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",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"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",
"businessDisplayName": "Acme Corporation",
"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>"
}
],
"x402_url": "https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402"
},
"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": "invalid_request",
"errorMessage": "Invalid request.",
"correlationId": "41deb8d59a9dc9a7-IAD"
}{
"errorType": "invalid_request",
"errorMessage": "request body exceeds the maximum allowed size of 262144 bytes"
}{
"errorType": "rate_limit_exceeded",
"errorMessage": "Rate limit exceeded."
}{
"errorType": "internal_server_error",
"errorMessage": "An internal server error occurred. Please try again later."
}{
"errorType": "invalid_request",
"errorMessage": "Invalid request.",
"correlationId": "41deb8d59a9dc9a7-IAD"
}Refund Checkout
Initiates a refund for a completed checkout. Only COMPLETED or PARTIALLY_REFUNDED checkouts can be refunded.
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",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"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",
"businessDisplayName": "Acme Corporation",
"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>"
}
],
"x402_url": "https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402"
},
"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": "invalid_request",
"errorMessage": "Invalid request.",
"correlationId": "41deb8d59a9dc9a7-IAD"
}{
"errorType": "invalid_request",
"errorMessage": "request body exceeds the maximum allowed size of 262144 bytes"
}{
"errorType": "rate_limit_exceeded",
"errorMessage": "Rate limit exceeded."
}{
"errorType": "internal_server_error",
"errorMessage": "An internal server error occurred. Please try again later."
}{
"errorType": "invalid_request",
"errorMessage": "Invalid request.",
"correlationId": "41deb8d59a9dc9a7-IAD"
}Authorizations
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
Path Parameters
The checkout identifier. Accepts either the id (24-char ObjectID hex) or the uuid (RFC 4122 UUID v4) returned in checkout responses.
^([0-9a-f]{24}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$Body
Refund amount. Must be at least 0.01 USDC after currency conversion and not exceed the remaining refundable amount. Partial refunds to Solana payers must be at least 0.50 USDC after conversion. A full-remainder refund is exempt only when the converted USDC amount exactly matches the current refundable balance. This API supports at most two decimal places. A remaining balance with nonzero sub-cent digits cannot use the full-remainder exemption through this API.
^\d+(\.\d{1,2})?$"25.00"
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.
"USDC"
Optional reason for the refund.
500"Customer requested refund"
Was this page helpful?