Skip to main content
POST
/
api
/
v1
/
checkouts
/
{id}
/
refund
Refund Checkout
curl --request POST \
  --url https://business.coinbase.com/api/v1/checkouts/{id}/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "25.00",
  "currency": "USDC",
  "reason": "Customer requested refund"
}
'
{
  "checkout": {
    "id": "68f7a946db0529ea9b6d3a12",
    "url": "https://payments.coinbase.com/payment-links/pl_01h8441j23abcd1234567890ef",
    "amount": "100.50",
    "currency": "USDC",
    "network": "base",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "createdAt": "2024-03-20T10:30:00Z",
    "updatedAt": "2024-03-20T10:30:00Z",
    "status": "ACTIVE",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "description": "Payment for order #12345",
    "expiresAt": "2024-03-20T10:30:00Z",
    "metadata": {
      "invoiceId": "12345",
      "reference": "Payment for invoice #12345",
      "customerId": "cust_abc123"
    },
    "successRedirectUrl": "https://example.com/success",
    "failRedirectUrl": "https://example.com/failed",
    "settlement": {
      "totalAmount": "100.00",
      "feeAmount": "1.25",
      "netAmount": "98.75",
      "currency": "USDC"
    },
    "fiatAmount": "100.00",
    "fiatCurrency": "USD",
    "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "refundedAmount": "25.00",
    "refunds": [
      {
        "id": "<string>",
        "checkoutId": "<string>",
        "amount": "<string>",
        "status": "PENDING",
        "createdAt": "2024-03-20T10:30:00Z",
        "currency": "USDC",
        "reason": "<string>",
        "transactionHash": "<string>",
        "completedAt": "2024-03-20T10:30:00Z",
        "fiatAmount": "<string>",
        "fiatCurrency": "<string>",
        "exchangeRate": "<string>"
      }
    ]
  },
  "refund": {
    "id": "<string>",
    "checkoutId": "<string>",
    "amount": "<string>",
    "status": "PENDING",
    "createdAt": "2024-03-20T10:30:00Z",
    "currency": "USDC",
    "reason": "<string>",
    "transactionHash": "<string>",
    "completedAt": "2024-03-20T10:30:00Z",
    "fiatAmount": "<string>",
    "fiatCurrency": "<string>",
    "exchangeRate": "<string>"
  }
}

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 UUID v4 request header for making requests safely retryable.

Required string length: 36
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Path Parameters

​
id
string
required

The checkout ID.

Pattern: ^[0-9a-f]{24}$
Example:

"68f7a946db0529ea9b6d3a12"

Body

application/json
​
amount
string
required

Refund amount. Must not exceed remaining refundable amount.

Pattern: ^\d+(\.\d{1,2})?$
Example:

"25.00"

​
currency
string

Currency of the refund amount. If omitted, defaults to the checkout's original fiat currency (or USDC if the payment was in USDC). Supported currencies: any fiat currency supported by the checkout creation API.

Example:

"USDC"

​
reason
string

Optional reason for the refund.

Maximum string length: 500
Example:

"Customer requested refund"

Response

Refund initiated successfully.

​
checkout
object
required
​
refund
object
required