Manage customer payment methods including credit cards and bank accounts.
Overview
Payment methods represent stored payment instruments for customers. They are used to charge customers for subscriptions and one-time purchases.
How It Works
- Collect payment details — Customer enters card information via your checkout
- Tokenize securely — Payment details are tokenized by the payment gateway
- Create payment method — The token is saved and attached to the customer
- Charge automatically — Future payments use the stored payment method
Example: A customer enters their Visa card during checkout. The card is tokenized by Stripe, stored as a payment method, and used to pay for their monthly subscription automatically.
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | List payment methods | Retrieve a paginated list of payment methods |
POST | Create payment method | Attach a new payment method to a customer |
GET | Get payment method | Retrieve a specific payment method |
DELETE | Delete payment method | Remove a payment method |
Important Behaviors
- Soft delete: Payment methods are soft-deleted, not permanently removed.
- Subscription guard: Cannot delete a payment method that is associated with an active subscription.
- Auto-default: When a new payment method is created, it is automatically set as the customer's default.
- Billing auto-update: Creating a payment method switches the customer's subscriptions to charge automatically using the new default source.
- Max 10 per customer: A customer can have at most 10 payment methods.
- Gateway auto-detect: If
object_gatewayis omitted on create, the account's active payment gateway is used.
Supported Payment Method Types
The brand field in the response identifies the payment method type:
| Type | brand value | Description |
|---|---|---|
| Credit/Debit Card | Visa, Mastercard, Amex, etc. | Standard card payments |
| BACS Direct Debit | bacs_debit | UK bank direct debit |
| US Bank Account (ACH) | us_bank_account | US bank account transfers |
| PayPal | paypal | PayPal payments |
Supported Gateways
| Gateway | Description |
|---|---|
stripe | Primary payment processor |
tap | Middle East payment gateway |
vantiv | Enterprise payment processing |
cybersource | Enterprise payment processing |
braintree | PayPal/Braintree payments |
Payment Method Object
| Attribute | Type | Description |
|---|---|---|
id | integer | Unique identifier |
object_gateway | string | Payment gateway (stripe, tap, vantiv, etc.) |
object_id | string | Payment gateway's token/source ID |
brand | string|null | Payment method type: card brand (Visa, Mastercard), or bacs_debit, us_bank_account, paypal |
last4 | string|null | Last 4 digits of the card or account |
exp_month | string|null | Card expiration month |
exp_year | string|null | Card expiration year |
cvc_check | string|null | CVC verification result |
address_zip_check | string|null | Postal code verification result |
address_line1_check | string|null | Address verification result |
funding | string|null | Card funding type: credit, debit, prepaid |
country | string|null | Two-letter ISO country code of card issuer |
fingerprint | string|null | Unique card fingerprint for duplicate detection |
three_d_secure | string|null | 3D Secure status |
name | string|null | Cardholder name |
tokenization_method | string|null | How card was tokenized (apple_pay, google_pay) |
dynamic_last4 | string|null | Dynamic last 4 digits (for mobile wallets) |