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

Path Parameters

id
string
required

The payment intent id (pi_…).

Body

application/json

Confirm with exactly one of payment_method or payment_token.

payment_method
string

A saved payment method id (pm_…).

payment_token
string

A single-use payment token created by the client-side card form.

mandate
string

Mandate id authorizing a merchant-initiated charge.

client_secret
string

Required when confirming with a publishable key.

initiated_by
enum<string>

merchant requires a secret key.

Available options:
customer,
merchant
billing_details
object | null

Only valid with payment_token. The details are attached to the single-use payment method created from the token, and the address feeds AVS on the authorization. Rejected when payment_method is used.

save_card
boolean

Save the card as this charge runs, creating a reusable payment method for the intent's customer. Only takes effect with payment_token and a customer on the intent; ignored otherwise. Consent details are recorded from customer_acceptance.

customer_acceptance
object | null

How consent to store the card was captured. Only read when save_card is true. Omitted or online records the request IP and user agent; send offline for MOTO keyed entry when the buyer is not using this browser.

Response

The confirmed payment intent.

id
string
required

The payment intent id (pi_…).

object
enum<string>
required

Always payment_intent.

Available options:
payment_intent
merchant_id
string
required

The owning merchant (mer_…).

livemode
boolean
required

Whether this intent was created with a live (true) or test (false) key.

client_secret
string | null
required

Returned when the intent is created or confirmed; null on capture, cancel, and list responses.

customer
string | null
required

The attached customer (cus_…). Null unless a customer was passed at creation.

amount
integer
required

The amount to collect, in minor units. Always positive.

currency
string
required

Three-letter ISO currency code. USD, EUR, and GBP are supported.

capture_method
enum<string>
required

automatic captures the charge on confirmation. manual authorizes a hold; capture it later via POST /payment_intents/{id}/capture.

Available options:
automatic,
manual
status
enum<string>
required

One of requires_payment_method (collect or attach a payment method), requires_confirmation (ready to confirm), processing (payment is in progress), requires_action (the buyer must complete another step), requires_capture (authorized and awaiting manual capture), succeeded (payment completed), or canceled (payment can no longer be completed).

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

The attached payment method (pm_…). Nullable; cleared on a decline so a retry can attach a different method.

latest_charge_id
string | null
required

The most recent charge produced by this intent (ch_…).

metadata
object
required

A string key-value map for storing your own structured data. Up to 50 keys; each key at most 40 characters and each value at most 500 characters.

created_at
integer
required

Unix epoch seconds.

updated_at
integer
required

Unix epoch seconds, bumped on every mutation.

tokenization
object | null

Browser-safe card-fields configuration returned with client_secret on publishable-key requests. Null when card collection is not available.

reference
string

Your order number or other reference. Max 256 characters.

saved_payment_method
string | null

Only present when save_card was requested: the id of the reusable payment method saved for the intent's customer, or null when the save was skipped (no customer) or failed. The charge outcome is independent of this field.