Authorize a payment session with x402
Authorizes a payment session using x402. The session must be in created status.
The client sends no request body. You may supply the base64-encoded x402-compliant payment payload in the optional PAYMENT-SIGNATURE header.
On authorization, a hold is placed on the payer’s funds. The authorization is returned in pending status and transitions asynchronously to succeeded or failed.
402 Payment Required may be returned with an empty body when payment must be supplied before authorization can proceed; that response may include a PAYMENT-REQUIRED header (see the 402 response) describing accepted networks, assets, and amounts.
If autoCapture is enabled on the session, a capture is automatically created after a successful authorization.
Headers
Optional. Base64-encoded (RFC 4648) x402-compliant payment payload.
An optional string request header for making requests safely retryable. When included, duplicate requests with the same key will return identical responses. Refer to our Idempotency docs for more information on using idempotency keys.
1 - 128Path Parameters
The unique identifier of the payment session to authorize with x402.
The ID of the payment session, a UUID prefixed by paymentSession_.
^paymentSession_[a-f0-9\-]{36}$"paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"
Response
Successfully created x402 authorization. The PAYMENT-RESPONSE header is always included on 200 responses.
A hold placed on the payer's funds. Once authorized, the merchant can capture (collect) the funds. Only one authorization is allowed per session.
The unique identifier of the authorization.
^authorization_[a-f0-9\-]{36}$"authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"
The ID of the payment session this authorization belongs to.
^paymentSession_[a-f0-9\-]{36}$"paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"
The current status of the authorization.
pending, succeeded, failed "pending"
A decimal representation of the authorized amount, denominated in the session's asset.
"1.00"
An error that occurred during a payment operation.
{
"code": "insufficient_funds",
"message": "The payer does not have sufficient funds.",
"occurredAt": "2025-06-15T12:00:00.000Z"
}A human-readable message describing the outcome or status for display. Returned for x402 authorizations; omitted for other authorization flows unless documented otherwise.
"Your payment was successfully submitted"
Optional metadata as key-value pairs. Use this to store additional structured information on a resource, such as customer IDs, order references, or any application-specific data. Up to 10 key/value pairs may be provided. Keys and values are both strings. Keys must be ≤ 40 characters; values must be ≤ 500 characters.
{
"customer_id": "cust_12345",
"order_reference": "order-67890"
}The payer for this authorization. For wallet authorizations, this is the blockchain address that signed the payloads. For Coinbase authorizations, this is the authenticated Coinbase account. This value is also reflected on the parent payment session's source field after a successful authorization.
- Payment Source Wallet
- Payment Source Coinbase
{
"address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
"network": "base",
"asset": "usdc"
}The onchain transactions associated with this authorization.
[
{
"transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
"network": "base"
}
]The UTC ISO 8601 timestamp at which the authorization was created.
"2025-06-15T12:00:00.000Z"
The UTC ISO 8601 timestamp at which the authorization was last updated.
"2025-06-15T12:01:00.000Z"