Stripe: Create a Setup Intent

← Setup intents operations · Get started

Operation stripe.postsetupintents

Provider route: POST /v1/setup_intents. 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["setupIntents"]["postSetupIntents"]>[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.setupIntents.postSetupIntents(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.setup_intents.post_setup_intents(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.allowed_payment_method_types	array	Optional	The list of payment method types to allow for this SetupIntent. Stripe will only use methods in this list when determining the payment methods to offer. A list of valid payment method types can be found [here](https://docs.stripe.com/api/payment_methods/object#payment_method_object-type).
body.allowed_payment_method_types[]	string	Each item	One of: acss_debit, affirm, afterpay_clearpay, alipay, alma, amazon_pay, au_becs_debit, bacs_debit, bancontact, billie, bizum, blik, boku_promptpay, boleto, capchase_pay, card, card_present, cashapp, check_scan, click_to_pay, crypto, customer_balance, demo_pay, duitnow, dummy_auth_push, dummy_passthrough_card, edenred, eps, fpx, gcash, getbalance, gift_card, giropay, gopay, grabpay, id_bank_transfer, ideal, interac_present, kakao_pay, klarna, knet, konbini, kr_card, kr_market, kriya, link, mb_way, mobilepay, momo, mondu, multibanco, naver_pay, netbanking, ng_bank, ng_bank_transfer, ng_card, ng_market, ng_ussd, ng_wallet, nz_bank_account, octopus, oxxo, p24, paper_check, pay_by_bank, payco, paynow, paypal, paypay, payto, pix, promptpay, qris, rechnung, revolut_pay, samsung_pay, satispay, scalapay, sepa_debit, sequra, shop_pay, shopeepay, sofort, south_korea_market, stripe_balance, sunbit, swish, tamara, test_pay, touch_n_go, truemoney, twint, upi, us_bank_account, us_cash_voucher, vipps, wechat_pay, wero, zip
body.attach_to_self	boolean	Optional	If present, the SetupIntent’s payment method will be attached to the in-context Stripe Account. It can only be used for this Stripe Account’s own money movement flows like InboundTransfer and OutboundTransfers. It cannot be set to true when setting up a PaymentMethod for a Customer, and defaults to false when attaching a PaymentMethod to a Customer.
body.automatic_payment_methods	object	Optional	When you enable this parameter, this SetupIntent accepts payment methods that you enable in the Dashboard and that are compatible with its other parameters.
body.automatic_payment_methods.allow_redirects	string	Optional	One of: always, never
body.automatic_payment_methods.enabled	boolean	Required within parent
body.confirm	boolean	Optional	Set to `true` to attempt to confirm this SetupIntent immediately. This parameter defaults to `false`. If a card is the attached payment method, you can provide a `return_url` in case further authentication is necessary.
body.confirmation_token	string	Optional	ID of the ConfirmationToken used to confirm this SetupIntent. If the provided ConfirmationToken contains properties that are also being provided in this request, such as `payment_method`, then the values in this request will take precedence. Maximum length: 5000
body.customer	string	Optional	ID of the Customer this SetupIntent belongs to, if one exists. If present, the SetupIntent’s payment method will be attached to the Customer on successful setup. Payment methods attached to other Customers cannot be used with this SetupIntent. Maximum length: 5000
body.customer_account	string	Optional	ID of the Account this SetupIntent belongs to, if one exists. If present, the SetupIntent’s payment method will be attached to the Account on successful setup. Payment methods attached to other Accounts cannot be used with this SetupIntent. Maximum length: 5000
body.description	string	Optional	An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 1000
body.excluded_payment_method_types	array	Optional	The list of payment method types to exclude from use with this SetupIntent.
body.excluded_payment_method_types[]	string	Each item	One of: acss_debit, affirm, afterpay_clearpay, alipay, alma, amazon_pay, au_becs_debit, bacs_debit, bancontact, billie, bizum, blik, boleto, card, cashapp, crypto, customer_balance, eps, fpx, giropay, grabpay, ideal, kakao_pay, klarna, konbini, kr_card, 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.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.flow_directions	array	Optional	Indicates the directions of money movement for which this payment method is intended to be used. Include `inbound` if you intend to use the payment method as the origin to pull funds from. Include `outbound` if you intend to use the payment method as the destination to send funds to. You can include both if you intend to use the payment method for both purposes.
body.flow_directions[]	string	Each item	One of: inbound, outbound
body.mandate_data	JSON	Optional	This hash contains details about the mandate to create. This parameter can only be used with [`confirm=true`](https://docs.stripe.com/api/setup_intents/create#create_setup_intent-confirm).
body.mandate_data (anyOf 1)	Model	Alternative	Expand Create a Setup Intent — request body — body mandate data customer acceptance
body.mandate_data (anyOf 2)	string	Alternative	One of:
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.on_behalf_of	string	Optional	The Stripe account ID created for this SetupIntent.
body.payment_method	string	Optional	ID of the payment method (a PaymentMethod, Card, or saved Source object) to attach to this SetupIntent. Maximum length: 5000
body.payment_method_configuration	string	Optional	The ID of the [payment method configuration](https://docs.stripe.com/api/payment_method_configurations) to use with this SetupIntent. Maximum length: 100
body.payment_method_data	Model	Optional	Expand Create a Setup Intent — request body — body payment method data
body.payment_method_options	Model	Optional	Expand Create a Setup Intent — request body — body payment method options
body.return_url	string	Optional	The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method’s app or site. To redirect to a mobile application, you can alternatively supply an application URI scheme. This parameter can only be used with [`confirm=true`](https://docs.stripe.com/api/setup_intents/create#create_setup_intent-confirm).
body.single_use	object	Optional	If you populate this hash, this SetupIntent generates a `single_use` mandate after successful completion. Single-use mandates are only valid for the following payment methods: `acss_debit`, `alipay`, `au_becs_debit`, `bacs_debit`, `bancontact`, `boleto`, `ideal`, `link`, `sepa_debit`, and `us_bank_account`.
body.single_use.amount	integer	Required within parent
body.single_use.currency	string	Required within parent	Format: currency
body.usage	string	Optional	Indicates how the payment method is intended to be used in the future. If not provided, this value defaults to `off_session`. One of: off_session, on_session
body.use_stripe_sdk	boolean	Optional	Set to `true` when confirming server-side and using Stripe.js, iOS, or Android client-side SDKs to handle the next actions.

Referenced models: Create a Setup Intent — request body — body mandate data customer acceptance, Create a Setup Intent — request body — body payment method data, Create a Setup Intent — request body — body payment method options

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 Cancel a Setup Intent — response body

Referenced models: Cancel a Setup Intent — response body

Schemas

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

Create a Setup Intent — request body — body mandate data customer acceptance

Field	Type	Presence	Description and constraints
$	object	Root
customer_acceptance	object	Required within parent
customer_acceptance.accepted_at	integer	Optional	Format: unix-time
customer_acceptance.offline	object	Optional
customer_acceptance.online	object	Optional
customer_acceptance.online.ip_address	string	Required within parent
customer_acceptance.online.user_agent	string	Required within parent	Maximum length: 5000
customer_acceptance.type	string	Required within parent	One of: offline, online Maximum length: 5000

Create a Setup Intent — request body — body payment method data

Field	Type	Presence	Description and constraints
$	object	Root	When included, this hash creates a PaymentMethod that is set as the [`payment_method`](https://docs.stripe.com/api/setup_intents/object#setup_intent_object-payment_method) value in the SetupIntent.
acss_debit	object	Optional
acss_debit.account_number	string	Required within parent	Maximum length: 5000
acss_debit.institution_number	string	Required within parent	Maximum length: 5000
acss_debit.transit_number	string	Required within parent	Maximum length: 5000
affirm	object	Optional
afterpay_clearpay	object	Optional
alipay	object	Optional
allow_redisplay	string	Optional	One of: always, limited, unspecified
alma	object	Optional
amazon_pay	object	Optional
au_becs_debit	object	Optional
au_becs_debit.account_number	string	Required within parent	Maximum length: 5000
au_becs_debit.bsb_number	string	Required within parent	Maximum length: 5000
bacs_debit	object	Optional
bacs_debit.account_number	string	Optional	Maximum length: 5000
bacs_debit.sort_code	string	Optional	Maximum length: 5000
bancontact	object	Optional
billie	object	Optional
billing_details	Model	Optional	Expand Create a Setup Intent — request body — body payment method data billing details
bizum	object	Optional
blik	object	Optional
boleto	object	Optional
boleto.tax_id	string	Required within parent	Maximum length: 5000
cashapp	object	Optional
crypto	object	Optional
customer_balance	object	Optional
eps	Model	Optional	Expand Create a Setup Intent — request body — body payment method data eps
fpx	object	Optional
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
giropay	object	Optional
grabpay	object	Optional
ideal	object	Optional
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
interac_present	object	Optional
kakao_pay	object	Optional
klarna	object	Optional
klarna.dob	object	Optional
klarna.dob.day	integer	Required within parent
klarna.dob.month	integer	Required within parent
klarna.dob.year	integer	Required within parent
konbini	object	Optional
kr_card	object	Optional
link	object	Optional
mb_way	object	Optional
metadata	object	Optional	Additional keys: see wildcard field
metadata.*	string	Additional keys
mobilepay	object	Optional
multibanco	object	Optional
naver_pay	object	Optional
naver_pay.funding	string	Optional	One of: card, points
nz_bank_account	object	Optional
nz_bank_account.account_holder_name	string	Optional	Maximum length: 5000
nz_bank_account.account_number	string	Required within parent	Maximum length: 5000
nz_bank_account.bank_code	string	Required within parent	Maximum length: 5000
nz_bank_account.branch_code	string	Required within parent	Maximum length: 5000
nz_bank_account.reference	string	Optional	Maximum length: 128
nz_bank_account.suffix	string	Required within parent	Maximum length: 5000
oxxo	object	Optional
p24	object	Optional
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
pay_by_bank	object	Optional
payco	object	Optional
paynow	object	Optional
paypal	object	Optional
paypay	object	Optional
payto	object	Optional
payto.account_number	string	Optional	Maximum length: 5000
payto.bsb_number	string	Optional	Maximum length: 5000
payto.pay_id	string	Optional	Maximum length: 5000
pix	object	Optional
promptpay	object	Optional
radar_options	object	Optional
radar_options.session	string	Optional	Maximum length: 5000
revolut_pay	object	Optional
samsung_pay	object	Optional
satispay	object	Optional
scalapay	object	Optional
sepa_debit	object	Optional
sepa_debit.iban	string	Required within parent	Maximum length: 5000
sequra	object	Optional
sofort	object	Optional
sofort.country	string	Required within parent	One of: AT, BE, DE, ES, IT, NL
sunbit	object	Optional
swish	object	Optional
twint	object	Optional
type	string	Required within parent	One of: acss_debit, affirm, afterpay_clearpay, alipay, alma, amazon_pay, au_becs_debit, bacs_debit, bancontact, billie, bizum, blik, boleto, cashapp, crypto, 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
upi	object	Optional
upi.mandate_options	object	Optional
upi.mandate_options.amount	integer	Optional
upi.mandate_options.amount_type	string	Optional	One of: fixed, maximum
upi.mandate_options.description	string	Optional	Maximum length: 20
upi.mandate_options.end_date	integer	Optional	Format: unix-time
us_bank_account	object	Optional
us_bank_account.account_holder_type	string	Optional	One of: company, individual
us_bank_account.account_number	string	Optional	Maximum length: 5000
us_bank_account.account_type	string	Optional	One of: checking, savings
us_bank_account.financial_connections_account	string	Optional	Maximum length: 5000
us_bank_account.routing_number	string	Optional	Maximum length: 5000
wechat_pay	object	Optional
zip	object	Optional

Referenced models: Create a Setup Intent — request body — body payment method data billing details, Create a Setup Intent — request body — body payment method data eps

PostApplicationFeesIdRefund — response body — application / object: application

Field	Type	Presence	Description and constraints
$	object	Root
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
name	JSON	Optional
name (anyOf 1)	string	Alternative	The name of the application. Maximum length: 5000
name (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: application

Delete a customer — response body

Field	Type	Presence	Description and constraints
$	object	Root
deleted	boolean	Required within parent	Always true for a deleted object Known values: True
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: customer

Cancel a Setup Intent — response body — managed payments value enabled

Field	Type	Presence	Description and constraints
$	object	Root
enabled	boolean	Required within parent	Set to `true` to enable [Managed Payments](https://docs.stripe.com/payments/managed-payments), Stripe's merchant of record solution, for this session.

Policy, approvals and errors

SDK function policy ID: stripe.postsetupintents. Catalog operation: PostSetupIntents. 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