Sign in

v14

latestOpenAPI 3.1.02026-08-083813925.4 MB
Setup intents

Create setup intent

Save a buyer's payment method for later without charging it. Provide a confirmation token for a method the buyer just supplied, or an existing payment method to re-verify. The buyer may still have a step to complete — 3D Secure, a hosted enrollment, linking a bank account — so poll the setup intent's status endpoint for what to do next.

Required permissions:

  • payment:charge
  • member:basic:read
  • member:email:read
post/setup_intents

Request body

OR

Example request

{
  "company_id": "biz_xxxxxxxxxxxxxx",
  "confirmation_token": "ctok_xxxxxxxxxxxxxx",
  "email": "buyer@example.com",
  "return_url": "https://example.com/path"
}

Response

A successful response

client_secretstring nullable required

The credential the buyer's surface presents to poll this setup intent and set its return URL. Returned when the setup is created and still has something to finish — hold on to it, because a later read will not repeat it. Null when the setup settled on the spot and there is nothing left to authorize. It unlocks this setup intent and nothing else; treat it like a password for that one attempt.

created_atstring date-time required

The datetime the setup intent was created.

error_messagestring nullable required

A human-readable error message explaining why the setup intent failed. Null if no error occurred.

idstring required

The unique identifier for the setup intent.

metadataobject nullable required

Custom key-value pairs attached to this setup intent. Null if no metadata was provided.

status'processing' | 'succeeded' | 'canceled' | 'requires_action' required

The status of the setup intent.

three_ds_verifiedboolean required

Whether 3D Secure authentication was completed when this payment method was set up.

Example response

{
  "checkout_configuration": {
    "id": "ch_xxxxxxxxxxxxxxx"
  },
  "client_secret": "sint_xxxxxxxxxxxxxx_secret_v1_xxxx",
  "company": {
    "id": "biz_xxxxxxxxxxxxxx"
  },
  "created_at": "2023-12-01T05:00:00.401Z",
  "error_message": "Your card was declined.",
  "id": "sint_xxxxxxxxxxxxx",
  "payment_method": {
    "card": {
      "exp_month": 42,
      "exp_year": 42,
      "last4": "4242"
    },
    "created_at": "2023-12-01T05:00:00.401Z",
    "id": "payt_xxxxxxxxxxxxx"
  }
}