Sign in
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

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"
  },
  "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"
  }
}

Changes