Stripe: Create a Payment Method

← Payment methods operations · Get started

Operation stripe.postpaymentmethods

Provider route: POST /v1/payment_methods. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["paymentMethods"]["postPaymentMethods"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.paymentMethods.postPaymentMethods(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.payment_methods.post_payment_methods(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Optional	Additional keys: not allowed
body.acss_debit	object	Optional	If this is an `acss_debit` PaymentMethod, this hash contains details about the ACSS Debit payment method.
body.acss_debit.account_number	string	Required within parent	Maximum length: 5000
body.acss_debit.institution_number	string	Required within parent	Maximum length: 5000
body.acss_debit.transit_number	string	Required within parent	Maximum length: 5000
body.affirm	object	Optional	If this is an `affirm` PaymentMethod, this hash contains details about the Affirm payment method.
body.afterpay_clearpay	object	Optional	If this is an `AfterpayClearpay` PaymentMethod, this hash contains details about the AfterpayClearpay payment method.
body.alipay	object	Optional	If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method.
body.allow_redisplay	string	Optional	This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. One of: always, limited, unspecified
body.alma	object	Optional	If this is an Alma PaymentMethod, this hash contains details about the Alma payment method.
body.amazon_pay	object	Optional	If this is an AmazonPay PaymentMethod, this hash contains details about the AmazonPay payment method.
body.au_becs_debit	object	Optional	If this is an `au_becs_debit` PaymentMethod, this hash contains details about the bank account.
body.au_becs_debit.account_number	string	Required within parent	Maximum length: 5000
body.au_becs_debit.bsb_number	string	Required within parent	Maximum length: 5000
body.bacs_debit	object	Optional	If this is a `bacs_debit` PaymentMethod, this hash contains details about the Bacs Direct Debit bank account.
body.bacs_debit.account_number	string	Optional	Maximum length: 5000
body.bacs_debit.sort_code	string	Optional	Maximum length: 5000
body.bancontact	object	Optional	If this is a `bancontact` PaymentMethod, this hash contains details about the Bancontact payment method.
body.billie	object	Optional	If this is a `billie` PaymentMethod, this hash contains details about the Billie payment method.
body.billing_details	Model	Optional	Expand Create a Payment Method — request body — body billing details
body.bizum	object	Optional	If this is a `bizum` PaymentMethod, this hash contains details about the Bizum payment method.
body.blik	object	Optional	If this is a `blik` PaymentMethod, this hash contains details about the BLIK payment method.
body.boleto	object	Optional	If this is a `boleto` PaymentMethod, this hash contains details about the Boleto payment method.
body.boleto.tax_id	string	Required within parent	Maximum length: 5000
body.card	JSON	Optional	If this is a `card` PaymentMethod, this hash contains the user’s card details. For backwards compatibility, you can alternatively provide a Stripe token (e.g., for Apple Pay, Amex Express Checkout, or legacy Checkout) into the card hash with format `card: {token: “tok_visa”}`. When providing a card number, you must meet the requirements for [PCI compliance](https://stripe.com/docs/security#validating-pci-compliance). We strongly recommend using Stripe.js instead of interacting with this API directly.
body.card (anyOf 1)	object	Alternative
body.card (anyOf 1).cvc	string	Optional	Maximum length: 5000
body.card (anyOf 1).exp_month	integer	Required within parent
body.card (anyOf 1).exp_year	integer	Required within parent
body.card (anyOf 1).networks	object	Optional
body.card (anyOf 1).networks.preferred	string	Optional	One of: cartes_bancaires, mastercard, visa
body.card (anyOf 1).number	string	Required within parent	Maximum length: 5000
body.card (anyOf 2)	object	Alternative
body.card (anyOf 2).token	string	Required within parent	Maximum length: 5000
body.cashapp	object	Optional	If this is a `cashapp` PaymentMethod, this hash contains details about the Cash App Pay payment method.
body.crypto	object	Optional	If this is a Crypto PaymentMethod, this hash contains details about the Crypto payment method.
body.custom	object	Optional	If this is a `custom` PaymentMethod, this hash contains details about the Custom payment method.
body.custom.type	string	Required within parent	Maximum length: 5000
body.customer	string	Optional	The `Customer` to whom the original PaymentMethod is attached. Maximum length: 5000
body.customer_balance	object	Optional	If this is a `customer_balance` PaymentMethod, this hash contains details about the CustomerBalance payment method.
body.eps	object	Optional	If this is an `eps` PaymentMethod, this hash contains details about the EPS payment method.
body.eps.bank	string	Optional	One of: arzte_und_apotheker_bank, austrian_anadi_bank_ag, bank_austria, bankhaus_carl_spangler, bankhaus_schelhammer_und_schattera_ag, bawag_psk_ag, bks_bank_ag, brull_kallmus_bank_ag, btv_vier_lander_bank, capital_bank_grawe_gruppe_ag, deutsche_bank_ag, dolomitenbank, easybank_ag, erste_bank_und_sparkassen, hypo_alpeadriabank_international_ag, hypo_bank_burgenland_aktiengesellschaft, hypo_noe_lb_fur_niederosterreich_u_wien, hypo_oberosterreich_salzburg_steiermark, hypo_tirol_bank_ag, hypo_vorarlberg_bank_ag, marchfelder_bank, oberbank_ag, raiffeisen_bankengruppe_osterreich, schoellerbank_ag, sparda_bank_wien, volksbank_gruppe, volkskreditbank_ag, vr_bank_braunau Maximum length: 5000
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.fpx	object	Optional	If this is an `fpx` PaymentMethod, this hash contains details about the FPX payment method.
body.fpx.bank	string	Required within parent	One of: affin_bank, agrobank, alliance_bank, ambank, bank_islam, bank_muamalat, bank_of_china, bank_rakyat, bnp_paribas, bsn, cimb, citibank, deutsche_bank, hong_leong_bank, hsbc, kfh, maybank2e, maybank2u, mbsb_bank, ocbc, pb_enterprise, public_bank, rhb, standard_chartered, uob Maximum length: 5000
body.giropay	object	Optional	If this is a `giropay` PaymentMethod, this hash contains details about the Giropay payment method.
body.grabpay	object	Optional	If this is a `grabpay` PaymentMethod, this hash contains details about the GrabPay payment method.
body.ideal	object	Optional	If this is an `ideal` PaymentMethod, this hash contains details about the iDEAL payment method.
body.ideal.bank	string	Optional	One of: abn_amro, adyen, asn_bank, bunq, buut, finom, handelsbanken, ing, knab, mollie, moneyou, n26, nn, rabobank, regiobank, revolut, sns_bank, triodos_bank, van_lanschot, yoursafe Maximum length: 5000
body.interac_present	object	Optional	If this is an `interac_present` PaymentMethod, this hash contains details about the Interac Present payment method.
body.kakao_pay	object	Optional	If this is a `kakao_pay` PaymentMethod, this hash contains details about the Kakao Pay payment method.
body.klarna	object	Optional	If this is a `klarna` PaymentMethod, this hash contains details about the Klarna payment method.
body.klarna.dob	object	Optional
body.klarna.dob.day	integer	Required within parent
body.klarna.dob.month	integer	Required within parent
body.klarna.dob.year	integer	Required within parent
body.konbini	object	Optional	If this is a `konbini` PaymentMethod, this hash contains details about the Konbini payment method.
body.kr_card	object	Optional	If this is a `kr_card` PaymentMethod, this hash contains details about the Korean Card payment method.
body.link	object	Optional	If this is an `Link` PaymentMethod, this hash contains details about the Link payment method (Link is also known as Onelink in the UK).
body.mb_way	object	Optional	If this is a MB WAY PaymentMethod, this hash contains details about the MB WAY payment method.
body.metadata	object	Optional	Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`. Additional keys: see wildcard field
body.metadata.*	string	Additional keys
body.mobilepay	object	Optional	If this is a `mobilepay` PaymentMethod, this hash contains details about the MobilePay payment method.
body.multibanco	object	Optional	If this is a `multibanco` PaymentMethod, this hash contains details about the Multibanco payment method.
body.naver_pay	object	Optional	If this is a `naver_pay` PaymentMethod, this hash contains details about the Naver Pay payment method.
body.naver_pay.funding	string	Optional	One of: card, points
body.nz_bank_account	object	Optional	If this is an nz_bank_account PaymentMethod, this hash contains details about the nz_bank_account payment method.
body.nz_bank_account.account_holder_name	string	Optional	Maximum length: 5000
body.nz_bank_account.account_number	string	Required within parent	Maximum length: 5000
body.nz_bank_account.bank_code	string	Required within parent	Maximum length: 5000
body.nz_bank_account.branch_code	string	Required within parent	Maximum length: 5000
body.nz_bank_account.reference	string	Optional	Maximum length: 128
body.nz_bank_account.suffix	string	Required within parent	Maximum length: 5000
body.oxxo	object	Optional	If this is an `oxxo` PaymentMethod, this hash contains details about the OXXO payment method.
body.p24	object	Optional	If this is a `p24` PaymentMethod, this hash contains details about the P24 payment method.
body.p24.bank	string	Optional	One of: alior_bank, bank_millennium, bank_nowy_bfg_sa, bank_pekao_sa, banki_spbdzielcze, blik, bnp_paribas, boz, citi_handlowy, credit_agricole, envelobank, etransfer_pocztowy24, getin_bank, ideabank, ing, inteligo, mbank_mtransfer, nest_przelew, noble_pay, pbac_z_ipko, plus_bank, santander_przelew24, tmobile_usbugi_bankowe, toyota_bank, velobank, volkswagen_bank
body.pay_by_bank	object	Optional	If this is a `pay_by_bank` PaymentMethod, this hash contains details about the PayByBank payment method.
body.payco	object	Optional	If this is a `payco` PaymentMethod, this hash contains details about the PAYCO payment method.
body.payment_method	string	Optional	The PaymentMethod to share. Maximum length: 5000
body.paynow	object	Optional	If this is a `paynow` PaymentMethod, this hash contains details about the PayNow payment method.
body.paypal	object	Optional	If this is a `paypal` PaymentMethod, this hash contains details about the PayPal payment method.
body.paypay	object	Optional	If this is a `paypay` PaymentMethod, this hash contains details about the PayPay payment method.
body.payto	object	Optional	If this is a `payto` PaymentMethod, this hash contains details about the PayTo payment method.
body.payto.account_number	string	Optional	Maximum length: 5000
body.payto.bsb_number	string	Optional	Maximum length: 5000
body.payto.pay_id	string	Optional	Maximum length: 5000
body.pix	object	Optional	If this is a `pix` PaymentMethod, this hash contains details about the Pix payment method.
body.promptpay	object	Optional	If this is a `promptpay` PaymentMethod, this hash contains details about the PromptPay payment method.
body.radar_options	object	Optional	Options to configure Radar. See [Radar Session](https://docs.stripe.com/radar/radar-session) for more information.
body.radar_options.session	string	Optional	Maximum length: 5000
body.revolut_pay	object	Optional	If this is a `revolut_pay` PaymentMethod, this hash contains details about the Revolut Pay payment method.
body.samsung_pay	object	Optional	If this is a `samsung_pay` PaymentMethod, this hash contains details about the SamsungPay payment method.
body.satispay	object	Optional	If this is a `satispay` PaymentMethod, this hash contains details about the Satispay payment method.
body.scalapay	object	Optional	If this is a Scalapay PaymentMethod, this hash contains details about the Scalapay payment method.
body.sepa_debit	object	Optional	If this is a `sepa_debit` PaymentMethod, this hash contains details about the SEPA debit bank account.
body.sepa_debit.iban	string	Required within parent	Maximum length: 5000
body.sequra	object	Optional	If this is a SeQura PaymentMethod, this hash contains details about the SeQura payment method.
body.sofort	object	Optional	If this is a `sofort` PaymentMethod, this hash contains details about the SOFORT payment method.
body.sofort.country	string	Required within parent	One of: AT, BE, DE, ES, IT, NL
body.sunbit	object	Optional	If this is a `sunbit` PaymentMethod, this hash contains details about the Sunbit payment method.
body.swish	object	Optional	If this is a `swish` PaymentMethod, this hash contains details about the Swish payment method.
body.twint	object	Optional	If this is a TWINT PaymentMethod, this hash contains details about the TWINT payment method.
body.type	string	Optional	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. One of: acss_debit, affirm, afterpay_clearpay, alipay, alma, amazon_pay, au_becs_debit, bacs_debit, bancontact, billie, bizum, blik, boleto, card, cashapp, crypto, custom, customer_balance, eps, fpx, giropay, grabpay, ideal, kakao_pay, klarna, konbini, kr_card, link, mb_way, mobilepay, multibanco, naver_pay, nz_bank_account, oxxo, p24, pay_by_bank, payco, paynow, paypal, paypay, payto, pix, promptpay, revolut_pay, samsung_pay, satispay, scalapay, sepa_debit, sequra, sofort, sunbit, swish, twint, upi, us_bank_account, wechat_pay, zip
body.upi	object	Optional	If this is a `upi` PaymentMethod, this hash contains details about the UPI payment method.
body.upi.mandate_options	object	Optional
body.upi.mandate_options.amount	integer	Optional
body.upi.mandate_options.amount_type	string	Optional	One of: fixed, maximum
body.upi.mandate_options.description	string	Optional	Maximum length: 20
body.upi.mandate_options.end_date	integer	Optional	Format: unix-time
body.us_bank_account	object	Optional	If this is an `us_bank_account` PaymentMethod, this hash contains details about the US bank account payment method.
body.us_bank_account.account_holder_type	string	Optional	One of: company, individual
body.us_bank_account.account_number	string	Optional	Maximum length: 5000
body.us_bank_account.account_type	string	Optional	One of: checking, savings
body.us_bank_account.financial_connections_account	string	Optional	Maximum length: 5000
body.us_bank_account.routing_number	string	Optional	Maximum length: 5000
body.wechat_pay	object	Optional	If this is an `wechat_pay` PaymentMethod, this hash contains details about the wechat_pay payment method.
body.zip	object	Optional	If this is a `zip` PaymentMethod, this hash contains details about the Zip payment method.

Referenced models: Create a Payment Method — request body — body billing details

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a Payment Method — response body

Referenced models: Create a Payment Method — response body

Schemas

698 more schemas are linked from the tables above, on the schema pages.

Create a Payment Method — request body — body billing details

Field	Type	Presence	Description and constraints
$	object	Root	Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
address	JSON	Optional
address (anyOf 1)	object	Alternative
address (anyOf 1).city	string	Optional	Maximum length: 5000
address (anyOf 1).country	string	Optional	Maximum length: 5000
address (anyOf 1).line1	string	Optional	Maximum length: 5000
address (anyOf 1).line2	string	Optional	Maximum length: 5000
address (anyOf 1).postal_code	string	Optional	Maximum length: 5000
address (anyOf 1).state	string	Optional	Maximum length: 5000
address (anyOf 2)	string	Alternative	One of:
email	JSON	Optional
email (anyOf 1)	string	Alternative
email (anyOf 2)	string	Alternative	One of:
name	JSON	Optional
name (anyOf 1)	string	Alternative	Maximum length: 5000
name (anyOf 2)	string	Alternative	One of:
phone	JSON	Optional
phone (anyOf 1)	string	Alternative	Maximum length: 5000
phone (anyOf 2)	string	Alternative	One of:
tax_id	string	Optional	Maximum length: 5000

Create a Payment Method — response body — zip

Field	Type	Presence	Description and constraints
$	object	Root

Create a charge — response body — billing details

Field	Type	Presence	Description and constraints
$	object	Root
address	JSON	Optional
address (anyOf 1)	JSON	Alternative	Billing address.
address (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a Location — response body — address
address (anyOf 2)	null	Alternative
email	JSON	Optional
email (anyOf 1)	string	Alternative	Email address. Maximum length: 5000
email (anyOf 2)	null	Alternative
name	JSON	Optional
name (anyOf 1)	string	Alternative	Full name. Maximum length: 5000
name (anyOf 2)	null	Alternative
phone	JSON	Optional
phone (anyOf 1)	string	Alternative	Billing phone number (including extension). Maximum length: 5000
phone (anyOf 2)	null	Alternative
tax_id	JSON	Optional
tax_id (anyOf 1)	string	Alternative	Taxpayer identification number. Used only for transactions between LATAM buyers and non-LATAM sellers. Maximum length: 5000
tax_id (anyOf 2)	null	Alternative

Referenced models: Create a Location — response body — address

Create a Payment Method — response body — acss debit

Field	Type	Presence	Description and constraints
$	object	Root
bank_name	JSON	Optional
bank_name (anyOf 1)	string	Alternative	Name of the bank associated with the bank account. Maximum length: 5000
bank_name (anyOf 2)	null	Alternative
fingerprint	JSON	Optional
fingerprint (anyOf 1)	string	Alternative	Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same. Maximum length: 5000
fingerprint (anyOf 2)	null	Alternative
institution_number	JSON	Optional
institution_number (anyOf 1)	string	Alternative	Institution number of the bank account. Maximum length: 5000
institution_number (anyOf 2)	null	Alternative
last4	JSON	Optional
last4 (anyOf 1)	string	Alternative	Last four digits of the bank account number. Maximum length: 5000
last4 (anyOf 2)	null	Alternative
transit_number	JSON	Optional
transit_number (anyOf 1)	string	Alternative	Transit number of the bank account. Maximum length: 5000
transit_number (anyOf 2)	null	Alternative

Create a Payment Method — response body — au becs debit

Field	Type	Presence	Description and constraints
$	object	Root
bsb_number	JSON	Optional
bsb_number (anyOf 1)	string	Alternative	Six-digit number identifying bank and branch associated with this bank account. Maximum length: 5000
bsb_number (anyOf 2)	null	Alternative
fingerprint	JSON	Optional
fingerprint (anyOf 1)	string	Alternative	Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same. Maximum length: 5000
fingerprint (anyOf 2)	null	Alternative
last4	JSON	Optional
last4 (anyOf 1)	string	Alternative	Last four digits of the bank account number. Maximum length: 5000
last4 (anyOf 2)	null	Alternative

Create a Payment Method — response body — bacs debit

Field	Type	Presence	Description and constraints
$	object	Root
fingerprint	JSON	Optional
fingerprint (anyOf 1)	string	Alternative	Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same. Maximum length: 5000
fingerprint (anyOf 2)	null	Alternative
last4	JSON	Optional
last4 (anyOf 1)	string	Alternative	Last four digits of the bank account number. Maximum length: 5000
last4 (anyOf 2)	null	Alternative
sort_code	JSON	Optional
sort_code (anyOf 1)	string	Alternative	Sort code of the bank account. (e.g., `10-20-30`) Maximum length: 5000
sort_code (anyOf 2)	null	Alternative

Create a Payment Method — response body — bizum

Field	Type	Presence	Description and constraints
$	object	Root
buyer_id	JSON	Optional
buyer_id (anyOf 1)	string	Alternative	A unique identifier for the buyer as determined by the local payment processor. Maximum length: 5000
buyer_id (anyOf 2)	null	Alternative

Create a Payment Method — response body — blik

Field	Type	Presence	Description and constraints
$	object	Root
buyer_id	JSON	Optional
buyer_id (anyOf 1)	string	Alternative	A unique and immutable identifier assigned by BLIK to every buyer. Maximum length: 5000
buyer_id (anyOf 2)	null	Alternative

Create a Payment Method — response body — boleto

Field	Type	Presence	Description and constraints
$	object	Root
tax_id	string	Required within parent	Uniquely identifies the customer tax id (CNPJ or CPF) Maximum length: 5000

Create a Payment Method — response body — cashapp

Field	Type	Presence	Description and constraints
$	object	Root
buyer_id	JSON	Optional
buyer_id (anyOf 1)	string	Alternative	A unique and immutable identifier assigned by Cash App to every buyer. Maximum length: 5000
buyer_id (anyOf 2)	null	Alternative
cashtag	JSON	Optional
cashtag (anyOf 1)	string	Alternative	A public identifier for buyers using Cash App. Maximum length: 5000
cashtag (anyOf 2)	null	Alternative

Create a Payment Method — response body — custom

Field	Type	Presence	Description and constraints
$	object	Root
display_name	JSON	Optional
display_name (anyOf 1)	string	Alternative	Display name of the Dashboard-only CustomPaymentMethodType. Maximum length: 5000
display_name (anyOf 2)	null	Alternative
logo	JSON	Optional
logo (anyOf 1)	JSON	Alternative	Contains information about the Dashboard-only CustomPaymentMethodType logo.
logo (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a Payment Method — response body — custom logo value content type, url
logo (anyOf 2)	null	Alternative
type	string	Required within parent	ID of the Dashboard-only CustomPaymentMethodType. Not expandable. Maximum length: 5000

Referenced models: Create a Payment Method — response body — custom logo value content type, url

Create a Payment Method — response body — link

Field	Type	Presence	Description and constraints
$	object	Root
email	JSON	Optional
email (anyOf 1)	string	Alternative	Account owner's email address. Maximum length: 5000
email (anyOf 2)	null	Alternative

Policy, approvals and errors

SDK function policy ID: stripe.postpaymentmethods. Catalog operation: PostPaymentMethods. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source