Skip to content
Guida del Centro assistenza · Fatturazione e pagamenti
3 min di letturaVerificato 2026-11-16

Metodi di pagamento

Aggiorna carte o mandati SEPA in sicurezza tramite il Portale Clienti Stripe integrato.

In questa guida

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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
ORCHESTRAZIONE DEI METODI DI PAGAMENTO MULTI-PROVIDER
FASE 01 AMMINISTRATORE DELLA FATTURAZIONE DEL WORKSPACE
Seleziona il circuito: Carta Stripe (3DS2) | Accordo PayPal | Mobile Money
FASE 02 ENDPOINT DI ORCHESTRAZIONE DEI PAGAMENTI (Billing API)
Stripe 3D-Secure
`POST/payment-methods
/stripe/setup-intent`
Il client completa 3DS2`POST/payment-methods
/stripe/confirm`
encrypted storage PayPal
`POST/payment-methods
/paypal/setup-token`
L'utente approva mand.`POST/payment-methods
/paypal/confirm`
xpress | | Mobile Mo
regionalePOST/payment- methods/mobile- money
Verifica mandato telefono / OTP
FASE 03 REGISTRO DEI METODI DI PAGAMENTO SALVATI (GET/payment-methods)
Conserva solo metadati non sensibili (Circuito, ultime 4 cifre, scadenza, ecc.)
Utilizzato automaticamente per i rinnovi e per POST/invoices/:id/pay

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 SetupIntent di Stripe con autenticazione forte del cliente (3D-Secure 2 / PSD2 SCA) eseguita nel browser prima che il paymentMethodId salvato nel vault venga confermato con l'API.

Circuiti di pagamento supportati ed endpoint

Circuito di pagamentoEndpointStrumenti e valute supportati
Elenco dei metodi salvatiGET /api/v1/billing/payment-methodsRestituisce 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 SEPAPOST /api/v1/billing/payment-methods/stripe/setup-intentPOST /api/v1/billing/payment-methods/stripe/confirmMandati Visa, Mastercard, American Express e addebito diretto SEPA con autenticazione completa 3D-Secure 2 (SCA) in EUR e USD.
Accordi di fatturazione PayPalPOST /api/v1/billing/payment-methods/paypal/setup-tokenPOST /api/v1/billing/payment-methods/paypal/confirmAccount aziendali o business PayPal salvati nel vault e autorizzati per la fatturazione ricorrente degli abbonamenti.
Mobile MoneyPOST /api/v1/billing/payment-methods/mobile-moneyCircuiti 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)

HTTP
GET /api/v1/billing/payment-methods HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>

Payload di risposta (200 OK)

JSON
{
  "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)

HTTP
POST /api/v1/billing/payment-methods/stripe/setup-intent HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "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:

HTTP
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"
}
JSON
{
  "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/confirm con { setupTokenId } (request payload).
  • Mobile Money (POST /api/v1/billing/payment-methods/mobile-money): registra un circuito di portafoglio mobile utilizzando request payload ({ provider, phoneNumber, currency?, note? }):
HTTP
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

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.