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.

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

More attributes

objectstring

acss_debitnullable Map

affirmnullable Map

afterpay_clearpaynullable Map

alipaynullable Map

allow_redisplaynullable enumPreview feature

amazon_paynullable Map

au_becs_debitnullable Map

bacs_debitnullable Map

bancontactnullable 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

klarnanullable Map

konbininullable Map

linknullable Map

livemodeboolean

mobilepaynullable Map

oxxonullable Map

p24nullable Map

paynownullable Map

paypalnullable Map

pixnullable Map

promptpaynullable Map

radar_optionsnullable Map

revolut_paynullable Map

sepa_debitnullable Map

sofortnullable Map

swishnullable Map

us_bank_accountnullable Map

wechat_paynullable Map

zipnullable Map

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 57 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

amazon_payMap

au_becs_debitMap

bacs_debitMap

bancontactMap

blikMap

boletoMap

cardMap

cashappMap

customer_balanceMap

epsMap

fpxMap

giropayMap

grabpayMap

idealMap

interac_presentMapPreview feature

klarnaMap

konbiniMap

linkMap

mobilepayMap

oxxoMap

p24Map

paynowMap

paypalMap

pixMap

promptpayMap

radar_optionsMap

revolut_payMap

sepa_debitMap

sofortMap

swishMap

us_bank_accountMap

wechat_payMap

zipMap

Returns

Returns a PaymentMethod object.

POST /v1/payment_methods

Server-side language

Stripe.apiKey = "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc";
PaymentMethodCreateParams params =
  PaymentMethodCreateParams.builder()
    .setType(PaymentMethodCreateParams.Type.CARD)
    .setCard(
      PaymentMethodCreateParams.Card.builder()
        .setNumber("4242424242424242")
        .setExpMonth(8L)
        .setExpYear(2026L)
        .setCvc("314")
        .build()
    )
    .build();
PaymentMethod paymentMethod = PaymentMethod.create(params);

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_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

us_bank_accountMap

Returns

Returns a PaymentMethod object.

POST /v1/payment_methods/:id

Server-side language

Stripe.apiKey = "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc";
PaymentMethod resource = PaymentMethod.retrieve("pm_1MqLiJLkdIwHu7ixUEgbFdYF");
PaymentMethodUpdateParams params =
  PaymentMethodUpdateParams.builder().putMetadata("order_id", "6735").build();
PaymentMethod paymentMethod = resource.update(params);

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

Stripe.apiKey = "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc";
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 enumPreview feature

amazon_paynullable Map

au_becs_debitnullable Map

bacs_debitnullable Map

bancontactnullable 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

klarnanullable Map

konbininullable Map

linknullable Map

livemodeboolean

mobilepaynullable Map

oxxonullable Map

p24nullable Map

paynownullable Map

paypalnullable Map

pixnullable Map

promptpaynullable Map

radar_optionsnullable Map

revolut_paynullable Map

sepa_debitnullable Map

sofortnullable Map

swishnullable 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

amazon_payMap

au_becs_debitMap

bacs_debitMap

bancontactMap

blikMap

boletoMap

cardMap

cashappMap

customer_balanceMap

epsMap

fpxMap

giropayMap

grabpayMap

idealMap

interac_presentMapPreview feature

klarnaMap

konbiniMap

linkMap

More attributes

More parameters

More parameters