Overview
Passinstance supports multi-provider payment method orchestration (Billing API at /api/v1/billing/payment-methods* and Settings -> Billing -> Payment Method at /settings/billing/payment-method), enabling workspaces to settle subscriptions and add-ons across payment method (CREDIT_CARD | PAYPAL | BANK_TRANSFER | GOOGLE_PAY | APPLE_PAY | STRIPE | CRYPTO | GIFT_CARD | MOBILE_MONEY) and tracking settlements via payment status (PENDING | COMPLETED | FAILED | CANCELLED | REFUNDED | PARTIALLY_REFUNDED | DISPUTED).
To maintain strict PCI-DSS compliance, Passinstance never transmits or stores raw card numbers (PAN) or CVV security codes on platform servers—all sensitive payment credentials are tokenized directly with the underlying payment processor via two-step SetupIntent / Setup-Token handshakes.
Workspace Billing vs. Workspace Payment Integrations
It is essential to understand the distinction between the two types of payment configurations in Passinstance:
| Configuration Area | What It Governs | Supported Gateways | Where to Manage |
|---|---|---|---|
| Workspace Billing (This Article) | How your organization pays Passinstance for monthly subscription plans, custom SMTP add-ons, vanity domains, and Delivery Center sendout credits. | Stripe (Cards, SEPA), PayPal Billing Agreements, Mobile Money | Settings -> Billing -> Payment Method (/settings/billing/payment-method) |
| Workspace Payment Integrations | How your end-customers pay you when buying passes, event tickets, or memberships via public PassFlows. | Stripe (PaymentIntent), PayPal REST API (Orders v2), Paystack, MTN MoMo, Orange Money | Settings -> Integrations -> Payments (POST /payments/admin/:customerId/integrations) |
For complete documentation on collecting customer payments on your passes, see Selling Passes, Selling Subscriptions, and Requesting a PayPal API Signature.
Sendout Runtime Payment Gate (assertCustomerPaymentMethod)
Beyond subscription renewals, your workspace payment method plays a critical operational role in pass delivery. The system enforces an automated preflight check (assertCustomerPaymentMethod in sendout-runtime.gates.ts) before executing outbound email or SMS campaigns:
-
Active Billing Mandate Required: Automated transactional sendouts (such as pass delivery upon API creation, download page email requests, or Delivery Center campaigns) require an active, valid payment method on file or a positive credit balance.
-
Fail-Safe Mechanism: If an account's payment method expires or encounters billing failures, automated outbound delivery is paused to prevent unexpected carrier liabilities. The API raises
PaymentRequiredExceptionuntil the billing method is updated.
Delivery Credit Top-Up Workflow
Merchants utilizing email (€0.0005/email) or SMS (€0.03/SMS) sendouts can purchase prepaid delivery credit bundles:
-
1
Navigate to Delivery Center -> Credits (
/delivery-center). -
2
Click Top Up Balance (
POST /delivery/top-up). -
3
Select your desired credit package (€20, €50, €100, €500).
-
4
Settle the invoice instantly using your vaulted card or a new Stripe Checkout session.
Multi-Provider Payment Tokenization Architecture
Important: Passinstance never touches raw credit card numbers or CVV values. All card capture flows use Stripe
SetupIntentclient secrets with Strong Customer Authentication (3D-Secure 2 / PSD2 SCA) enforced in the browser before the vaultedpaymentMethodIdis confirmed with the API.
Supported Payment Rails & Endpoints
| Payment Rail | Endpoints | Supported Instruments & Currencies |
|---|---|---|
| List Saved Methods | GET /api/v1/billing/payment-methods | Returns all vaulted payment methods attached to the workspace, indicating isDefault, card brand/last4, expiration status, or PayPal/Mobile Money identifier. |
| Stripe Cards & SEPA | POST /api/v1/billing/payment-methods/stripe/setup-intentPOST /api/v1/billing/payment-methods/stripe/confirm | Visa, Mastercard, American Express, and SEPA Direct Debit mandates with full 3D-Secure 2 (SCA) authentication in EUR and USD. |
| PayPal Billing Agreements | POST /api/v1/billing/payment-methods/paypal/setup-tokenPOST /api/v1/billing/payment-methods/paypal/confirm | Vaulted PayPal corporate or business accounts authorized for recurring subscription billing. |
| Mobile Money | POST /api/v1/billing/payment-methods/mobile-money | Regional mobile wallet rails (e.g., M-Pesa, MTN Mobile Money, Orange Money, Airtel Money) for supported emerging-market workspaces. |
API Walkthrough: Enrolling & Confirming Payment Methods
1. List Vaulted Payment Methods (GET /api/v1/billing/payment-methods)
GET /api/v1/billing/payment-methods HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Response Payload (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. Two-Step Stripe 3D-Secure Card Enrollment
Step A: Create a 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..."
}
Step B: Confirm the Vaulted Card (POST /api/v1/billing/payment-methods/stripe/confirm)
After Stripe Elements completes any required 3D-Secure 2 challenge in the browser, pass request payload ({ setupIntentId, paymentMethodId }) to persist the card for your 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. PayPal Billing Agreement & Mobile Money Enrollment
-
PayPal (
POST /api/v1/billing/payment-methods/paypal/setup-token->/confirm): Submits{ returnUrl, cancelUrl }(request payload) to generate a PayPal encrypted storage token, then calls/paypal/confirmwith{ setupTokenId }(request payload). -
Mobile Money (
POST /api/v1/billing/payment-methods/mobile-money): Registers a mobile wallet rail usingrequest 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"
}
Related Documentation
-
Selling Passes — Monetizing passes using workspace payment integrations.
-
Selling Subscriptions — Recurring memberships and pass expiration synchronization.
-
Requesting a PayPal API Signature — Connecting PayPal REST credentials for pass sales.
-
Invoices & Billing History — Retry open invoices and download PDF receipts.
-
Plan Changes & Cancellation — Upgrade or change subscription intervals.
