Create Setup Intent
Saves a buyer’s payment method for later without charging it. Pass a confirmation_token for a method the buyer just supplied through the payment elements in setup mode, or a payment_method_id already on file to re-verify it. The response is the setup intent as created, not its outcome: while it is requires_action the buyer still has a step, so hand client_secret to the elements’ handleNextAction or poll Retrieve setup status. A buyer’s own token holding member:payment_methods:use may create a setup intent for itself from a confirmation token.
Authorizations
An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.
Headers
A unique key that makes this request safe to retry. See Idempotent requests.
255"d9105228-4a08-46b1-8b91-42fed586d383"
Pins the request to a dated API version.
"2026-09-22-1"
Body
The account to save the payment method for, prefixed biz_.
"biz_xxxxxxxxxxxxxx"
A confirmation token describing a payment method the buyer just supplied, collected by the payment elements in setup mode. Provide this or payment_method_id, not both. The buyer is resolved from the token's billing email, or from email, and may still have a step to complete — poll Retrieve setup status for what to do next.
"ctok_xxxxxxxxxxxxxx"
The currency the saved payment method will be used with, as a lowercase ISO 4217 code. Controls which currency-specific payment methods are available. Defaults to usd.
"usd"
Overrides the buyer email carried on the confirmation token, resolving or creating the user the method belongs to. Ignored unless confirmation_token is provided, and when the token was created by a signed-in buyer or the caller is the buyer.
"dana@shinetime.example"
Custom metadata to attach to the setup intent. Returned on the setup intent and its webhooks.
An existing payment method to re-verify and save, prefixed payt_. Provide this or confirmation_token, not both. Not available to a buyer credential.
"payt_xxxxxxxxxxxxxx"
Where the buyer continues after completing an off-site step. An absolute https URL without credentials, at most 2,048 characters.
"https://shinetime.example/billing/saved"
Response
setup intent created from a confirmation token
The account the payment method is saved for, prefixed biz_.
"biz_xxxxxxxxxxxxxx"
The checkout configuration this setup was created through, prefixed ch_. Null for a setup created through this API rather than a hosted checkout.
The credential a buyer's surface presents to poll this setup and set its return URL — hand it to the elements' handleNextAction. Only on setups created through this API, and always null in list responses — retrieve the setup intent for it.
"sint_xxxxxxxxxxxxxx_secret_vdefault_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
When the setup intent was created, as an ISO 8601 timestamp.
"2026-01-01T12:00:00.000Z"
Setup intent ID, prefixed sint_.
"sint_xxxxxxxxxxxxxx"
Why the setup ended where it did, or null when nothing has failed. Present on canceled — a buyer who abandoned carries no code, one refused by the provider does. Dropped once the setup succeeds.
The buyer's member record on the account, prefixed mber_. Null without the member:basic:read permission, unless the caller is the buyer.
"mber_xxxxxxxxxxxxxx"
Your own key-value data attached when the setup intent was created.
The method behind this setup shaped for display: a buyer-facing name, the standard icon set, and the card's brand, last four, issuer identification number, and expiry when it was a card. Null until a method was collected.
The saved payment method, prefixed payt_, ready to charge with Create Payment. Null until the setup has succeeded.
"payt_xxxxxxxxxxxxxx"
The kind of instrument being saved, for example card or us_bank_account.
acss_debit, addi, affirm, afterpay_clearpay, alipay, alma, amazon_pay, apple, apple_pay, au_bank_transfer, au_becs_debit, bacs_debit, bancolombia, bancontact, bank_wire, billie, blik, boleto, bre_b, ca_bank_transfer, capchase_pay, card, card_installments_three, card_installments_six, card_installments_twelve, cashapp, claritypay, coinbase, crypto, custom, customer_balance, demo_pay, efecty, eps, eu_bank_transfer, fpx, flex_pay, gb_bank_transfer, gcash, giropay, google_pay, gopay, grabpay, id_bank_transfer, ideal, interac, kakao_pay, klarna, klarna_pay_now, konbini, kr_card, kr_market, kriya, kueski, link, mb_way, m_pesa, mercado_pago, mercado_pago_ar, mercado_pago_mx, mobilepay, modo, mondu, multibanco, naver_pay, nequi, netbanking, ng_bank, ng_bank_transfer, ng_card, ng_market, ng_ussd, ng_wallet, nupay, nz_bank_account, oney, oney_3x, oney_4x, opay, oxxo, p24, pago_efectivo, pse, pay_by_bank, payco, paynow, paypal, paypay, payto, pix, platform_balance, promptpay, qris, rapipago, rechnung, revolut_pay, samsung_pay, satispay, scalapay, sencillito, sepa_debit, sequra, servipag, sezzle, shop_pay, shopeepay, sofort, south_korea_market, spei, splitit, sunbit, swish, tamara, touch_n_go, twint, upi, us_bank_account, us_bank_transfer, venmo, verve, vipps, webpay, wechat_pay, yape, zip, coinflow, unknown "acss_debit"
Where the buyer lands after completing an off-site step, or null to leave them where they are.
"https://shinetime.example/billing/saved"
How far the setup has got. A 201 or 200 means we answered, not that the method was saved — always branch on this. requires_action — the buyer has a step outstanding; hand client_secret to the elements or poll Retrieve setup status. processing — the processor is deciding. succeeded — the method is saved, and only this one means saved. canceled — abandoned or refused; see last_setup_error.
processing, succeeded, canceled, requires_action "succeeded"
True when the buyer completed 3D Secure while saving this payment method.
false
When the setup intent was last updated, as an ISO 8601 timestamp.
"2026-01-01T12:00:00.000Z"
The user saving the payment method. Null when the buyer is a company rather than a user.