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_reference": "order-67890"
  }
}
'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds"

payload = {
    "source": {
        "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
        "asset": "usdc"
    },
    "amount": "0.50",
    "reason": "Customer returned the item.",
    "metadata": {
        "customer_id": "cust_12345",
        "order_reference": "order-67890"
    }
}
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({
    source: {accountId: 'account_af2937b0-9846-4fe7-bfe9-ccc22d935114', asset: 'usdc'},
    amount: '0.50',
    reason: 'Customer returned the item.',
    metadata: {customer_id: 'cust_12345', order_reference: 'order-67890'}
  })
};

fetch('https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds', 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://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds",
  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([
    'source' => [
        'accountId' => 'account_af2937b0-9846-4fe7-bfe9-ccc22d935114',
        'asset' => 'usdc'
    ],
    'amount' => '0.50',
    'reason' => 'Customer returned the item.',
    'metadata' => [
        'customer_id' => 'cust_12345',
        'order_reference' => 'order-67890'
    ]
  ]),
  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://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds"

	payload := strings.NewReader("{\n  \"source\": {\n    \"accountId\": \"account_af2937b0-9846-4fe7-bfe9-ccc22d935114\",\n    \"asset\": \"usdc\"\n  },\n  \"amount\": \"0.50\",\n  \"reason\": \"Customer returned the item.\",\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\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://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source\": {\n    \"accountId\": \"account_af2937b0-9846-4fe7-bfe9-ccc22d935114\",\n    \"asset\": \"usdc\"\n  },\n  \"amount\": \"0.50\",\n  \"reason\": \"Customer returned the item.\",\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds")

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  \"source\": {\n    \"accountId\": \"account_af2937b0-9846-4fe7-bfe9-ccc22d935114\",\n    \"asset\": \"usdc\"\n  },\n  \"amount\": \"0.50\",\n  \"reason\": \"Customer returned the item.\",\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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_reference": "order-67890"
  },
  "createdAt": "2025-06-15T12:40:00.000Z",
  "updatedAt": "2025-06-15T12:40:00.000Z"
}

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid refund parameters."
}

{
  "errorType": "not_found",
  "errorMessage": "Payment session with the given ID does not exist."
}

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key."
}

{
  "errorType": "internal_server_error",
  "errorMessage": "An internal server error occurred. Please try again later."
}

{
  "errorType": "bad_gateway",
  "errorMessage": "Bad gateway. Please try again later."
}

{
  "errorType": "service_unavailable",
  "errorMessage": "Service unavailable. Please try again later."
}

POST

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_reference": "order-67890"
  }
}
'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds"

payload = {
    "source": {
        "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
        "asset": "usdc"
    },
    "amount": "0.50",
    "reason": "Customer returned the item.",
    "metadata": {
        "customer_id": "cust_12345",
        "order_reference": "order-67890"
    }
}
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({
    source: {accountId: 'account_af2937b0-9846-4fe7-bfe9-ccc22d935114', asset: 'usdc'},
    amount: '0.50',
    reason: 'Customer returned the item.',
    metadata: {customer_id: 'cust_12345', order_reference: 'order-67890'}
  })
};

fetch('https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds', 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://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds",
  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([
    'source' => [
        'accountId' => 'account_af2937b0-9846-4fe7-bfe9-ccc22d935114',
        'asset' => 'usdc'
    ],
    'amount' => '0.50',
    'reason' => 'Customer returned the item.',
    'metadata' => [
        'customer_id' => 'cust_12345',
        'order_reference' => 'order-67890'
    ]
  ]),
  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://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds"

	payload := strings.NewReader("{\n  \"source\": {\n    \"accountId\": \"account_af2937b0-9846-4fe7-bfe9-ccc22d935114\",\n    \"asset\": \"usdc\"\n  },\n  \"amount\": \"0.50\",\n  \"reason\": \"Customer returned the item.\",\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\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://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source\": {\n    \"accountId\": \"account_af2937b0-9846-4fe7-bfe9-ccc22d935114\",\n    \"asset\": \"usdc\"\n  },\n  \"amount\": \"0.50\",\n  \"reason\": \"Customer returned the item.\",\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/refunds")

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  \"source\": {\n    \"accountId\": \"account_af2937b0-9846-4fe7-bfe9-ccc22d935114\",\n    \"asset\": \"usdc\"\n  },\n  \"amount\": \"0.50\",\n  \"reason\": \"Customer returned the item.\",\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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_reference": "order-67890"
  },
  "createdAt": "2025-06-15T12:40:00.000Z",
  "updatedAt": "2025-06-15T12:40:00.000Z"
}

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid refund parameters."
}

{
  "errorType": "not_found",
  "errorMessage": "Payment session with the given ID does not exist."
}

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key."
}

{
  "errorType": "internal_server_error",
  "errorMessage": "An internal server error occurred. Please try again later."
}

{
  "errorType": "bad_gateway",
  "errorMessage": "Bad gateway. Please try again later."
}

{
  "errorType": "service_unavailable",
  "errorMessage": "Service unavailable. 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 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.

Account
Refund Wallet

Show child attributes

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.

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

externalReferenceId

string

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

Maximum string length: 256

Example:

"merchant-refund-abc123"

customerDisplay

Operation Customer Display · object

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

Show child attributes

Example:

{ "referenceCode": "REF-ABC123" }

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.

Account
Refund Wallet

Show child attributes

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.

Show child attributes

Example:

{
  "code": "insufficient_funds",
  "message": "The payer does not have sufficient funds.",
  "occurredAt": "2025-06-15T12:00:00.000Z"
}

metadata

object

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

externalReferenceId

string

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

Maximum string length: 256

Example:

"merchant-refund-abc123"

customerDisplay

Operation Customer Display · object

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

Show child attributes

Example:

{ "referenceCode": "REF-ABC123" }

onchainTransactions

object[]

The onchain transactions associated with this refund.

Show child attributes

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"