Create a payment session

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

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

Body

application/json

A request to create a new payment session.

amount

string

required

A decimal representation of the payment amount, denominated in asset.

Example:

"1.00"

asset

string

required

The symbol of the asset for the payment amount.

Required string length: 1 - 42

Example:

"usdc"

target

Payment Target Wallet · object

required

The target of the payment session.

Payment Target Wallet
Account

Show child attributes

Example:

{
  "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "network": "base"
}

expiries

object

Deadlines for each stage of the payment session lifecycle. All fields are optional; when omitted from a create request, the following defaults apply: authorizationExpiresAt = now + 1 day, captureExpiresAt = now + 7 days, refundExpiresAt = now + 30 days.

Expiries must satisfy authorizationExpiresAt ≤ captureExpiresAt ≤ refundExpiresAt. The API returns a 400 error if this constraint is violated.

Each deadline acts as a guard — after it passes, the corresponding action is rejected, but the session remains in its current status. No automatic state transitions occur; the merchant must take explicit action (e.g., cancel or void) to move the session to a terminal state.

Show child attributes

Example:

{
  "authorizationExpiresAt": "2025-12-31T23:59:59.000Z",
  "captureExpiresAt": "2026-01-15T23:59:59.000Z",
  "refundExpiresAt": "2026-02-15T23:59:59.000Z"
}

redirect

object

Redirect URLs used to direct the payer after a web-based payment flow completes or fails.

Show child attributes

Example:

{
  "failureUrl": "https://merchant.example.com/payment/failed",
  "successUrl": "https://merchant.example.com/payment/success"
}

autoCapture

boolean

default:false

When true, a capture is automatically created after a successful authorization. When false or omitted, the merchant must create captures manually via the captures endpoint.

Example:

false

externalReferenceId

string

An arbitrary client-supplied identifier for the payment session, such as an order ID or invoice number from the caller's own system. Not interpreted by CDP — stored and returned as-is.

Maximum string length: 256

Example:

"merchant-order-abc123"

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.

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

Response

Successfully created payment session.

Tracks the full lifecycle of a payment from creation through settlement. Typical flow: Create → Authorize (via payment method) → Capture. Optional: Void to release uncaptured funds, or Refund to return captured funds.

paymentSessionId

string

The unique identifier of the payment session.

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

Example:

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

entityId

string

The ID of the entity that owns the payment session.

Example:

"entity_af2937b0-9846-4fe7-bfe9-ccc22d935114"

amount

string

A decimal representation of the payment amount, denominated in asset.

Example:

"1.00"

asset

string

The symbol of the asset for the payment amount.

Required string length: 1 - 42

Example:

"usdc"

target

Payment Target Wallet · object

The target of the payment session.

Payment Target Wallet
Account

Show child attributes

Example:

{
  "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "network": "base"
}

autoCapture

boolean

default:false

When true, a capture is automatically created after a successful authorization. When false or omitted, the merchant must create captures manually via the captures endpoint.

Example:

false

expiries

object

Deadlines for each stage of the payment session lifecycle. All fields are optional; when omitted from a create request, the following defaults apply: authorizationExpiresAt = now + 1 day, captureExpiresAt = now + 7 days, refundExpiresAt = now + 30 days.

Expiries must satisfy authorizationExpiresAt ≤ captureExpiresAt ≤ refundExpiresAt. The API returns a 400 error if this constraint is violated.

Each deadline acts as a guard — after it passes, the corresponding action is rejected, but the session remains in its current status. No automatic state transitions occur; the merchant must take explicit action (e.g., cancel or void) to move the session to a terminal state.

Show child attributes

Example:

{
  "authorizationExpiresAt": "2025-12-31T23:59:59.000Z",
  "captureExpiresAt": "2026-01-15T23:59:59.000Z",
  "refundExpiresAt": "2026-02-15T23:59:59.000Z"
}

source

Payment Source Wallet · object

The source of the payment session. Set after a successful authorization. Not present before authorization.

Payment Source Wallet
Payment Source Coinbase

Show child attributes

Example:

{
  "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
  "network": "base",
  "asset": "usdc"
}

status

enum<string>

The most recent meaningful event on the payment session.

Available options:

created,

canceled,

authorization_pending,

authorization_succeeded,

authorization_failed,

capture_pending,

capture_succeeded,

capture_failed,

void_pending,

void_succeeded,

void_failed,

refund_pending,

refund_succeeded,

refund_failed

Example:

"created"

balances

object

Running totals tracking how funds move through the session. All amounts are decimal representations denominated in the session's asset.

Show child attributes

Example:

{
  "capturable": "1.00",
  "captured": "0",
  "refundable": "0",
  "refunded": "0"
}

authorizations

object[]

The authorizations for this payment session.

Show child attributes

captures

object[]

The captures for this payment session.

Show child attributes

voids

object[]

The voids for this payment session.

Show child attributes

refunds

object[]

The refunds for this payment session.

Show child attributes

url

string<uri>

A URL to the hosted payment page where the payer can complete this payment session.

Required string length: 11 - 2048

Pattern: ^https?://.*$

Example:

"https://pay.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"

redirect

object

Redirect URLs used to direct the payer after a web-based payment flow completes or fails.

Show child attributes

Example:

{
  "failureUrl": "https://merchant.example.com/payment/failed",
  "successUrl": "https://merchant.example.com/payment/success"
}

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.

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

externalReferenceId

string

An arbitrary client-supplied identifier for the payment session, such as an order ID or invoice number from the caller's own system. Not interpreted by CDP — stored and returned as-is.

Maximum string length: 256

Example:

"merchant-order-abc123"

cancellationReason

string

The reason the payment session was canceled. Only present when the session has been canceled.

Example:

"Customer requested cancellation."

createdAt

string<date-time>

The UTC ISO 8601 timestamp at which the payment session was created.

Example:

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

updatedAt

string<date-time>

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

Example:

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

CDP PAYMENTS API

SANDBOX

REST API

Authorizations

Headers

Body

Response