Skip to main content
POST
/
v2
/
payment-sessions
/
{paymentSessionId}
/
refunds
Refund a payment session
curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "amount": "0.50",
  "reason": "Customer returned the item.",
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  }
}
'
{
  "refundId": "refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "status": "pending",
  "amount": "0.50",
  "reason": "Customer returned the item.",
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  },
  "createdAt": "2025-06-15T12:40:00.000Z",
  "updatedAt": "2025-06-15T12:40: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.

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 refund for a payment session.

​
source
Account · object
required

The source from which to fund the refund. Can be a CDP account or an onchain address.

Example:
{
  "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "asset": "usdc"
}
​
amount
string

A decimal representation of the amount to refund, denominated in the session's asset. If omitted, the full remaining refundable amount is refunded.

Example:

"0.50"

​
reason
string

The reason for the refund.

Example:

"Customer returned the item."

​
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"
}

Response

Successfully created refund.

A return of previously captured funds to the payer. Multiple partial refunds are allowed up to the total captured amount.

​
refundId
string

The unique identifier of the refund.

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

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

​
paymentSessionId
string

The ID of the payment session this refund belongs to.

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

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

​
source
Account · object

The source from which the refund is funded. Can be a CDP account or an onchain address.

Example:
{
  "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "asset": "usdc"
}
​
status
enum<string>

The current status of the refund.

Available options:
pending,
succeeded,
failed
Example:

"pending"

​
amount
string

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

Example:

"0.50"

​
reason
string

The reason for the refund.

Example:

"Customer returned the item."

​
error
object

An error that occurred during a payment operation.

Example:
{
  "code": "insufficient_funds",
  "message": "The payer does not have sufficient funds.",
  "occurredAt": "2025-06-15T12:00:00.000Z"
}
​
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"
}
​
onchainTransactions
object[]

The onchain transactions associated with this refund.

Example:
[
  {
    "transactionHash": "0x012345678901234567890abcdef1234567890abcdef1234567890abcdef1234",
    "network": "base"
  }
]
​
createdAt
string<date-time>

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

Example:

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

​
updatedAt
string<date-time>

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

Example:

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