A valid request URL is required to generate request examples{
"id": "<string>",
"object": "payment_intent",
"merchant_id": "<string>",
"livemode": true,
"client_secret": "<string>",
"customer": "<string>",
"amount": 123,
"currency": "<string>",
"capture_method": "automatic",
"status": "requires_payment_method",
"payment_method": "<string>",
"latest_charge_id": "<string>",
"metadata": {},
"created_at": 123,
"updated_at": 123,
"setup_future_usage": "off_session",
"tokenization": {
"provider": "<string>",
"tokenization_key": "<string>"
},
"reference": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "invalid currency"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"type": "card_error",
"code": "PAYMENT_DECLINED",
"message": "payment was declined",
"decline_code": "insufficient_funds",
"decline_type": "authorization",
"retryable": true
},
"payment_intent": {
"id": "pi_2pXq",
"object": "payment_intent",
"merchant_id": "mer_7kRzDef",
"livemode": false,
"client_secret": null,
"customer": null,
"amount": 5000,
"currency": "USD",
"capture_method": "automatic",
"status": "requires_payment_method",
"payment_method": null,
"latest_charge_id": null,
"metadata": {},
"created_at": 1700000000,
"updated_at": 1700000000
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"type": "api_error",
"code": "GATEWAY_ERROR",
"message": "payment was not sent to the payment processor and no money moved; confirm again with a new Idempotency-Key"
}
}Create a payment intent
Creates a payment intent for a given amount and currency. Supplying a
payment_method confirms it in the same request (create-and-confirm),
in which case a decline returns 402 with the intent embedded.
A valid request URL is required to generate request examples{
"id": "<string>",
"object": "payment_intent",
"merchant_id": "<string>",
"livemode": true,
"client_secret": "<string>",
"customer": "<string>",
"amount": 123,
"currency": "<string>",
"capture_method": "automatic",
"status": "requires_payment_method",
"payment_method": "<string>",
"latest_charge_id": "<string>",
"metadata": {},
"created_at": 123,
"updated_at": 123,
"setup_future_usage": "off_session",
"tokenization": {
"provider": "<string>",
"tokenization_key": "<string>"
},
"reference": "<string>"
}{
"error": {
"code": "INVALID_REQUEST",
"message": "invalid currency"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"type": "card_error",
"code": "PAYMENT_DECLINED",
"message": "payment was declined",
"decline_code": "insufficient_funds",
"decline_type": "authorization",
"retryable": true
},
"payment_intent": {
"id": "pi_2pXq",
"object": "payment_intent",
"merchant_id": "mer_7kRzDef",
"livemode": false,
"client_secret": null,
"customer": null,
"amount": 5000,
"currency": "USD",
"capture_method": "automatic",
"status": "requires_payment_method",
"payment_method": null,
"latest_charge_id": null,
"metadata": {},
"created_at": 1700000000,
"updated_at": 1700000000
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "card_error",
"decline_code": "<string>",
"decline_type": "authorization",
"retryable": true,
"doc_url": "<string>"
}
}{
"error": {
"type": "api_error",
"code": "GATEWAY_ERROR",
"message": "payment was not sent to the payment processor and no money moved; confirm again with a new Idempotency-Key"
}
}Authorizations
A merchant secret key (sk_…) sent as Authorization: Bearer <key>.
Headers
A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.
255Merchant ID when an authorized Platform acts for a connected Merchant. Omit when authenticating directly as that Merchant.
^mer_[0-9A-Za-z]{14}$Body
Amount to collect, in minor units.
Three-letter ISO currency code.
Save the new card for future payments after collecting consent. Requires a customer.
off_session automatic captures on confirmation; manual authorizes, then you capture later.
automatic, manual Payment method id (pm_…). When present, the intent is confirmed in the same request.
Mandate id authorizing a merchant-initiated charge.
Who initiated the charge. merchant (off-session) requires a secret key.
customer, merchant Your order number or other reference (max 256 chars).
Customer id (cus_…) to attach.
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.
Show child attributes
Show child attributes
Response
The created payment intent.
A request to collect a payment from a customer, tracking the payment through its attempts until it succeeds or is canceled.
The payment intent id (pi_…).
Always payment_intent.
payment_intent The owning merchant (mer_…).
Whether this intent was created with a live (true) or test (false) key.
Returned when the intent is created or confirmed; null on capture, cancel, and list responses.
The attached customer (cus_…). Null unless a customer was passed at creation.
The amount to collect, in minor units. Always positive.
Three-letter ISO currency code. USD, EUR, and GBP are supported.
automatic captures the charge on confirmation. manual authorizes a hold; capture it later via POST /payment_intents/{id}/capture.
automatic, manual 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).
requires_payment_method, requires_confirmation, requires_action, requires_capture, processing, succeeded, canceled The attached payment method (pm_…). Nullable; cleared on a decline so a retry can attach a different method.
The most recent charge produced by this intent (ch_…).
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.
Show child attributes
Show child attributes
Unix epoch seconds.
Unix epoch seconds, bumped on every mutation.
Save the new card for future payments after collecting consent. Requires a customer.
off_session Browser-safe card-fields configuration returned with client_secret on publishable-key requests. Null when card collection is not available.
Show child attributes
Show child attributes
Your order number or other reference. Max 256 characters.