Skip to content
Help Center Guide · Billing & Payments
4 min readVerified 2026-11-16

Payment Methods

Update credit/debit cards or SEPA/supported payment instruments securely through the Stripe Customer Portal.

In This Guide

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 AreaWhat It GovernsSupported GatewaysWhere 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 MoneySettings -> Billing -> Payment Method (/settings/billing/payment-method)
Workspace Payment IntegrationsHow 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 MoneySettings -> 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 PaymentRequiredException until 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. 1
    Navigate to Delivery Center -> Credits (/delivery-center).
  2. 2
    Click Top Up Balance (POST /delivery/top-up).
  3. 3
    Select your desired credit package (€20, €50, €100, €500).
  4. 4
    Settle the invoice instantly using your vaulted card or a new Stripe Checkout session.

Multi-Provider Payment Tokenization Architecture

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
MULTI-PROVIDER PAYMENT METHOD ORCHESTRATION
STAGE 01 WORKSPACE BILLING ADMIN (CLIENT)
Selects Payment Rail: Stripe Card (3DS2) | PayPal Agreement | Mobile Money
STAGE 02 PAYMENT ORCHESTRATION ENDPOINTS (Billing API)
Stripe 3D-Secure
`POST/payment-methods
/stripe/setup-intent`
Client Completes 3DS2`POST/payment-methods
/stripe/confirm`
PayPal Saved Billing
`POST/payment-methods
/paypal/setup-token`
Buyer Approves Mandate`POST/payment-methods
/paypal/confirm`
Regional Mobile
MoneyPOST/payment- methods/mobile- money
Phone / OTP Mandate
Verification
STAGE 03 VAULTED PAYMENT METHOD REGISTRY (GET/payment-methods)
Stores Non-Sensitive Metadata Only (Brand, Last4, Expiry, PayPal Email, Default)
Enforces assertCustomerPaymentMethod for Delivery Center Sendouts
Used Automatically for Subscription Renewals & POST/invoices/:id/pay

Important: Passinstance never touches raw credit card numbers or CVV values. All card capture flows use Stripe SetupIntent client secrets with Strong Customer Authentication (3D-Secure 2 / PSD2 SCA) enforced in the browser before the vaulted paymentMethodId is confirmed with the API.


Supported Payment Rails & Endpoints

Payment RailEndpointsSupported Instruments & Currencies
List Saved MethodsGET /api/v1/billing/payment-methodsReturns all vaulted payment methods attached to the workspace, indicating isDefault, card brand/last4, expiration status, or PayPal/Mobile Money identifier.
Stripe Cards & SEPAPOST /api/v1/billing/payment-methods/stripe/setup-intentPOST /api/v1/billing/payment-methods/stripe/confirmVisa, Mastercard, American Express, and SEPA Direct Debit mandates with full 3D-Secure 2 (SCA) authentication in EUR and USD.
PayPal Billing AgreementsPOST /api/v1/billing/payment-methods/paypal/setup-tokenPOST /api/v1/billing/payment-methods/paypal/confirmVaulted PayPal corporate or business accounts authorized for recurring subscription billing.
Mobile MoneyPOST /api/v1/billing/payment-methods/mobile-moneyRegional 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)

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

Response Payload (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. Two-Step Stripe 3D-Secure Card Enrollment

Step A: Create a Stripe SetupIntent (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..."
}

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:

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. 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/confirm with { setupTokenId } (request payload).
  • Mobile Money (POST /api/v1/billing/payment-methods/mobile-money): Registers a mobile wallet rail using 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"
}

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.