Skip to main content
POST
Void 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

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"

Body

application/json

A request to create a void for a payment session. A void releases all remaining capturable funds back to the payer, including after partial refunds as long as a capturableAmount remains.

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:
externalReferenceId
string

An optional merchant-provided internal identifier for this void, from the merchant's own system—not visible to the payer.

Maximum string length: 256
Example:

"merchant-void-abc123"

customerDisplay
Operation Customer Display · object

Optional customer-facing display data for this void, shown to the payer. Falls back to the session's orderCode when referenceCode is omitted.

Example:

Response

Successfully created void.

A release of uncaptured authorized funds back to the payer. Voids release all remaining capturable funds in a single operation, including after partial refunds as long as a capturableAmount remains.

voidId
string

The unique identifier of the void.

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

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

paymentSessionId
string

The ID of the payment session this void belongs to.

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

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

status
enum<string>

The current status of the void.

Available options:
pending,
succeeded,
failed
Example:

"pending"

amount
string

A decimal representation of the voided amount, denominated in the session's asset.

Example:

"1.00"

error
object

An error that occurred during a payment operation.

Example:
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:
externalReferenceId
string

A merchant-provided internal identifier for this void, from the merchant's own system—not visible to the payer. Present only when supplied on the create void request.

Maximum string length: 256
Example:

"merchant-void-abc123"

customerDisplay
Operation Customer Display · object

Customer-facing display data for this void, shown to the payer. Present when supplied on the create void request or when the session's orderCode fallback applies; otherwise omitted.

Example:
onchainTransactions
object[]

The onchain transactions associated with this void.

Example:
createdAt
string<date-time>

The UTC ISO 8601 timestamp at which the void was created.

Example:

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

updatedAt
string<date-time>

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

Example:

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