Overzicht
Passinstance ondersteunt orkestratie van betaalmethoden via meerdere aanbieders (Billing API op /api/v1/billing/payment-methods* en Instellingen -> Facturatie -> Betaalmethode op /settings/billing/payment-method), zodat werkruimtes abonnementen en add-ons kunnen afrekenen over payment method (CREDIT_CARD | PAYPAL | BANK_TRANSFER | GOOGLE_PAY | APPLE_PAY | STRIPE | CRYPTO | GIFT_CARD | MOBILE_MONEY) en betalingen volgen via payment status (PENDING | COMPLETED | FAILED | CANCELLED | REFUNDED | PARTIALLY_REFUNDED | DISPUTED).
Om strikte PCI-DSS-naleving te waarborgen verstuurt of bewaart Passinstance nooit volledige kaartnummers (PAN) of CVV-beveiligingscodes op platformservers—alle gevoelige betaalgegevens worden rechtstreeks bij de betalingsverwerker getokeniseerd via tweedelige SetupIntent / Setup-Token-handshakes.
Architectuur voor multi-provider betaaltokenisatie
Belangrijk: Passinstance raakt nooit ruwe creditcardnummers of CVV-waarden aan. Alle kaartregistraties gebruiken Stripe
SetupIntentclient secrets waarbij Strong Customer Authentication (3D-Secure 2 / PSD2 SCA) in de browser wordt afgedwongen voordat depaymentMethodIdbij de API wordt bevestigd.
Ondersteunde betaalsporen & endpoints
| Betaalspoor | Endpoints | Ondersteunde instrumenten & valuta |
|---|---|---|
| Opgeslagen methoden tonen | GET /api/v1/billing/payment-methods | Retourneert alle opgeslagen betaalmethoden van de werkruimte met isDefault, kaartmerk/laatste 4 cijfers, vervaldatum of PayPal-/Mobile Money-aanduiding. |
| Stripe-kaarten & SEPA | POST /api/v1/billing/payment-methods/stripe/setup-intentPOST /api/v1/billing/payment-methods/stripe/confirm | Visa, Mastercard, American Express en SEPA-incassomachtigingen met volledige 3D-Secure 2 (SCA)-authenticatie in EUR en USD. |
| PayPal-machtigingen | POST /api/v1/billing/payment-methods/paypal/setup-tokenPOST /api/v1/billing/payment-methods/paypal/confirm | Zakelijke PayPal-accounts geautoriseerd voor terugkerende abonnementsfacturatie. |
| Mobile Money | POST /api/v1/billing/payment-methods/mobile-money | Regionale mobiele betaalnetwerken (bijv. M-Pesa, MTN Mobile Money, Orange Money, Airtel Money) voor ondersteunde markten. |
API-uitleg: betaalmethoden registreren en bevestigen
1. Opgeslagen betaalmethoden ophalen (GET /api/v1/billing/payment-methods)
GET /api/v1/billing/payment-methods HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Antwoordpayload (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. Tweestaps Stripe 3D-Secure kaartregistratie
Stap A: Maak een Stripe SetupIntent (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..."
}
Stap B: Bevestig de opgeslagen kaart (POST /api/v1/billing/payment-methods/stripe/confirm)
Nadat Stripe Elements een vereiste 3D-Secure 2-controle in de browser heeft voltooid, geeft u request payload ({ setupIntentId, paymentMethodId }) door om de kaart op te slaan:
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. PayPal-facturatieovereenkomst & Mobile Money-registratie
-
PayPal (
POST /api/v1/billing/payment-methods/paypal/setup-token->/confirm): Stuurt{ returnUrl, cancelUrl }(request payload) om een PayPal-kluistoken aan te maken en roept daarna/paypal/confirmaan met{ setupTokenId }(request payload). -
Mobile Money (
POST /api/v1/billing/payment-methods/mobile-money): Registreert een mobiele wallet-lijn viarequest 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"
}
Gerelateerde documentatie
-
Probeer openstaande facturen opnieuw en download PDF-kwitanties in Facturen & facturatiegeschiedenis.
-
Upgrade pakketten of wijzig facturatie-intervallen in Abonnementwijzigingen & opzegging.
-
Werk zakelijke factuuradressen en btw-nummers bij in Bedrijfsinstellingen.
