A payment method is a tokenised payment instrument — a card, bank account, or other payment type — belonging to an account. Shuttle never stores sensitive payment data; only gateway tokens and masked identifiers (like the last 4 digits of a card).
How Payment Methods Are Created
- During checkout: when a customer pays through the hosted checkout, their payment details are tokenised and saved
- Via the Create Payment API: pass card or bank details in the
payment_methodobject and they're tokenised inline - Directly via this API: for advanced use cases like data migration or importing tokens from another system
Supported Types
Payment methods vary by gateway, but commonly include:
- Cards: VISA, Mastercard, AMEX, Discover, JCB, Diners
- Bank accounts: ACH (US), SEPA (Europe), BACS (UK), BECS (Australia)
- Wallets: PayPal, Apple Pay, Google Pay
Status Lifecycle
| Status | Description |
|---|---|
ACTIVE | Tokenised and available for use — last known state was working |
FAILING | Tokenised and available but last payment attempt failed |
FAILED | Automatically archived after repeated failures |
ARCHIVE | Manually archived (soft deleted) |
EXPIRED | Past its expiry date |
SINGLEUSE | One-time token for a single payment, not saved |
REQAUTH | Requires 3DS completion before it can be used |
Gateway Groups
Some processors support payment method sharing across multiple gateway connections via gateway_group. When present, a payment method tokenised on one gateway can be used across any gateway that shares the same group. This is processor-specific.