Panoramica
Passinstance supporta l'orchestrazione multi-provider dei metodi di pagamento (Billing API su /api/v1/billing/payment-methods* e Impostazioni -> Fatturazione -> Metodo di pagamento su /settings/billing/payment-method), consentendo ai workspace di saldare abbonamenti e componenti aggiuntivi tramite payment method (CREDIT_CARD | PAYPAL | BANK_TRANSFER | GOOGLE_PAY | APPLE_PAY | STRIPE | CRYPTO | GIFT_CARD | MOBILE_MONEY) e tracciando i regolamenti tramite payment status (PENDING | COMPLETED | FAILED | CANCELLED | REFUNDED | PARTIALLY_REFUNDED | DISPUTED).
Per mantenere una rigorosa conformità PCI-DSS, Passinstance non trasmette né memorizza mai i numeri completi delle carte (PAN) o i codici di sicurezza CVV sui server della piattaforma: tutte le credenziali di pagamento sensibili vengono tokenizzate direttamente presso il processore di pagamento sottostante tramite handshake a due fasi SetupIntent / Setup-Token.
Architettura di tokenizzazione dei pagamenti multi-provider
Importante: Passinstance non entra mai in contatto con i numeri completi delle carte di credito o i codici CVV. Tutti i flussi di acquisizione delle carte utilizzano segreti client
SetupIntentdi Stripe con autenticazione forte del cliente (3D-Secure 2 / PSD2 SCA) eseguita nel browser prima che ilpaymentMethodIdsalvato nel vault venga confermato con l'API.
Circuiti di pagamento supportati ed endpoint
| Circuito di pagamento | Endpoint | Strumenti e valute supportati |
|---|---|---|
| Elenco dei metodi salvati | GET /api/v1/billing/payment-methods | Restituisce tutti i metodi di pagamento salvati nel vault associati al workspace, indicando isDefault, circuito/ultime 4 cifre della carta, stato di scadenza o identificativo PayPal/Mobile Money. |
| Carte Stripe e SEPA | POST /api/v1/billing/payment-methods/stripe/setup-intentPOST /api/v1/billing/payment-methods/stripe/confirm | Mandati Visa, Mastercard, American Express e addebito diretto SEPA con autenticazione completa 3D-Secure 2 (SCA) in EUR e USD. |
| Accordi di fatturazione PayPal | POST /api/v1/billing/payment-methods/paypal/setup-tokenPOST /api/v1/billing/payment-methods/paypal/confirm | Account aziendali o business PayPal salvati nel vault e autorizzati per la fatturazione ricorrente degli abbonamenti. |
| Mobile Money | POST /api/v1/billing/payment-methods/mobile-money | Circuiti di portafoglio mobile regionali (ad es. M-Pesa, MTN Mobile Money, Orange Money, Airtel Money) per i workspace dei mercati emergenti supportati. |
Guida API: registrazione e conferma dei metodi di pagamento
1. Elenco dei metodi di pagamento salvati (GET /api/v1/billing/payment-methods)
GET /api/v1/billing/payment-methods HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Payload di risposta (200 OK)
{
"paymentMethods": [
{
"id": "pm_019331f0-9988-7a11-8b22-334455667788",
"provider": "STRIPE",
"type": "CARD",
"brand": "visa",
"last4": "4242",
"expMonth": 8,
"expYear": 2029,
"isDefault": true,
"createdAt": "2026-01-15T10:12:00.000Z"
},
{
"id": "pm_01933205-4411-7c22-9d33-556677889900",
"provider": "PAYPAL",
"type": "PAYPAL_AGREEMENT",
"email": "billing@phenix-hospitality.example.com",
"isDefault": false,
"createdAt": "2026-06-20T14:05:11.000Z"
}
]
}
2. Registrazione della carta Stripe 3D-Secure in due fasi
Fase A: creare un SetupIntent di Stripe (POST /api/v1/billing/payment-methods/stripe/setup-intent)
POST /api/v1/billing/payment-methods/stripe/setup-intent HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"setupIntentId": "seti_1Q9xYz2eZvKYlo2C99887766",
"clientSecret": "seti_1Q9xYz2eZvKYlo2C99887766_secret_R1a2B3c4D5e6F7g8",
"publishableKey": "pk_live_51H..."
}
Fase B: confermare la carta salvata nel vault (POST /api/v1/billing/payment-methods/stripe/confirm)
Dopo che Stripe Elements ha completato l'eventuale verifica 3D-Secure 2 richiesta nel browser, passi request payload ({ setupIntentId, paymentMethodId }) per rendere persistente la carta nel Suo workspace:
POST /api/v1/billing/payment-methods/stripe/confirm HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"setupIntentId": "seti_1Q9xYz2eZvKYlo2C99887766",
"paymentMethodId": "pm_1Q9xZa2eZvKYlo2C11223344"
}
{
"id": "pm_01933240-7766-7b00-8c11-990011223344",
"provider": "STRIPE",
"type": "CARD",
"brand": "mastercard",
"last4": "8819",
"expMonth": 11,
"expYear": 2030,
"isDefault": true
}
3. Registrazione di accordi di fatturazione PayPal e Mobile Money
-
PayPal (
POST /api/v1/billing/payment-methods/paypal/setup-token->/confirm): invia{ returnUrl, cancelUrl }(request payload) per generare un token PayPal encrypted storage, quindi chiama/paypal/confirmcon{ setupTokenId }(request payload). -
Mobile Money (
POST /api/v1/billing/payment-methods/mobile-money): registra un circuito di portafoglio mobile utilizzandorequest payload({ provider, phoneNumber, currency?, note? }):
POST /api/v1/billing/payment-methods/mobile-money HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"provider": "MPESA",
"phoneNumber": "+254712345678",
"currency": "KES",
"note": "Primary Kenya operations billing number"
}
Documentazione correlata
-
Ritenti il pagamento delle fatture aperte e scarichi le ricevute in PDF in Fatture e cronologia di fatturazione.
-
Effettui l'upgrade o modifichi gli intervalli di fatturazione in Modifiche al piano e cancellazione.
-
Aggiorni gli indirizzi di fatturazione aziendale e i numeri di Partita IVA in Impostazioni aziendali.
