Payment Sessions

Cancel a payment session

Changed on Oct 6, 2026

Cancels a payment session before any funds have been authorized or captured. The session must be in created status. Cancel is blocked while any authorization action is pending.

Once canceled, no further actions can be performed on the session. This is the only way to terminate a pre-authorization session — expiry deadlines block actions but do not automatically transition the session to a terminal state.

post/v2/payment-sessions/{paymentSessionId}/cancel

Request

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

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

cancellationReasonstring

The reason for cancelling the payment session.

Example request

{
  "cancellationReason": "Customer requested cancellation."
}

Response

Successfully canceled 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

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

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 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_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 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_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_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_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_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_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 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
- 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 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
- warning
  added the new operation_in_progress enum value to the response property for the response status

Operation history (5 revisions)