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_gateway is 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)