Sample - Stripe API
POST/v1/payment_methods/{payment_method}/attach

Attach a PaymentMethod to a customer

Attaches a PaymentMethod to a customer for use with payments or future payment setup. Supply either customer or customer_account to identify the customer association, and use expand to request additional response fields. For future payments, prefer a SetupIntent or a PaymentIntent configured with setup-future-usage behavior.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 3 body fields
payment_methodstringrequired
The unique identifier of the PaymentMethod to attach. Maximum 5000 characters.

Customer association and response-expansion options for attaching a PaymentMethod.

customerstringoptional
The ID of the customer to which to attach the PaymentMethod.
customer_accountstringoptional
The ID of the Account representing the customer to which to attach the PaymentMethod.
expandarray<string>optional
Specifies which fields in the response should be expanded.

2 status codes
200Returns the attached PaymentMethod, including its customer payment details, identifier, type, billing details, and current attachment state.
acss_debitobjectoptional
affirmobjectoptional
afterpay_clearpayobjectoptional
alipayobjectoptional
allow_redisplaystringoptional
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”.
Allowed:alwayslimitedunspecified
almaobjectoptional
amazon_payobjectoptional
au_becs_debitobjectoptional
bacs_debitobjectoptional
bancontactobjectoptional
billieobjectoptional
billing_detailsobjectrequired
bizumobjectoptional
blikobjectoptional
boletoobjectoptional
cardobjectoptional
card_presentobjectoptional
cashappobjectoptional
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
cryptoobjectoptional
customobjectoptional
customerstringoptional
The ID of the Customer to which this PaymentMethod is saved. This will not be set when the PaymentMethod has not been saved to a Customer.
customer_accountstringoptional
customer_balanceobjectoptional
epsobjectoptional
fpxobjectoptional
giropayobjectoptional
grabpayobjectoptional
idstringrequired
Unique identifier for the object.
idealobjectoptional
interac_presentobjectoptional
kakao_payobjectoptional
klarnaobjectoptional
konbiniobjectoptional
kr_cardobjectoptional
linkobjectoptional
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
mb_wayobjectoptional
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
mobilepayobjectoptional
multibancoobjectoptional
naver_payobjectoptional
nz_bank_accountobjectoptional
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:payment_method
oxxoobjectoptional
p24objectoptional
pay_by_bankobjectoptional
paycoobjectoptional
paynowobjectoptional
paypalobjectoptional
paytoobjectoptional
pixobjectoptional
promptpayobjectoptional
radar_optionsobjectoptional
Options to configure Radar. See [Radar Session](https://docs.stripe.com/radar/radar-session) for more information.
revolut_payobjectoptional
samsung_payobjectoptional
satispayobjectoptional
scalapayobjectoptional
sepa_debitobjectoptional
sofortobjectoptional
sunbitobjectoptional
swishobjectoptional
twintobjectoptional
typestringrequired
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.
Allowed:acss_debitaffirmafterpay_clearpayalipayalmaamazon_payau_becs_debitbacs_debitbancontactbilliebizumblik
upiobjectoptional
us_bank_accountobjectoptional
wechat_payobjectoptional
zipobjectoptional
defaultError response.
errorobjectrequired

Error handling

payment_method must identify the PaymentMethod to attach and must not exceed 5000 characters. Provide the customer identifier through customer or customer_account, and ensure each expand value does not exceed 5000 characters.