Payment methods

payment-methods

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

1. During checkout: when a customer pays through the hosted checkout, their payment details are tokenised and saved
2. Via the Create Payment API: pass card or bank details in the payment_method object and they’re tokenised inline
3. 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.

Operations

GET

/payment_methods

POST

/payment_methods

GET

/payment_methods/{payment_method_id}

PUT

/payment_methods/{payment_method_id}

DELETE

/payment_methods/{payment_method_id}