Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Body

application/json
currency
string
required

Three-letter ISO currency code.

customer
string

Customer id (cus_…) to attach. When present, a mandate is created on confirm and the resulting payment method is linked to this customer.

metadata
object

Up to 50 key-value pairs of arbitrary metadata.

Response

The created setup intent.

id
string
required

Unique identifier for the setup intent (seti_…).

object
enum<string>
required
Available options:
setup_intent
merchant_id
string
required
livemode
boolean
required
customer
string | null
required

The customer this intent is attached to (cus_…), or null if not customer-scoped.

currency
string
required

Three-letter ISO currency code.

status
enum<string>
required

requires_confirmation — initial state; awaiting a client-side token. processing — vault operation is in progress. succeeded — card vaulted and payment method created. canceled — intent was canceled before completion.

Available options:
requires_confirmation,
processing,
succeeded,
canceled
payment_method
string | null
required

The reusable payment method created when the card was vaulted (pm_…). Null until succeeded.

metadata
object
required
created_at
integer
required

Unix epoch seconds.

updated_at
integer
required

Unix epoch seconds.