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_detailshash
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 hash
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 40 more

More attributes

objectstring

acss_debitnullable hash

affirmnullable hash

afterpay_clearpaynullable hash

alipaynullable hash

allow_redisplaynullable enum

almanullable hash

amazon_paynullable hash

au_becs_debitnullable hash

bacs_debitnullable hash

bancontactnullable hash

billienullable hash

bliknullable hash

boletonullable hash

cardnullable hash

card_presentnullable hash

cashappnullable hash

createdtimestamp

cryptonullable hash

customer_balancenullable hash

epsnullable hash

fpxnullable hash

giropaynullable hash

grabpaynullable hash

idealnullable hash

interac_presentnullable hashPreview feature

kakao_paynullable hash

klarnanullable hash

konbininullable hash

kr_cardnullable hash

latest_active_mandatenullable hashPreview feature

linknullable hash

livemodeboolean

mobilepaynullable hash

multibanconullable hash

naver_paynullable hash

nz_bank_accountnullable hash

oxxonullable hash

p24nullable hash

pay_by_banknullable hash

payconullable hash

paynownullable hash

paypalnullable hash

pixnullable hash

promptpaynullable hash

radar_optionsnullable hash

revolut_paynullable hash

samsung_paynullable hash

satispaynullable hash

sepa_debitnullable hash

sofortnullable hash

swishnullable hash

twintnullable hash

us_bank_accountnullable hash

wechat_paynullable hash

zipnullable hash

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 40 more

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

metadatahash
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_debithash

affirmhash

afterpay_clearpayhash

alipayhash

allow_redisplayenum

almahash

amazon_payhash

au_becs_debithash

bacs_debithash

bancontacthash

billiehash

blikhash

boletohash

cardhash

cashapphash

cryptohash

customer_balancehash

epshash

fpxhash

giropayhash

grabpayhash

idealhash

interac_presenthashPreview feature

kakao_payhash

klarnahash

konbinihash

kr_cardhash

linkhash

mobilepayhash

multibancohash

naver_payhash

nz_bank_accounthash

oxxohash

p24hash

pay_by_bankhash

paycohash

paynowhash

paypalhash

pixhash

promptpayhash

radar_optionshash

revolut_payhash

samsung_payhash

satispayhash

sepa_debithash

soforthash

swishhash

twinthash

us_bank_accounthash

wechat_payhash

ziphash

Returns

Returns a PaymentMethod object.

POST /v1/payment_methods

Server-side language

Stripe.api_key = 'sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2'
payment_method = Stripe::PaymentMethod.create({
  type: 'us_bank_account',
  us_bank_account: {
    account_holder_type: 'individual',
    account_number: '000123456789',
    routing_number: '110000000',
  },
  billing_details: {name: 'John Doe'},
})

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 to a customer to be updated.

Parameters

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

metadatahash
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

cardhash

linkhash

pay_by_bankhash

us_bank_accounthash

Returns

Returns a PaymentMethod object.

POST /v1/payment_methods/:id

Server-side language

Stripe.api_key = 'sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2'
payment_method = Stripe::PaymentMethod.update(
  'pm_1Q0PsIJvEtkwdCNYMSaVuRz6',
  {metadata: {order_id: '6735'}},
)

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.api_key = 'sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2'
payment_method = Stripe::Customer.retrieve_payment_method(
  'cus_9s6XKzkNRiz8i3',
  'pm_1NVChw2eZvKYlo2CHxiM5E2E',
)

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_detailshash

customernullable stringExpandable

metadatanullable hash

typeenum

More attributesExpand all

objectstring

acss_debitnullable hash

affirmnullable hash

afterpay_clearpaynullable hash

alipaynullable hash

allow_redisplaynullable enum

almanullable hash

amazon_paynullable hash

au_becs_debitnullable hash

bacs_debitnullable hash

bancontactnullable hash

billienullable hash

bliknullable hash

boletonullable hash

cardnullable hash

card_presentnullable hash

cashappnullable hash

createdtimestamp

cryptonullable hash

customer_balancenullable hash

epsnullable hash

fpxnullable hash

giropaynullable hash

grabpaynullable hash

idealnullable hash

interac_presentnullable hashPreview feature

kakao_paynullable hash

klarnanullable hash

konbininullable hash

kr_cardnullable hash

latest_active_mandatenullable hashPreview feature

linknullable hash

livemodeboolean

mobilepaynullable hash

multibanconullable hash

naver_paynullable hash

nz_bank_accountnullable hash

oxxonullable hash

p24nullable hash

pay_by_banknullable hash

payconullable hash

paynownullable hash

paypalnullable hash

pixnullable hash

promptpaynullable hash

radar_optionsnullable hash

revolut_paynullable hash

samsung_paynullable hash

satispaynullable hash

sepa_debitnullable hash

sofortnullable hash

swishnullable hash

twintnullable hash

us_bank_accountnullable hash

wechat_paynullable hash

zipnullable hash

Create a PaymentMethod

Parameters

typeenumRequired

billing_detailshash

metadatahash

More parametersExpand all

acss_debithash

affirmhash

afterpay_clearpayhash

alipayhash

allow_redisplayenum

almahash

amazon_payhash

au_becs_debithash

bacs_debithash

More attributes

More parameters

More parameters