Skip to main content
POST
Authorize a payment session with x402

Headers

PAYMENT-SIGNATURE
string

Optional. Base64-encoded (RFC 4648) x402-compliant payment payload.

X-External-Reference-Id
string

An optional merchant-provided internal identifier for this x402 authorization, from the merchant's own system—not visible to the payer. A merchant-provided internal identifier for a resource from the merchant's own system—not visible to the payer. It must not contain personally identifiable information (PII) or payment credentials.

Maximum string length: 256
Example:

"merchant-reference-abc123"

X-Customer-Display-Reference-Code
string

A short customer-facing reference code for this x402 authorization, visible to the payer. Equivalent to customerDisplay.referenceCode on JSON authorization requests. Falls back to the session's orderCode when omitted. A short customer-facing reference for an operation, visible to the payer. It must not contain personally identifiable information (PII) or payment credentials.

Maximum string length: 128
Example:

"REF-ABC123"

X-Idempotency-Key
string

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.

Required string length: 1 - 128

Path Parameters

paymentSessionId
string
required

The unique identifier of the payment session to authorize with x402. The ID of the payment session, a UUID prefixed by paymentSession_.

Pattern: ^paymentSession_[a-f0-9\-]{36}$
Example:

"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.

authorizationId
string

The unique identifier of the authorization.

Pattern: ^authorization_[a-f0-9\-]{36}$
Example:

"authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"

paymentSessionId
string

The ID of the payment session this authorization belongs to.

Pattern: ^paymentSession_[a-f0-9\-]{36}$
Example:

"paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"

status
enum<string>

The current status of the authorization.

Available options:
pending,
succeeded,
failed
Example:

"pending"

amount
string

A decimal representation of the authorized amount, denominated in the session's asset.

Example:

"1.00"

error
object

An error that occurred during a payment operation.

Example:
message
string

A human-readable message describing the outcome or status for display. Returned for x402 authorizations; omitted for other authorization flows unless documented otherwise.

Example:

"Your payment was successfully submitted"

metadata
object

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.

Example:
externalReferenceId
string

A merchant-provided internal identifier for this authorization, from the merchant's own system—not visible to the payer. Present only when supplied on the authorization request.

Maximum string length: 256
Example:

"merchant-authorization-abc123"

customerDisplay
Operation Customer Display · object

Customer-facing display data for this authorization, shown to the payer. Present when supplied on the authorization request or when the session's orderCode fallback applies; otherwise omitted.

Example:
source
Payment Source Wallet · object

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.

Example:
onchainTransactions
object[]

The onchain transactions associated with this authorization.

Example:
createdAt
string<date-time>

The UTC ISO 8601 timestamp at which the authorization was created.

Example:

"2025-06-15T12:00:00.000Z"

updatedAt
string<date-time>

The UTC ISO 8601 timestamp at which the authorization was last updated.

Example:

"2025-06-15T12:01:00.000Z"