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_detailsobject
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 object
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.

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.

blik

BLIK is a single-use payment method common in Poland.

boleto

Boleto is a voucher-based payment method used in Brazil.

Show 56 more

More attributes

objectstring

acss_debitnullable object

affirmnullable object

afterpay_clearpaynullable object

alipaynullable object

allow_redisplaynullable enumPreview feature

amazon_paynullable object

au_becs_debitnullable object

bacs_debitnullable object

bancontactnullable object

bliknullable object

boletonullable object

cardnullable object

card_presentnullable object

cashappnullable object

createdtimestamp

customer_balancenullable object

epsnullable object

fpxnullable object

giropaynullable object

grabpaynullable object

idealnullable object

interac_presentnullable objectPreview feature

klarnanullable object

konbininullable object

linknullable object

livemodeboolean

mobilepaynullable objectPreview feature

oxxonullable object

p24nullable object

paynownullable object

paypalnullable object

pixnullable object

promptpaynullable object

radar_optionsnullable object

revolut_paynullable object

sepa_debitnullable object

sofortnullable object

swishnullable object

us_bank_accountnullable object

wechat_paynullable object

zipnullable object

The PaymentMethod object

{
  "id": "pm_1MqLiJLkdIwHu7ixUEgbFdYF",
  "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": "unchecked"
    },
    "country": "US",
    "exp_month": 8,
    "exp_year": 2026,
    "fingerprint": "mToisGZ01V71BCos",
    "funding": "credit",
    "generated_from": null,
    "last4": "4242",
    "networks": {
      "available": [
        "visa"
      ],
      "preferred": null
    },
    "three_d_secure_usage": {
      "supported": true
    },
    "wallet": null
  },
  "created": 1679945299,
  "customer": null,
  "livemode": false,
  "metadata": {},
  "type": "card"
}

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.

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.

blik

BLIK is a single-use payment method common in Poland.

boleto

Boleto is a voucher-based payment method used in Brazil.

Show 55 more

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

metadataobject
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_debitobject

affirmobject

afterpay_clearpayobject

alipayobject

allow_redisplayenum

amazon_payobject

au_becs_debitobject

bacs_debitobject

bancontactobject

blikobject

boletoobject

cardobject

cashappobject

customer_balanceobject

epsobject

fpxobject

giropayobject

grabpayobject

idealobject

interac_presentobjectPreview feature

klarnaobject

konbiniobject

linkobject

mobilepayobjectPreview feature

oxxoobject

p24object

paynowobject

paypalobject

pixobject

promptpayobject

radar_optionsobject

revolut_payobject

sepa_debitobject

sofortobject

swishobject

us_bank_accountobject

wechat_payobject

zipobject

Returns

Returns a PaymentMethod object.

POST /v1/payment_methods

Server-side language

curl https://api.stripe.com/v1/payment_methods \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d type=card \
  -d "card[number]"=4242424242424242 \
  -d "card[exp_month]"=8 \
  -d "card[exp_year]"=2026 \
  -d "card[cvc]"=314

Response

{
  "id": "pm_1MqLiJLkdIwHu7ixUEgbFdYF",
  "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": "unchecked"
    },
    "country": "US",
    "exp_month": 8,
    "exp_year": 2026,
    "fingerprint": "mToisGZ01V71BCos",
    "funding": "credit",
    "generated_from": null,
    "last4": "4242",
    "networks": {
      "available": [
        "visa"
      ],
      "preferred": null
    },
    "three_d_secure_usage": {
      "supported": true
    },
    "wallet": null
  },
  "created": 1679945299,
  "customer": null,
  "livemode": false,
  "metadata": {},
  "type": "card"
}

Update a PaymentMethod

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

Parameters

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

metadataobject
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

cardobject

linkobject

us_bank_accountobject

Returns

Returns a PaymentMethod object.

POST /v1/payment_methods/:id

Server-side language

curl https://api.stripe.com/v1/payment_methods/pm_1MqLiJLkdIwHu7ixUEgbFdYF \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "metadata[order_id]"=6735

Response

{
  "id": "pm_1MqLiJLkdIwHu7ixUEgbFdYF",
  "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": "unchecked"
    },
    "country": "US",
    "exp_month": 8,
    "exp_year": 2026,
    "fingerprint": "mToisGZ01V71BCos",
    "funding": "credit",
    "generated_from": null,
    "last4": "4242",
    "networks": {
      "available": [
        "visa"
      ],
      "preferred": null
    },
    "three_d_secure_usage": {
      "supported": true
    },
    "wallet": null
  },
  "created": 1679945299,
  "customer": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "type": "card"
}

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

curl https://api.stripe.com/v1/customers/cus_9s6XKzkNRiz8i3/payment_methods/pm_1NVChw2eZvKYlo2CHxiM5E2E \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"

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_detailsobject

customernullable stringExpandable

metadatanullable object

typeenum

More attributesExpand all

objectstring

acss_debitnullable object

affirmnullable object

afterpay_clearpaynullable object

alipaynullable object

allow_redisplaynullable enumPreview feature

amazon_paynullable object

au_becs_debitnullable object

bacs_debitnullable object

bancontactnullable object

bliknullable object

boletonullable object

cardnullable object

card_presentnullable object

cashappnullable object

createdtimestamp

customer_balancenullable object

epsnullable object

fpxnullable object

giropaynullable object

grabpaynullable object

idealnullable object

interac_presentnullable objectPreview feature

klarnanullable object

konbininullable object

linknullable object

livemodeboolean

mobilepaynullable objectPreview feature

oxxonullable object

p24nullable object

paynownullable object

paypalnullable object

pixnullable object

promptpaynullable object

radar_optionsnullable object

revolut_paynullable object

sepa_debitnullable object

sofortnullable object

swishnullable object

us_bank_accountnullable object

wechat_paynullable object

zipnullable object

Create a PaymentMethod

Parameters

typeenumRequired

billing_detailsobject

metadataobject

More parametersExpand all

acss_debitobject

affirmobject

afterpay_clearpayobject

alipayobject

allow_redisplayenum

amazon_payobject

au_becs_debitobject

bacs_debitobject

bancontactobject

blikobject

boletoobject

cardobject

cashappobject

customer_balanceobject

epsobject

fpxobject

giropayobject

grabpayobject

idealobject

interac_presentobjectPreview feature

klarnaobject

konbiniobject

linkobject

More attributes

More parameters

More parameters