Skip to main content
POST
/
v2
/
payment-sessions
/
{paymentSessionId}
/
authorizations
/
wallet
Authorize a payment session with a wallet
curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/authorizations/wallet \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "optionId": "opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "signedPayloads": [
    {
      "payloadId": "payload_af2937b0-9846-4fe7-bfe9-ccc22d935114",
      "signature": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
    }
  ],
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  }
}
'
{
  "authorizationId": "authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "status": "pending",
  "amount": "1.00",
  "source": {
    "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
    "network": "base",
    "asset": "usdc"
  },
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  },
  "createdAt": "2025-06-15T12:01:00.000Z",
  "updatedAt": "2025-06-15T12:01:00.000Z"
}

Headers

​
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. The ID of the payment session, a UUID prefixed by paymentSession_.

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

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

Body

application/json

A request to authorize a payment session using a wallet. The payer selects one of the options returned by the wallet authorization options endpoint and submits the signed payloads.

​
optionId
string
required

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

Example:

"opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
signedPayloads
object[]
required

The processed payloads from the payer, corresponding to the payloads in the selected authorization option.

Example:
[
  {
    "payloadId": "payload_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "signature": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
  }
]
​
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:
{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

Response

Successfully created wallet authorization.

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:
{
  "code": "insufficient_funds",
  "message": "The payer does not have sufficient funds.",
  "occurredAt": "2025-06-15T12:00:00.000Z"
}
​
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:
{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}
​
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:
{
  "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
  "network": "base",
  "asset": "usdc"
}
​
onchainTransactions
object[]

The onchain transactions associated with this authorization.

Example:
[
  {
    "transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
    "network": "base"
  }
]
​
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"