Sign in
Setup Intents

Save Card Details

Saves a card for later charges from card details the caller holds itself, for integrators whose own systems are PCI compliant. Card details are accepted only on the vault host, where the card is tokenized before it reaches Whop; the official SDKs route this operation there, and raw card details sent to the regular host are refused. (Whop's own clients, which tokenize with the Basis Theory SDK, send the resulting token intent id to the regular host.) The setup runs in the background: poll Retrieve setup status for its outcome and for anything the buyer must still do, such as 3D Secure. Once it succeeds, the saved payment method arrives on the setup_intent.succeeded webhook and in List payment methods for the member.

post/setup_intents/direct

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 the card is saved for, prefixed biz_.

currencystring nullable

The currency the card will be charged in, as a three-letter code. Defaults to usd.

member_idstring nullable

The member the card belongs to, prefixed mber_. When omitted the buyer is resolved from billing_details.email.

metadataobject nullable

Custom metadata to attach to the setup.

return_urlstring nullable

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

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "billing_details": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1 Market St",
      "line2": "Suite 400",
      "postal_code": "94105",
      "state": "CA"
    },
    "email": "dana@shinetime.example",
    "name": "Dana Shine",
    "phone": "+14155550123"
  },
  "currency": "usd",
  "member_id": "mber_xxxxxxxxxxxxxx",
  "metadata": {
    "crm_id": "C-88"
  },
  "payment_method": {
    "card": {
      "details": {
        "cvc": "123",
        "exp_month": 12,
        "exp_year": 2031,
        "number": "4242424242424242"
      },
      "network_transaction_id": "016153570198200"
    },
    "type": "card"
  },
  "return_url": "https://shinetime.example/billing/saved"
}

Response

setup started from card details

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 3 of the 74 revisions of this API.21

  • 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

  • 140d015b99661See the full diff
    • ○

      endpoint added

      endpoint-added

Of the 74 revisions, 1 has no diff computed.