Attach a PaymentMethod to a Customer

Changed on

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

Request

  • Base URL: https://api.stripe.com
  • URL: https://api.stripe.com/v1/payment_methods/{payment_method}/attach
  • Auth: one of:
    • HTTP basic
    • HTTP bearer

Path parameters

payment_methodstring required

Request body application/x-www-form-urlencoded

customerstring

The ID of the customer to which to attach the PaymentMethod.

customer_accountstring

The ID of the Account representing the customer to which to attach the PaymentMethod.

expandstring[]

Specifies which fields in the response should be expanded.

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
paypayPaymentMethodPaypay
promptpayPaymentMethodPromptpay
revolut_payPaymentMethodRevolutPay
samsung_payPaymentMethodSamsungPay
satispayPaymentMethodSatispay
scalapayPaymentMethodScalapay
sequraPaymentMethodSequra
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' | 'paypay' | 'payto' | 'pix' | 'promptpay' | 'revolut_pay' | 'samsung_pay' | 'satispay' | 'scalapay' | 'sepa_debit' | 'sequra' | '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

Changes

  • c113b1939b8fRevision changes
    • info

      added the optional property //////////// to the response with the status

    • info

      added the optional property ////// to the response with the status

    • info

      added the optional property //////////// to the response with the status

  • 7b8f614372caRevision changes
    • info

      added the optional property //////////////// to the response with the status

    • info

      added the optional property ////////// to the response with the status

    • info

      added the optional property //////////////// to the response with the status

Some revisions have not been checked yet.