Sign in
Setup Intents

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.

post/setup_intents

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

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

Request body

account_idstring required

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

confirmation_tokenstring nullable

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.

currencystring nullable

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.

emailstring nullable

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.

metadataobject nullable

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

payment_method_idstring nullable

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

return_urlstring nullable

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

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "confirmation_token": "ctok_xxxxxxxxxxxxxx",
  "currency": "usd",
  "email": "dana@shinetime.example",
  "metadata": {
    "customer_id": "cus_4417"
  },
  "payment_method_id": "payt_xxxxxxxxxxxxxx",
  "return_url": "https://shinetime.example/billing/saved"
}

Response

setup intent created from a confirmation token

account_idstring nullable required

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

checkout_configuration_idstring nullable required

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

client_secretstring nullable 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.

created_atstring required

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

idstring required

Setup intent ID, prefixed sint_.

member_idstring nullable required

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

metadataobject nullable required

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

payment_method_idstring nullable required

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

payment_method_type'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' required

The different types of payment methods that can be used.

return_urlstring nullable required

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

status'processing' | 'succeeded' | 'canceled' | 'requires_action' 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.

three_ds_verifiedboolean required

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

updated_atstring required

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

Example response

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "client_secret": "sint_xxxxxxxxxxxxxx_secret_vdefault_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-01-01T12:00:00.000Z",
  "id": "sint_xxxxxxxxxxxxxx",
  "last_setup_error": {
    "code": "enrollment_declined",
    "message": "The bank declined the enrollment."
  },
  "member_id": "mber_xxxxxxxxxxxxxx",
  "metadata": {
    "customer_id": "cus_4417"
  },
  "payment_instrument": {
    "card": {
      "brand": "visa",
      "exp_month": 10,
      "exp_year": 2031,
      "issuer_identification_number": "41111111",
      "last4": "4242"
    },
    "display_name": "Visa •••• 4242",
    "icons": {
      "card": {
        "dark": {
          "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
          "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
          "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
          "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
        },
        "light": {
          "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
          "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
          "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
          "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
        }
      },
      "square": {
        "dark": {
          "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
          "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
          "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
          "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
        },
        "light": {
          "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
          "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
          "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
          "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
        }
      }
    },
    "payment_method_type": "card"
  },
  "payment_method_id": "payt_xxxxxxxxxxxxxx",
  "payment_method_type": "acss_debit",
  "return_url": "https://shinetime.example/billing/saved",
  "status": "succeeded",
  "updated_at": "2026-01-01T12:00:00.000Z",
  "user": {
    "id": "user_xxxxxxxxxxxxxx",
    "name": "Dana Whitfield",
    "profile_picture": {
      "url": "https://ui-avatars.com/api/"
    },
    "username": "danawhitfield"
  }
}

Changes