Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

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

  • cryptoMap

  • customMap

  • customer_balanceMap

  • epsMap

  • fpxMap

  • giropayMap

  • grabpayMap

  • idealMap

  • interac_presentMapPreview feature

  • kakao_payMap

  • klarnaMap

  • konbiniMap

  • kr_cardMap

  • linkMap

  • mb_wayMap

  • mobilepayMap

  • multibancoMap

  • naver_payMap

  • nz_bank_accountMap

  • oxxoMap

  • p24Map

  • pay_by_bankMap

  • paycoMap

  • paynowMap

  • paypalMap

  • paypayMapPreview feature

  • paytoMap

  • 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
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 to 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

  • paytoMap

  • us_bank_accountMap

Returns

Returns a PaymentMethod object.

POST /v1/payment_methods/:id
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
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"
}

Retrieve a PaymentMethod

Retrieves a PaymentMethod object attached to the StripeAccount. To retrieve a payment method attached to a Customer, you should use Retrieve a Customer’s PaymentMethods

Parameters

No parameters.

Returns

Returns a PaymentMethod object.

GET /v1/payment_methods/:id
Stripe.apiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
PaymentMethod paymentMethod = PaymentMethod.retrieve("pm_1Q0PsIJvEtkwdCNYMSaVuRz6");
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": {}
  }
}

List a Customer's PaymentMethods

Returns a list of PaymentMethods for a given Customer

Parameters

  • typeenum

    An optional filter on the list, based on the object type field. Without the filter, the list includes all current and future payment method types. If your integration expects only one type of payment method in the response, make sure to provide a type value in the request.

More parameters

  • allow_redisplayenum

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A Map with a data property that contains an array of up to limit PaymentMethods of type type, starting after PaymentMethods starting_after. Each entry in the array is a separate PaymentMethod object. If no more PaymentMethods are available, the resulting array will be empty.

GET /v1/customers/:id/payment_methods
Stripe.apiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
Customer resource = Customer.retrieve("cus_9s6XKzkNRiz8i3");
CustomerListPaymentMethodsParams params =
  CustomerListPaymentMethodsParams.builder().setLimit(3L).build();
PaymentMethodCollection paymentMethods = resource.listPaymentMethods(params);
Response
{
  "object": "list",
  "url": "/v1/customers/cus_9s6XKzkNRiz8i3/payment_methods",
  "has_more": false,
  "data": [
    {
      "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"
    }
  ]
}