Payment Sessions

Create a payment session

Changed on Oct 6, 2026

Creates a payment session that defines what is being paid — amount, asset, and target. Optionally configure execution behavior, expiry deadlines, redirect URLs, and metadata.

If expiry deadlines are omitted, sensible defaults are applied (1 day for authorization, 7 days for capture, 30 days for refund). Expiries must be in ascending order — see the expiries object for details and constraints.

Returns the session in created status. Next step: call one of the authorization endpoints (wallet or Coinbase) to authorize the payment.

post/v2/payment-sessions

Request

Base URL: https://api.cdp.coinbase.com/platform
URL: https://api.cdp.coinbase.com/platform/v2/payment-sessions
Auth: HTTP bearer

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

amountstring required

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

assetstring required

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.

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.

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.

Example request

{
  "amount": "1.00",
  "asset": "usd",
  "target": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "network": "base"
  },
  "expiries": {
    "authorizationExpiresAt": "2025-12-31T23:59:59.000Z",
    "captureExpiresAt": "2026-01-15T23:59:59.000Z",
    "refundExpiresAt": "2026-02-15T23:59:59.000Z"
  },
  "redirect": {
    "failureUrl": "https://merchant.example.com/payment/failed",
    "successUrl": "https://merchant.example.com/payment/success"
  },
  "externalReferenceId": "merchant-order-abc123",
  "customerDisplay": {
    "merchantName": "Acme Store",
    "displayAmount": {
      "amount": "1.37",
      "currency": "cad"
    }
  },
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  },
  "compliance": {
    "buyer": {
      "name": "John Doe",
      "address": {
        "line1": "123 Market St",
        "city": "San Francisco",
        "state": "CA",
        "postCode": "94105",
        "countryCode": "US"
      }
    }
  }
}

Response

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

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

externalReferenceIdstring

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

Oct 6, 2026156440e9f8df Revision 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
Sep 25, 2026229ed860a74b Revision 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

Operation history (5 revisions)