Sign in
Payment Sessions

Authorize a payment session with a mandate

Changed on

Merchant-initiated. The merchant draws against a mandate in approval_succeeded status using the mandate's existing approval, so no fresh signature is required and the customer does not need to be present. The session must be in created status and the mandate must be in approval_succeeded status. When more than one mandate condition applies, the first match wins: an in-flight approval or revocation returns 409 (mandate_action_pending); revokedAt set returns 422 (mandate_revoked); canceledAt set returns 422 (mandate_canceled); a past expiresAt returns 400 (mandate_expired); any other status returns 422 (mandate_invalid_status).

It requires API key authentication: unlike the payer-present wallet flow there is no per-call signature to prove consent, so the merchant authenticates as the party entitled to draw against the mandate.

The charge must fall within the mandate's policy. Exceeding maxPerAuthorization or maxPerPeriod returns 422 (mandate_policy_violation).

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. If autoCapture is enabled on the session, a capture is automatically created after a successful authorization.

post/v2/payment-sessions/{paymentSessionId}/authorizations/mandate

Request

  • Base URL: https://api.cdp.coinbase.com/platform
  • URL: https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/authorizations/mandate
  • Auth: HTTP bearer

Path parameters

paymentSessionIdstring required

The ID of the payment session, a UUID prefixed by paymentSession_.

Example:paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad

The unique identifier of the payment session to authorize.

Headers

X-Idempotency-Keystring

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.

Request body

mandateIdstring required

The ID of the mandate, a UUID prefixed by mandate_.

metadataMetadata

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.

externalReferenceIdstring

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.

Example request

{
  "mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"
}

Response

Successfully created mandate authorization.

authorizationIdstring

The ID of the authorization, a UUID prefixed by authorization_.

paymentSessionIdstring

The ID of the payment session, a UUID prefixed by paymentSession_.

status'pending' | 'succeeded' | 'failed'

The current status of a payment action (authorization, capture, void, or refund).

amountstring

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

messagestring

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

metadataMetadata

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.

externalReferenceIdstring

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.

createdAtstring date-time

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

updatedAtstring date-time

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

Example response

{
  "authorizationId": "authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "status": "succeeded",
  "amount": "1.00",
  "source": {
    "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
    "network": "base",
    "asset": "usdc"
  },
  "onchainTransactions": [
    {
      "transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
      "network": "base"
    }
  ],
  "metadata": {
    "customer_id": "cust_12345"
  },
  "createdAt": "2025-06-15T12:00:00.000Z",
  "updatedAt": "2025-06-15T12:01:00.000Z"
}

Changes