Payment Methods

PaymentMethod objects represent your customer’s payment instruments. You can use them with PaymentIntents to collect payments or save them to Customer objects to store instrument details for future payments.

Related guides: Payment Methods and More Payment Scenarios.

Endpoints

POST/v1/payment_methods

POST/v1/payment_methods/:id

GET/v1/customers/:id/payment_methods/:id

GET/v1/payment_methods/:id

GET/v1/customers/:id/payment_methods

GET/v1/payment_methods

POST/v1/payment_methods/:id/attach

POST/v1/payment_methods/:id/detach

The PaymentMethod object

Attributes

idstring
Unique identifier for the object.

billing_detailsMap
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.

customernullable stringExpandable
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.

metadatanullable Map
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.

typeenum

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.

Possible enum values

acss_debit

Pre-authorized debit payments are used to debit Canadian bank accounts through the Automated Clearing Settlement System (ACSS).

affirm

Affirm is a buy now, pay later payment method in the US.

afterpay_clearpay

Afterpay / Clearpay is a buy now, pay later payment method used in Australia, Canada, France, New Zealand, Spain, the UK, and the US.

alipay

Alipay is a digital wallet payment method used in China.

alma

Alma is a Buy Now, Pay Later payment method that lets customers pay in 2, 3, or 4 installments.

amazon_pay

Amazon Pay is a Wallet payment method that lets hundreds of millions of Amazon customers pay their way, every day.

au_becs_debit

BECS Direct Debit is used to debit Australian bank accounts through the Bulk Electronic Clearing System (BECS).

bacs_debit

Bacs Direct Debit is used to debit UK bank accounts.

bancontact

Bancontact is a bank redirect payment method used in Belgium.

billie

Billie is a payment method.

Show 79 more

More attributes

objectstring

acss_debitnullable Map

affirmnullable Map

afterpay_clearpaynullable Map

alipaynullable Map

allow_redisplaynullable enum

almanullable Map

amazon_paynullable Map

au_becs_debitnullable Map

bacs_debitnullable Map

bancontactnullable Map

billienullable Map

bliknullable Map

boletonullable Map

cardnullable Map

card_presentnullable Map

cashappnullable Map

createdtimestamp

customer_balancenullable Map

epsnullable Map

fpxnullable Map

giropaynullable Map

grabpaynullable Map

idealnullable Map

interac_presentnullable MapPreview feature

kakao_paynullable Map

klarnanullable Map

konbininullable Map

kr_cardnullable Map

linknullable Map

livemodeboolean

mobilepaynullable Map

multibanconullable Map

naver_paynullable Map

nz_bank_accountnullable Map

oxxonullable Map

p24nullable Map

pay_by_banknullable MapPreview feature

payconullable Map

paynownullable Map

paypalnullable Map

pixnullable Map

promptpaynullable Map

radar_optionsnullable Map

revolut_paynullable Map

samsung_paynullable Map

satispaynullable Map

sepa_debitnullable Map

sofortnullable Map

swishnullable Map

twintnullable Map

us_bank_accountnullable Map

wechat_paynullable Map

zipnullable Map

The PaymentMethod object

{
  "id": "pm_1Q0PsIJvEtkwdCNYMSaVuRz6",
  "object": "payment_method",
  "allow_redisplay": "unspecified",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": null,
    "name": "John Doe",
    "phone": null
  },
  "created": 1726673582,
  "customer": null,
  "livemode": false,
  "metadata": {},
  "type": "us_bank_account",
  "us_bank_account": {
    "account_holder_type": "individual",
    "account_type": "checking",
    "bank_name": "STRIPE TEST BANK",
    "financial_connections_account": null,
    "fingerprint": "LstWJFsCK7P349Bg",
    "last4": "6789",
    "networks": {
      "preferred": "ach",
      "supported": [
        "ach"
      ]
    },
    "routing_number": "110000000",
    "status_details": {}
  }
}

Create a PaymentMethod

Creates a PaymentMethod object. Read the Stripe.js reference to learn how to create PaymentMethods via Stripe.js.

Instead of creating a PaymentMethod directly, we recommend using the PaymentIntents API to accept a payment immediately or the SetupIntent API to collect payment method details ahead of a future payment.

Parameters

typeenumRequired

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.

Possible enum values

acss_debit

Pre-authorized debit payments are used to debit Canadian bank accounts through the Automated Clearing Settlement System (ACSS).

affirm

Affirm is a buy now, pay later payment method in the US.

afterpay_clearpay

Afterpay / Clearpay is a buy now, pay later payment method used in Australia, Canada, France, New Zealand, Spain, the UK, and the US.

alipay

Alipay is a digital wallet payment method used in China.

alma

Alma is a Buy Now, Pay Later payment method that lets customers pay in 2, 3, or 4 installments.

amazon_pay

Amazon Pay is a Wallet payment method that lets hundreds of millions of Amazon customers pay their way, every day.

au_becs_debit

BECS Direct Debit is used to debit Australian bank accounts through the Bulk Electronic Clearing System (BECS).

bacs_debit

Bacs Direct Debit is used to debit UK bank accounts.

bancontact

Bancontact is a bank redirect payment method used in Belgium.

billie

Billie is a payment method.

Show 78 more

billing_detailsMap
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.

metadataMap
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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

More parameters

acss_debitMap

affirmMap

afterpay_clearpayMap

alipayMap

allow_redisplayenum

almaMap

amazon_payMap

au_becs_debitMap

bacs_debitMap

bancontactMap

billieMap

blikMap

boletoMap

cardMap

cashappMap

customer_balanceMap

epsMap

fpxMap

giropayMap

grabpayMap

idealMap

interac_presentMapPreview feature

kakao_payMap

klarnaMap

konbiniMap

kr_cardMap

linkMap

mobilepayMap

multibancoMap

naver_payMap

nz_bank_accountMap

oxxoMap

p24Map

pay_by_bankMapPreview feature

paycoMap

paynowMap

paypalMap

pixMap

promptpayMap

radar_optionsMap

revolut_payMap

samsung_payMap

satispayMap

sepa_debitMap

sofortMap

swishMap

twintMap

us_bank_accountMap

wechat_payMap

zipMap

Returns

Returns a PaymentMethod object.

POST /v1/payment_methods

Server-side language

Stripe.apiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
PaymentMethodCreateParams params =
  PaymentMethodCreateParams.builder()
    .setType(PaymentMethodCreateParams.Type.US_BANK_ACCOUNT)
    .setUsBankAccount(
      PaymentMethodCreateParams.UsBankAccount.builder()
        .setAccountHolderType(
          PaymentMethodCreateParams.UsBankAccount.AccountHolderType.INDIVIDUAL
        )
        .setAccountNumber("000123456789")
        .setRoutingNumber("110000000")
        .build()
    )
    .setBillingDetails(
      PaymentMethodCreateParams.BillingDetails.builder().setName("John Doe").build()
    )
    .build();
PaymentMethod paymentMethod = PaymentMethod.create(params);

Response

{
  "id": "pm_1Q0PsIJvEtkwdCNYMSaVuRz6",
  "object": "payment_method",
  "allow_redisplay": "unspecified",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": null,
    "name": "John Doe",
    "phone": null
  },
  "created": 1726673582,
  "customer": null,
  "livemode": false,
  "metadata": {},
  "type": "us_bank_account",
  "us_bank_account": {
    "account_holder_type": "individual",
    "account_type": "checking",
    "bank_name": "STRIPE TEST BANK",
    "financial_connections_account": null,
    "fingerprint": "LstWJFsCK7P349Bg",
    "last4": "6789",
    "networks": {
      "preferred": "ach",
      "supported": [
        "ach"
      ]
    },
    "routing_number": "110000000",
    "status_details": {}
  }
}

Update a PaymentMethod

Updates a PaymentMethod object. A PaymentMethod must be attached a customer to be updated.

Parameters

billing_detailsMap
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.

metadataMap
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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

More parameters

allow_redisplayenum

cardMap

linkMap

pay_by_bankMapPreview feature

us_bank_accountMap

Returns

Returns a PaymentMethod object.

POST /v1/payment_methods/:id

Server-side language

Stripe.apiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
PaymentMethod resource = PaymentMethod.retrieve("pm_1Q0PsIJvEtkwdCNYMSaVuRz6");
PaymentMethodUpdateParams params =
  PaymentMethodUpdateParams.builder().putMetadata("order_id", "6735").build();
PaymentMethod paymentMethod = resource.update(params);

Response

{
  "id": "pm_1Q0PsIJvEtkwdCNYMSaVuRz6",
  "object": "payment_method",
  "allow_redisplay": "unspecified",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": null,
    "name": "John Doe",
    "phone": null
  },
  "created": 1726673582,
  "customer": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "type": "us_bank_account",
  "us_bank_account": {
    "account_holder_type": "individual",
    "account_type": "checking",
    "bank_name": "STRIPE TEST BANK",
    "financial_connections_account": null,
    "fingerprint": "LstWJFsCK7P349Bg",
    "last4": "6789",
    "networks": {
      "preferred": "ach",
      "supported": [
        "ach"
      ]
    },
    "routing_number": "110000000",
    "status_details": {}
  }
}

Retrieve a Customer's PaymentMethod

Retrieves a PaymentMethod object for a given Customer.

Parameters

No parameters.

Returns

Returns a PaymentMethod object.

GET /v1/customers/:id/payment_methods/:id

Server-side language

Stripe.apiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
Customer resource =
  Customer.retrieve("cus_9s6XKzkNRiz8i3", "pm_1NVChw2eZvKYlo2CHxiM5E2E");
CustomerRetrievePaymentMethodParams params =
  CustomerRetrievePaymentMethodParams.builder().build();
PaymentMethod paymentMethod = resource.retrievePaymentMethod(params);

Response

{
  "id": "pm_1NVChw2eZvKYlo2CHxiM5E2E",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": null,
    "name": null,
    "phone": null
  },
  "card": {
    "brand": "visa",
    "checks": {
      "address_line1_check": null,
      "address_postal_code_check": null,
      "cvc_check": "pass"
    },
    "country": "US",
    "exp_month": 12,
    "exp_year": 2034,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "funding": "credit",
    "generated_from": null,
    "last4": "4242",
    "networks": {
      "available": [
        "visa"
      ],
      "preferred": null
    },
    "three_d_secure_usage": {
      "supported": true
    },
    "wallet": null
  },
  "created": 1689682128,
  "customer": "cus_9s6XKzkNRiz8i3",
  "livemode": false,
  "metadata": {},
  "redaction": null,
  "type": "card"
}

Payment Methods

The PaymentMethod object

Attributes

idstring

billing_detailsMap

customernullable stringExpandable

metadatanullable Map

typeenum

More attributesExpand all

objectstring

acss_debitnullable Map

affirmnullable Map

afterpay_clearpaynullable Map

alipaynullable Map

allow_redisplaynullable enum

almanullable Map

amazon_paynullable Map

au_becs_debitnullable Map

bacs_debitnullable Map

bancontactnullable Map

billienullable Map

bliknullable Map

boletonullable Map

cardnullable Map

card_presentnullable Map

cashappnullable Map

createdtimestamp

customer_balancenullable Map

epsnullable Map

fpxnullable Map

giropaynullable Map

grabpaynullable Map

idealnullable Map

interac_presentnullable MapPreview feature

kakao_paynullable Map

klarnanullable Map

konbininullable Map

kr_cardnullable Map

linknullable Map

livemodeboolean

mobilepaynullable Map

multibanconullable Map

naver_paynullable Map

nz_bank_accountnullable Map

oxxonullable Map

p24nullable Map

pay_by_banknullable MapPreview feature

payconullable Map

paynownullable Map

paypalnullable Map

pixnullable Map

promptpaynullable Map

radar_optionsnullable Map

revolut_paynullable Map

samsung_paynullable Map

satispaynullable Map

sepa_debitnullable Map

sofortnullable Map

swishnullable Map

twintnullable Map

us_bank_accountnullable Map

wechat_paynullable Map

zipnullable Map

Create a PaymentMethod

Parameters

typeenumRequired

billing_detailsMap

metadataMap

More parametersExpand all

acss_debitMap

affirmMap

afterpay_clearpayMap

alipayMap

allow_redisplayenum

almaMap

amazon_payMap

au_becs_debitMap

bacs_debitMap

bancontactMap

billieMap

More attributes

More parameters

More parameters