Skip to main content
A payment intent represents a single intent to collect a card payment from a buyer. It is the object that actually tracks the money: how much is being collected, and where that collection stands — from pending (nothing paid yet) through processing (a payment is in flight) to a terminal succeeded or canceled. Create one with POST /payments/payment-intent and collect it with Payment Elements. Payment intent responses include a clientSecret scoped to that intent. It is the browser’s credential for that intent: it authorizes loading the payment form and confirming the payment, which advances the intent from pending to processing. It grants nothing else. Treat the client secret as sensitive. Pass it to the browser, but never log it or persist it.

​
Statuses

​
Metadata

metadata is stored on the intent and echoed back on every read — use it to carry your own order reference (for example { "orderId": "ord_123" }) so you can correlate a payment intent to the right order without extra lookups.

​
Payment methods

By default a payment intent offers every supported payment method: card, apple_pay, and google_pay. To offer only some of them, pass allowedPaymentMethods when you create or update the intent, for example ["card"] to turn off wallets for a single payment. allowedPaymentMethods is returned exactly as you set it, and is omitted when every supported method is allowed. Wallets such as Apple Pay and Google Pay only appear on devices and browsers that support them.

​
Tracking payment state

Subscribe to the payments.payment_intent.updated webhook and read the intent back with GET /payments/payment-intent/{id} when it fires. If you cannot receive webhooks, poll that endpoint instead. Fulfill when status is "succeeded" — that is the only signal a payment has settled; never grant goods or services on a browser-side signal alone.

The payment intent object. Its status tracks the payment from creation through settlement.

​
id
string
required

Unique identifier for the payment intent.

​
status
enum<string>
required

Status of the payment intent. pending intents have not been paid yet; processing intents have a payment in flight awaiting settlement; succeeded intents have a confirmed settled payment; canceled intents were canceled and can no longer be paid.

Available options:
pending,
processing,
succeeded,
canceled
​
amount
integer
required

Payment amount in the smallest unit of currency.

​
currency
enum<string>
required

ISO currency code for the payment. Supported currencies are usd and eur.

Available options:
usd,
eur
​
createdAt
string<date-time>
required

ISO-8601 timestamp the payment intent was created at.

​
updatedAt
string<date-time>
required

ISO-8601 timestamp the payment intent last changed status.

​
metadata
object

Merchant-defined metadata stored on the payment intent and echoed in payment intent responses and the payment-intent success webhook.

​
clientSecret
string

Sensitive PaymentIntent-scoped browser capability. Do not log or store it in browser persistence.

​
allowedPaymentMethods
enum<string>[]

Payment methods the merchant allows, exactly as set on create or update. Omitted when all supported methods are allowed.

Payment method available for an acquiring PaymentIntent checkout.

Available options:
card,
apple_pay,
google_pay