Sign in
Payment Sessions

Authorize a payment session with a wallet

Changed on

Customer-initiated. Authorizes a payment session using the payer's wallet. The payer signs the payloads themselves, so this call is unauthenticated. The session must be in created status.

The optionId must match one of the options returned by the Get Wallet Authorization Options endpoint. Include the signed payloads for the selected option.

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/wallet

Request

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

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

optionIdstring required

The identifier of the chosen authorization option. Must match an optionId from the wallet authorization options response.

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

{
  "optionId": "opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "signedPayloads": [
    {
      "payloadId": "payload_af2937b0-9846-4fe7-bfe9-ccc22d935114",
      "signature": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
    }
  ]
}

Response

Successfully created wallet 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

  • 156440e9f8dfRevision changes
    • warning

      added the new incompatible_event_types enum value to the response property for the response status

    • warning

      added the new incompatible_event_types enum value to the response property for the response status

    • warning

      added the new incompatible_event_types enum value to the response property for the response status

    • warning

      added the new incompatible_event_types enum value to the response property for the response status

    • warning

      added the new incompatible_event_types enum value to the response property for the response status

    • warning

      added the new incompatible_event_types enum value to the response property for the response status

    • warning

      added the new invalid_webhook_headers enum value to the response property for the response status

    • warning

      added the new invalid_webhook_headers enum value to the response property for the response status

    • warning

      added the new invalid_webhook_headers enum value to the response property for the response status

    • warning

      added the new invalid_webhook_headers enum value to the response property for the response status

    • warning

      added the new invalid_webhook_headers enum value to the response property for the response status

    • warning

      added the new invalid_webhook_headers enum value to the response property for the response status

    • warning

      added the new invalid_webhook_url enum value to the response property for the response status

    • warning

      added the new invalid_webhook_url enum value to the response property for the response status

    • warning

      added the new invalid_webhook_url enum value to the response property for the response status

    • warning

      added the new invalid_webhook_url enum value to the response property for the response status

    • warning

      added the new invalid_webhook_url enum value to the response property for the response status

    • warning

      added the new invalid_webhook_url enum value to the response property for the response status

    • warning

      added the new mandate_action_pending enum value to the response property for the response status

    • warning

      added the new mandate_action_pending enum value to the response property for the response status

    • warning

      added the new mandate_action_pending enum value to the response property for the response status

    • warning

      added the new mandate_action_pending enum value to the response property for the response status

    • warning

      added the new mandate_action_pending enum value to the response property for the response status

    • warning

      added the new mandate_action_pending enum value to the response property for the response status

    • warning

      added the new mandate_canceled enum value to the response property for the response status

    • warning

      added the new mandate_canceled enum value to the response property for the response status

    • warning

      added the new mandate_canceled enum value to the response property for the response status

    • warning

      added the new mandate_canceled enum value to the response property for the response status

    • warning

      added the new mandate_canceled enum value to the response property for the response status

    • warning

      added the new mandate_canceled enum value to the response property for the response status

    • warning

      added the new mandate_expired enum value to the response property for the response status

    • warning

      added the new mandate_expired enum value to the response property for the response status

    • warning

      added the new mandate_expired enum value to the response property for the response status

    • warning

      added the new mandate_expired enum value to the response property for the response status

    • warning

      added the new mandate_expired enum value to the response property for the response status

    • warning

      added the new mandate_expired enum value to the response property for the response status

    • warning

      added the new mandate_invalid_status enum value to the response property for the response status

    • warning

      added the new mandate_invalid_status enum value to the response property for the response status

    • warning

      added the new mandate_invalid_status enum value to the response property for the response status

    • warning

      added the new mandate_invalid_status enum value to the response property for the response status

    • warning

      added the new mandate_invalid_status enum value to the response property for the response status

    • warning

      added the new mandate_invalid_status enum value to the response property for the response status

    • warning

      added the new mandate_policy_violation enum value to the response property for the response status

    • warning

      added the new mandate_policy_violation enum value to the response property for the response status

    • warning

      added the new mandate_policy_violation enum value to the response property for the response status

    • warning

      added the new mandate_policy_violation enum value to the response property for the response status

    • warning

      added the new mandate_policy_violation enum value to the response property for the response status

    • warning

      added the new mandate_policy_violation enum value to the response property for the response status

    • warning

      added the new mandate_revoked enum value to the response property for the response status

    • warning

      added the new mandate_revoked enum value to the response property for the response status

    • warning

      added the new mandate_revoked enum value to the response property for the response status

    • warning

      added the new mandate_revoked enum value to the response property for the response status

    • warning

      added the new mandate_revoked enum value to the response property for the response status

    • warning

      added the new mandate_revoked enum value to the response property for the response status

    • warning

      added the new solana enum value to the ////// response property for the response status

    • warning

      added the new solana enum value to the ////////// response property for the response status

    • warning

      added the new solana-devnet enum value to the ////// response property for the response status

    • warning

      added the new solana-devnet enum value to the ////////// response property for the response status

    • warning

      added the new subscription_limit_exceeded enum value to the response property for the response status

    • warning

      added the new subscription_limit_exceeded enum value to the response property for the response status

    • warning

      added the new subscription_limit_exceeded enum value to the response property for the response status

    • warning

      added the new subscription_limit_exceeded enum value to the response property for the response status

    • warning

      added the new subscription_limit_exceeded enum value to the response property for the response status

    • warning

      added the new subscription_limit_exceeded enum value to the response property for the response status

  • 229ed860a74bRevision changes
    • warning

      added the new mfa_challenge_not_found enum value to the response property for the response status

    • warning

      added the new mfa_challenge_not_found enum value to the response property for the response status

    • warning

      added the new mfa_challenge_not_found enum value to the response property for the response status

    • warning

      added the new mfa_challenge_not_found enum value to the response property for the response status

    • warning

      added the new mfa_challenge_not_found enum value to the response property for the response status

    • warning

      added the new mfa_challenge_not_found enum value to the response property for the response status

    • warning

      added the new operation_in_progress enum value to the response property for the response status

    • warning

      added the new operation_in_progress enum value to the response property for the response status

    • warning

      added the new operation_in_progress enum value to the response property for the response status

    • warning

      added the new operation_in_progress enum value to the response property for the response status

    • warning

      added the new operation_in_progress enum value to the response property for the response status

    • warning

      added the new operation_in_progress enum value to the response property for the response status