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"
}
'
import requests

url = "https://business.coinbase.com/api/v1/checkouts/{id}/refund"

payload = {
"amount": "25.00",
"currency": "USDC",
"reason": "Customer requested refund"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({amount: '25.00', currency: 'USDC', reason: 'Customer requested refund'})
};

fetch('https://business.coinbase.com/api/v1/checkouts/{id}/refund', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://business.coinbase.com/api/v1/checkouts/{id}/refund",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => '25.00',
'currency' => 'USDC',
'reason' => 'Customer requested refund'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://business.coinbase.com/api/v1/checkouts/{id}/refund"

payload := strings.NewReader("{\n \"amount\": \"25.00\",\n \"currency\": \"USDC\",\n \"reason\": \"Customer requested refund\"\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://business.coinbase.com/api/v1/checkouts/{id}/refund")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"25.00\",\n \"currency\": \"USDC\",\n \"reason\": \"Customer requested refund\"\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://business.coinbase.com/api/v1/checkouts/{id}/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": \"25.00\",\n \"currency\": \"USDC\",\n \"reason\": \"Customer requested refund\"\n}"

response = http.request(request)
puts response.read_body
{
  "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>"
  }
}
{
"errorType": "invalid_request",
"errorMessage": "Invalid request parameters."
}
{
"errorType": "unauthorized",
"errorMessage": "The request is not properly authenticated."
}
{
"errorType": "forbidden",
"errorMessage": "User forbidden from performing the action."
}
{
"errorType": "not_found",
"errorMessage": "The requested resource was not found."
}
{
"errorType": "rate_limit_exceeded",
"errorMessage": "Rate limit exceeded."
}
{
"errorType": "internal_server_error",
"errorMessage": "An internal server error occurred. Please try again later."
}

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 be > 0 and 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