Skip to main content
POST
Create Setup Intent

Authorizations

Authorization
string
header
required

An Account API key, an App API key, an account access token, an account-scoped user token, or a user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************. See Auth & API keys for how to get each one.

Scopes

payment:charge

Headers

Idempotency-Key
string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255
Example:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date
string

Pins the request to a dated API version.

Example:

"2026-11-14-1"

Body

application/json
account_id
string
required

The account to save the payment method for, prefixed biz_.

Example:

"biz_xxxxxxxxxxxxxx"

confirmation_token
string | null

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.

Example:

"ctok_xxxxxxxxxxxxxx"

currency
string | null

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.

Example:

"usd"

email
string | null

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.

Example:

"dana@shinetime.example"

metadata
object | null

Custom metadata to attach to the setup intent. Returned on the setup intent and its webhooks.

Example:
owner_id
string | null

Who the saved payment method belongs to. Pass account_id to save it on the account itself, which needs payment:charge on the account. Pass your own user ID, prefixed user_, to save it on the authenticated user. Omit it to save it on the buyer: the caller when it is the buyer, otherwise the user the confirmation token names. Not available with payment_method_id, which keeps its current owner, or with purpose.

Example:

"biz_xxxxxxxxxxxxxx"

payment_method_id
string | null

An existing payment method to re-verify and save, prefixed payt_. Provide this or confirmation_token, not both. Not available to a buyer credential.

Example:

"payt_xxxxxxxxxxxxxx"

purpose
enum<string> | null

What the saved payment method will pay for. Set to ads_billing when saving a card to pay for Whop Ads on account_id: the card is verified by Whop Ads, the merchant that charges it, which helps minimize security declines on ad payments, and it requires ad_campaign:create on account_id. Omit it for any other payment method.

Available options:
ads_billing,
null
Example:

"ads_billing"

return_url
string | null

Where the buyer continues after completing an off-site step. An absolute https URL without credentials, at most 2,048 characters.

Example:

"https://shinetime.example/billing/saved"

three_ds_level
enum<string> | null

3D Secure behavior for supported on-session card payments. mandate_challenge requires a 3DS challenge before payment processing; mandate_if_required mandates a challenge only when the payment processor requires it; frictionless_if_required uses the regular frictionless 3DS flow. Payments of $1,000 or more use mandate_if_required unless mandate_challenge is selected. Risk and authentication recovery requirements can override the preference. Applies to this setup only, and only while the buyer is present: ignored with payment_method_id, which re-verifies off session. Not available with purpose: ads_billing. Defaults to frictionless_if_required.

Available options:
mandate_challenge,
mandate_if_required,
frictionless_if_required,
null
Example:

"mandate_challenge"

Response

setup intent created from a confirmation token

account_id
string | null
required

The account the payment method is saved for, prefixed biz_.

Example:

"biz_xxxxxxxxxxxxxx"

checkout_configuration_id
string | null
required

The checkout configuration this setup was created through, prefixed ch_. Null for a setup created through this API rather than a hosted checkout.

Example:

null

client_secret
string | null
required

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.

Example:

"sint_xxxxxxxxxxxxxx_secret_vdefault_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

created_at
string
required

When the setup intent was created, as an ISO 8601 timestamp.

Example:

"2026-01-01T12:00:00.000Z"

id
string
required

Setup intent ID, prefixed sint_.

Example:

"sint_xxxxxxxxxxxxxx"

last_setup_error
object | null
required

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.

member_id
string | null
required

The buyer's member record on the account, prefixed mber_. Null without the member:basic:read permission, unless the caller is the buyer.

Example:

"mber_xxxxxxxxxxxxxx"

metadata
object | null
required

Your own key-value data attached when the setup intent was created.

Example:
payment_instrument
object | null
required

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, expiry, and network transaction id when it was a card. Null until a method was collected.

payment_method_id
string | null
required

The saved payment method, prefixed payt_, ready to charge with Create Payment. Null until the setup has succeeded.

Example:

"payt_xxxxxxxxxxxxxx"

payment_method_type
enum<string> | null
required

The kind of instrument being saved, for example card or us_bank_account.

Available options:
acss_debit,
addi,
affirm,
afterpay_clearpay,
alipay,
alipayhk,
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_present,
card_installments_three,
card_installments_six,
card_installments_twelve,
cashapp,
claritypay,
coinbase,
crypto,
crypto_subscription,
custom,
customer_balance,
demo_pay,
duitnow_qr,
efecty,
eps,
eu_bank_transfer,
fpx,
flex_pay,
gb_bank_transfer,
gcash,
giropay,
google_pay,
gopay,
grabpay,
id_bank_transfer,
ideal,
interac,
international_bank_wire,
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,
paypal_express,
paypay,
payto,
payto_email,
payto_phone,
payto_bank_account,
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,
tabby,
tamara,
touch_n_go,
twint,
upi,
us_bank_account,
us_bank_transfer,
venmo,
verve,
vipps,
webpay,
wechat_pay,
whop_pay,
yape,
zip,
coinflow,
unknown
Example:

"acss_debit"

return_url
string | null
required

Where the buyer lands after completing an off-site step, or null to leave them where they are.

Example:

"https://shinetime.example/billing/saved"

status
enum<string>
required

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.

Available options:
processing,
succeeded,
canceled,
requires_action
Example:

"requires_action"

three_ds_level
enum<string> | null
required

3D Secure behavior for supported on-session card payments. mandate_challenge requires a 3DS challenge before payment processing; mandate_if_required mandates a challenge only when the payment processor requires it; frictionless_if_required uses the regular frictionless 3DS flow. Payments of $1,000 or more use mandate_if_required unless mandate_challenge is selected. Risk and authentication recovery requirements can override the preference. The setting requested for this setup, or null when unset.

Available options:
mandate_challenge,
mandate_if_required,
frictionless_if_required,
null
Example:

"frictionless_if_required"

three_ds_verified
boolean
required

True when the buyer completed 3D Secure while saving this payment method.

Example:

false

updated_at
string
required

When the setup intent was last updated, as an ISO 8601 timestamp.

Example:

"2026-01-01T12:00:00.000Z"

user
object | null
required

The user saving the payment method. Null when the buyer is a company rather than a user.