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.

purpose'ads_billing' nullable

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.

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",
  "purpose": "ads_billing",
  "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' | '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_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' | 'tabby' | '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

Changed in 14 of the 74 revisions of this API.52721

  • 73dd0533cd811See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

  • 86b97292852d1See the full diff
    • ●

      added the new alipayhk enum value to the //// response property for the response status

      response-property-enum-value-added

  • 7fcefabddb0a1See the full diff
    • ●

      added the new tabby enum value to the //// response property for the response status

      response-property-enum-value-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 140d015b99663417See the full diff
    • ▲

      added the new required request property

      new-required-request-property

    • ▲

      removed subschema #1: CreateSetupIntentInputWithConfirmationToken subschema #2: CreateSetupIntentInputWithPaymentMethodId from the request body oneOf list

      request-body-one-of-removed

    • ▲

      removed the success response with the status

      response-success-status-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ○

      the security scope member:basic:read was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

    • ○

      the security scope member:email:read was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

    • ○

      api tag Setup Intents added

      api-tag-added

    • ○

      api tag Setup intents removed

      api-tag-removed

    • ○

      added the new optional header request parameter Api-Version-Date to all path's operations

      new-optional-request-default-parameter-to-existing-path

    • ○

      added the new optional header request parameter Idempotency-Key

      new-optional-request-parameter

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      added the success response with the status

      response-success-status-added

  • c19acf2e254811See the full diff
    • ●

      added the new touch_n_go enum value to the / response property for the response status

      response-property-enum-value-added

    • ○

      removed the bizum enum value from the / response property for the response status

      response-property-enum-value-removed

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 2fa9dfe9535a5See the full diff
    • ●

      added the new mercado_pago_ar enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new mercado_pago_mx enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new nupay enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new opay enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new verve enum value to the / response property for the response status

      response-property-enum-value-added

  • 8473fa1d1f473See the full diff
    • ●

      added the new oney enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new oney_3x enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new oney_4x enum value to the / response property for the response status

      response-property-enum-value-added

  • 697924df40d122See the full diff
    • ▲

      added the new required request property /

      new-required-request-property

    • ▲

      added the new required request property /

      new-required-request-property

    • ●

      removed the request property /

      request-property-removed

    • ●

      removed the request property /

      request-property-removed

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 4da7133b2de72See the full diff
    • ●

      added the new flex_pay enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new gcash enum value to the / response property for the response status

      response-property-enum-value-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 86d0a97abfe55See the full diff
    • ●

      added the new accel enum value to the ////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new culiance enum value to the ////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new nyce enum value to the ////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new pulse enum value to the ////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new star enum value to the ////// response property for the response status

      response-property-enum-value-added

    This revision also has 42 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 74 revisions, 1 has no diff computed.