Sign in
Payment Sessions

Get a payment session

Changed on

Retrieves a single payment session by its ID, including its current status, balances, and associated metadata. The API key must have permission to access the requested session.

get/v2/payment-sessions/{paymentSessionId}

Request

  • Base URL: https://api.cdp.coinbase.com/platform
  • URL: https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}
  • 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.

Response

Successfully retrieved payment session.

paymentSessionIdstring

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

entityIdstring

The ID of the entity that owns the payment session.

amountstring

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

assetstring

The symbol of the asset (e.g., eth, usd, usdc, usdt).

autoCaptureboolean

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.

status'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'

The most recent meaningful event on the payment session. For session-level milestones the value is one of created or canceled. For action outcomes the value follows the pattern {action}_{result} — e.g. authorization_succeeded, capture_pending, refund_failed.

urlstring uri

A valid HTTP or HTTPS URL.

x402Urlstring uri

A valid HTTP or HTTPS URL.

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 this payment session, from the merchant's own system—not visible to the payer. It must not contain personally identifiable information (PII) or payment credentials.

cancellationReasonstring

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

createdAtstring date-time

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

updatedAtstring date-time

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

Example response

{
  "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "entityId": "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "amount": "1.00",
  "asset": "usdc",
  "target": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "network": "base"
  },
  "autoCapture": false,
  "expiries": {
    "authorizationExpiresAt": "2025-12-31T23:59:59.000Z",
    "captureExpiresAt": "2026-01-15T23:59:59.000Z",
    "refundExpiresAt": "2026-02-15T23:59:59.000Z"
  },
  "status": "created",
  "balances": {
    "capturable": "0",
    "captured": "0",
    "refundable": "0",
    "refunded": "0"
  },
  "url": "https://payments.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "x402Url": "https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402",
  "redirect": {
    "failureUrl": "https://merchant.example.com/payment/failed",
    "successUrl": "https://merchant.example.com/payment/success"
  },
  "customerDisplay": {
    "merchantName": "Acme Store",
    "displayAmount": {
      "amount": "1.37",
      "currency": "cad"
    }
  },
  "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"
}

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 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 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_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_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 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 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 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 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 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

  • 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 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