Skip to main content
GET
/
v2
/
payment-sessions
/
{paymentSessionId}
Get a payment session
curl --request GET \
  --url https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId} \
  --header 'Authorization: Bearer <token>'
{
  "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "entityId": "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "status": "authorization_succeeded",
  "amount": "1.00",
  "asset": "usdc",
  "target": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "network": "base"
  },
  "source": {
    "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
    "network": "base",
    "asset": "usdc"
  },
  "autoCapture": false,
  "expiries": {
    "authorizationExpiresAt": "2025-12-31T23:59:59.000Z",
    "captureExpiresAt": "2026-01-15T23:59:59.000Z",
    "refundExpiresAt": "2026-02-15T23:59:59.000Z"
  },
  "balances": {
    "capturable": "1.00",
    "captured": "0",
    "refundable": "0",
    "refunded": "0"
  },
  "authorizations": [
    {
      "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"
        }
      ],
      "createdAt": "2025-06-15T12:01:00.000Z",
      "updatedAt": "2025-06-15T12:02:00.000Z"
    }
  ],
  "url": "https://pay.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "redirect": {
    "failureUrl": "https://merchant.example.com/payment/failed",
    "successUrl": "https://merchant.example.com/payment/success"
  },
  "externalReferenceId": "merchant-order-abc123",
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  },
  "createdAt": "2025-06-15T12:00:00.000Z",
  "updatedAt": "2025-06-15T12:05:00.000Z"
}

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.

Path Parameters

​
paymentSessionId
string
required

The unique identifier of the payment session. 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 retrieved 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.

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.

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.

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.

Example:
{
  "capturable": "1.00",
  "captured": "0",
  "refundable": "0",
  "refunded": "0"
}
​
authorizations
object[]

The authorizations for this payment session.

​
captures
object[]

The captures for this payment session.

​
voids
object[]

The voids for this payment session.

​
refunds
object[]

The refunds for this payment session.

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

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.

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"