Sign in

v52

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-015891,4406.1 MB

Attach a PaymentMethod to a Customer

Attaches a PaymentMethod object to a Customer.

To attach a new PaymentMethod to a customer for future payments, we recommend you use a SetupIntent or a PaymentIntent with setup_future_usage. These approaches will perform any necessary steps to set up the PaymentMethod for future payments. Using the /v1/payment_methods/:id/attach endpoint without first using a SetupIntent or PaymentIntent with setup_future_usage does not optimize the PaymentMethod for future use, which makes later declines and payment friction more likely. See Optimizing cards for future payments for more information about setting up future payments.

To use this PaymentMethod as the default for invoice or subscription payments, set invoice_settings.default_payment_method, on the Customer to the PaymentMethod’s ID.

post/v1/payment_methods/{payment_method}/attach

Path parameters

payment_methodstring required

Response

Successful response.

affirmPaymentMethodAffirm
afterpay_clearpayPaymentMethodAfterpayClearpay
alipayPaymentFlowsPrivatePaymentMethodsAlipay
allow_redisplay'always' | 'limited' | 'unspecified'

This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to “unspecified”.

almaPaymentMethodAlma
amazon_payPaymentMethodAmazonPay
bancontactPaymentMethodBancontact
billiePaymentMethodBillie
createdinteger required

Time at which the object was created. Measured in seconds since the Unix epoch.

cryptoPaymentMethodCrypto
customer_accountstring nullable
customer_balancePaymentMethodCustomerBalance
giropayPaymentMethodGiropay
grabpayPaymentMethodGrabpay
idstring required

Unique identifier for the object.

kakao_payPaymentMethodKakaoPay
konbiniPaymentMethodKonbini
livemodeboolean required

If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.

mb_wayPaymentMethodMbWay
metadataobject nullable

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

mobilepayPaymentMethodMobilepay
multibancoPaymentMethodMultibanco
object'payment_method' required

String representing the object's type. Objects of the same type share the same value.

oxxoPaymentMethodOxxo
pay_by_bankPaymentMethodPayByBank
paycoPaymentMethodPayco
paynowPaymentMethodPaynow
promptpayPaymentMethodPromptpay
revolut_payPaymentMethodRevolutPay
samsung_payPaymentMethodSamsungPay
satispayPaymentMethodSatispay
scalapayPaymentMethodScalapay
sunbitPaymentMethodSunbit
swishPaymentMethodSwish
twintPaymentMethodTwint
type'acss_debit' | 'affirm' | 'afterpay_clearpay' | 'alipay' | 'alma' | 'amazon_pay' | 'au_becs_debit' | 'bacs_debit' | 'bancontact' | 'billie' | 'bizum' | 'blik' | 'boleto' | 'card' | 'card_present' | 'cashapp' | 'crypto' | 'custom' | 'customer_balance' | 'eps' | 'fpx' | 'giropay' | 'grabpay' | 'ideal' | 'interac_present' | 'kakao_pay' | 'klarna' | 'konbini' | 'kr_card' | 'link' | 'mb_way' | 'mobilepay' | 'multibanco' | 'naver_pay' | 'nz_bank_account' | 'oxxo' | 'p24' | 'pay_by_bank' | 'payco' | 'paynow' | 'paypal' | 'payto' | 'pix' | 'promptpay' | 'revolut_pay' | 'samsung_pay' | 'satispay' | 'scalapay' | 'sepa_debit' | 'sofort' | 'sunbit' | 'swish' | 'twint' | 'upi' | 'us_bank_account' | 'wechat_pay' | 'zip' required

The type of the PaymentMethod. An additional hash is included on the PaymentMethod with a name matching this value. It contains additional information specific to the PaymentMethod type.

wechat_payPaymentMethodWechatPay
zipPaymentMethodZip