Create a crypto payment refund address

curl --request POST \
  --url https://api-sandbox.circle.com/v1/payments/refundAddresses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "paymentId": "74fe686b-9142-43ab-9ba9-2e0c9b366d70",
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "metadata": {
    "nickname": "Refund recipient",
    "email": "satoshi@example.com",
    "bns": "sample.circle",
    "lei": "529900T8BM49AURSDO55"
  },
  "ownership": {
    "custody": {
      "type": "hosted",
      "vaspId": "581b9b20-28e1-464d-a257-e408733d0857"
    },
    "type": "third_party"
  },
  "clientEntityId": "7c1fb25a-f814-4c57-b06f-d5a25bfbf935",
  "addressTag": "123456789"
}
'

import requests

url = "https://api-sandbox.circle.com/v1/payments/refundAddresses"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "paymentId": "74fe686b-9142-43ab-9ba9-2e0c9b366d70",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
    "metadata": {
        "nickname": "Refund recipient",
        "email": "satoshi@example.com",
        "bns": "sample.circle",
        "lei": "529900T8BM49AURSDO55"
    },
    "ownership": {
        "custody": {
            "type": "hosted",
            "vaspId": "581b9b20-28e1-464d-a257-e408733d0857"
        },
        "type": "third_party"
    },
    "clientEntityId": "7c1fb25a-f814-4c57-b06f-d5a25bfbf935",
    "addressTag": "123456789"
}
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({
    idempotencyKey: 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    paymentId: '74fe686b-9142-43ab-9ba9-2e0c9b366d70',
    address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F',
    metadata: {
      nickname: 'Refund recipient',
      email: 'satoshi@example.com',
      bns: 'sample.circle',
      lei: '529900T8BM49AURSDO55'
    },
    ownership: {
      custody: {type: 'hosted', vaspId: '581b9b20-28e1-464d-a257-e408733d0857'},
      type: 'third_party'
    },
    clientEntityId: '7c1fb25a-f814-4c57-b06f-d5a25bfbf935',
    addressTag: '123456789'
  })
};

fetch('https://api-sandbox.circle.com/v1/payments/refundAddresses', 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-sandbox.circle.com/v1/payments/refundAddresses",
  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([
    'idempotencyKey' => 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    'paymentId' => '74fe686b-9142-43ab-9ba9-2e0c9b366d70',
    'address' => '0x8381470ED67C3802402dbbFa0058E8871F017A6F',
    'metadata' => [
        'nickname' => 'Refund recipient',
        'email' => 'satoshi@example.com',
        'bns' => 'sample.circle',
        'lei' => '529900T8BM49AURSDO55'
    ],
    'ownership' => [
        'custody' => [
                'type' => 'hosted',
                'vaspId' => '581b9b20-28e1-464d-a257-e408733d0857'
        ],
        'type' => 'third_party'
    ],
    'clientEntityId' => '7c1fb25a-f814-4c57-b06f-d5a25bfbf935',
    'addressTag' => '123456789'
  ]),
  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-sandbox.circle.com/v1/payments/refundAddresses"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentId\": \"74fe686b-9142-43ab-9ba9-2e0c9b366d70\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"metadata\": {\n    \"nickname\": \"Refund recipient\",\n    \"email\": \"satoshi@example.com\",\n    \"bns\": \"sample.circle\",\n    \"lei\": \"529900T8BM49AURSDO55\"\n  },\n  \"ownership\": {\n    \"custody\": {\n      \"type\": \"hosted\",\n      \"vaspId\": \"581b9b20-28e1-464d-a257-e408733d0857\"\n    },\n    \"type\": \"third_party\"\n  },\n  \"clientEntityId\": \"7c1fb25a-f814-4c57-b06f-d5a25bfbf935\",\n  \"addressTag\": \"123456789\"\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-sandbox.circle.com/v1/payments/refundAddresses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentId\": \"74fe686b-9142-43ab-9ba9-2e0c9b366d70\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"metadata\": {\n    \"nickname\": \"Refund recipient\",\n    \"email\": \"satoshi@example.com\",\n    \"bns\": \"sample.circle\",\n    \"lei\": \"529900T8BM49AURSDO55\"\n  },\n  \"ownership\": {\n    \"custody\": {\n      \"type\": \"hosted\",\n      \"vaspId\": \"581b9b20-28e1-464d-a257-e408733d0857\"\n    },\n    \"type\": \"third_party\"\n  },\n  \"clientEntityId\": \"7c1fb25a-f814-4c57-b06f-d5a25bfbf935\",\n  \"addressTag\": \"123456789\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/payments/refundAddresses")

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  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentId\": \"74fe686b-9142-43ab-9ba9-2e0c9b366d70\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"metadata\": {\n    \"nickname\": \"Refund recipient\",\n    \"email\": \"satoshi@example.com\",\n    \"bns\": \"sample.circle\",\n    \"lei\": \"529900T8BM49AURSDO55\"\n  },\n  \"ownership\": {\n    \"custody\": {\n      \"type\": \"hosted\",\n      \"vaspId\": \"581b9b20-28e1-464d-a257-e408733d0857\"\n    },\n    \"type\": \"third_party\"\n  },\n  \"clientEntityId\": \"7c1fb25a-f814-4c57-b06f-d5a25bfbf935\",\n  \"addressTag\": \"123456789\"\n}"

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

{
  "data": {
    "id": "7418ddb1-1bbf-5506-88f9-209a25c63b8b",
    "chain": "ETH",
    "address": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799",
    "metadata": {
      "nickname": "Refund recipient"
    },
    "identity": {
      "type": "individual",
      "firstName": "John",
      "lastName": "Doe"
    },
    "ownership": {
      "type": "third_party",
      "custody": {
        "type": "hosted",
        "vaspId": "581b9b20-28e1-464d-a257-e408733d0857"
      }
    },
    "status": "pending",
    "createDate": "2026-06-30T12:00:00Z",
    "updateDate": "2026-06-30T12:00:00Z"
  }
}

{
  "code": 400,
  "message": "Bad request."
}

{
  "code": 401,
  "message": "Malformed authorization."
}

{
  "code": 3,
  "message": "Forbidden"
}

{
  "code": 500,
  "message": "Internal server error."
}

Create a crypto payment refund address

Creates a refund address-book entry that can be used as destination.addressBookId when refunding a crypto payment intent.

This endpoint is used for Circle Singapore (CIRCLE_SG) refund flow 2, where the refund goes to a different address while reusing the original payment’s Travel Rule originator PII. Provide the original paymentId and a hosted VASP in ownership.custody.vaspId; the supplied VASP ID must match the VASP associated with the original payment sender.

Do not provide recipient identity in the request. Identity is derived from the original payment’s Travel Rule originator PII.

POST

payments

refundAddresses

Create a crypto payment refund address

curl --request POST \
  --url https://api-sandbox.circle.com/v1/payments/refundAddresses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "paymentId": "74fe686b-9142-43ab-9ba9-2e0c9b366d70",
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "metadata": {
    "nickname": "Refund recipient",
    "email": "satoshi@example.com",
    "bns": "sample.circle",
    "lei": "529900T8BM49AURSDO55"
  },
  "ownership": {
    "custody": {
      "type": "hosted",
      "vaspId": "581b9b20-28e1-464d-a257-e408733d0857"
    },
    "type": "third_party"
  },
  "clientEntityId": "7c1fb25a-f814-4c57-b06f-d5a25bfbf935",
  "addressTag": "123456789"
}
'

import requests

url = "https://api-sandbox.circle.com/v1/payments/refundAddresses"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "paymentId": "74fe686b-9142-43ab-9ba9-2e0c9b366d70",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
    "metadata": {
        "nickname": "Refund recipient",
        "email": "satoshi@example.com",
        "bns": "sample.circle",
        "lei": "529900T8BM49AURSDO55"
    },
    "ownership": {
        "custody": {
            "type": "hosted",
            "vaspId": "581b9b20-28e1-464d-a257-e408733d0857"
        },
        "type": "third_party"
    },
    "clientEntityId": "7c1fb25a-f814-4c57-b06f-d5a25bfbf935",
    "addressTag": "123456789"
}
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({
    idempotencyKey: 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    paymentId: '74fe686b-9142-43ab-9ba9-2e0c9b366d70',
    address: '0x8381470ED67C3802402dbbFa0058E8871F017A6F',
    metadata: {
      nickname: 'Refund recipient',
      email: 'satoshi@example.com',
      bns: 'sample.circle',
      lei: '529900T8BM49AURSDO55'
    },
    ownership: {
      custody: {type: 'hosted', vaspId: '581b9b20-28e1-464d-a257-e408733d0857'},
      type: 'third_party'
    },
    clientEntityId: '7c1fb25a-f814-4c57-b06f-d5a25bfbf935',
    addressTag: '123456789'
  })
};

fetch('https://api-sandbox.circle.com/v1/payments/refundAddresses', 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-sandbox.circle.com/v1/payments/refundAddresses",
  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([
    'idempotencyKey' => 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    'paymentId' => '74fe686b-9142-43ab-9ba9-2e0c9b366d70',
    'address' => '0x8381470ED67C3802402dbbFa0058E8871F017A6F',
    'metadata' => [
        'nickname' => 'Refund recipient',
        'email' => 'satoshi@example.com',
        'bns' => 'sample.circle',
        'lei' => '529900T8BM49AURSDO55'
    ],
    'ownership' => [
        'custody' => [
                'type' => 'hosted',
                'vaspId' => '581b9b20-28e1-464d-a257-e408733d0857'
        ],
        'type' => 'third_party'
    ],
    'clientEntityId' => '7c1fb25a-f814-4c57-b06f-d5a25bfbf935',
    'addressTag' => '123456789'
  ]),
  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-sandbox.circle.com/v1/payments/refundAddresses"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentId\": \"74fe686b-9142-43ab-9ba9-2e0c9b366d70\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"metadata\": {\n    \"nickname\": \"Refund recipient\",\n    \"email\": \"satoshi@example.com\",\n    \"bns\": \"sample.circle\",\n    \"lei\": \"529900T8BM49AURSDO55\"\n  },\n  \"ownership\": {\n    \"custody\": {\n      \"type\": \"hosted\",\n      \"vaspId\": \"581b9b20-28e1-464d-a257-e408733d0857\"\n    },\n    \"type\": \"third_party\"\n  },\n  \"clientEntityId\": \"7c1fb25a-f814-4c57-b06f-d5a25bfbf935\",\n  \"addressTag\": \"123456789\"\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-sandbox.circle.com/v1/payments/refundAddresses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentId\": \"74fe686b-9142-43ab-9ba9-2e0c9b366d70\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"metadata\": {\n    \"nickname\": \"Refund recipient\",\n    \"email\": \"satoshi@example.com\",\n    \"bns\": \"sample.circle\",\n    \"lei\": \"529900T8BM49AURSDO55\"\n  },\n  \"ownership\": {\n    \"custody\": {\n      \"type\": \"hosted\",\n      \"vaspId\": \"581b9b20-28e1-464d-a257-e408733d0857\"\n    },\n    \"type\": \"third_party\"\n  },\n  \"clientEntityId\": \"7c1fb25a-f814-4c57-b06f-d5a25bfbf935\",\n  \"addressTag\": \"123456789\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/payments/refundAddresses")

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  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentId\": \"74fe686b-9142-43ab-9ba9-2e0c9b366d70\",\n  \"address\": \"0x8381470ED67C3802402dbbFa0058E8871F017A6F\",\n  \"metadata\": {\n    \"nickname\": \"Refund recipient\",\n    \"email\": \"satoshi@example.com\",\n    \"bns\": \"sample.circle\",\n    \"lei\": \"529900T8BM49AURSDO55\"\n  },\n  \"ownership\": {\n    \"custody\": {\n      \"type\": \"hosted\",\n      \"vaspId\": \"581b9b20-28e1-464d-a257-e408733d0857\"\n    },\n    \"type\": \"third_party\"\n  },\n  \"clientEntityId\": \"7c1fb25a-f814-4c57-b06f-d5a25bfbf935\",\n  \"addressTag\": \"123456789\"\n}"

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

{
  "data": {
    "id": "7418ddb1-1bbf-5506-88f9-209a25c63b8b",
    "chain": "ETH",
    "address": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799",
    "metadata": {
      "nickname": "Refund recipient"
    },
    "identity": {
      "type": "individual",
      "firstName": "John",
      "lastName": "Doe"
    },
    "ownership": {
      "type": "third_party",
      "custody": {
        "type": "hosted",
        "vaspId": "581b9b20-28e1-464d-a257-e408733d0857"
      }
    },
    "status": "pending",
    "createDate": "2026-06-30T12:00:00Z",
    "updateDate": "2026-06-30T12:00:00Z"
  }
}

{
  "code": 400,
  "message": "Bad request."
}

{
  "code": 401,
  "message": "Malformed authorization."
}

{
  "code": 3,
  "message": "Forbidden"
}

{
  "code": 500,
  "message": "Internal server error."
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

idempotencyKey

string<uuid>

required

Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests.

Example:

"ba943ff1-ca16-49b2-ba55-1057e70ca5c7"

paymentId

string<uuid>

required

Original payment identifier. Recipient identity is derived from this payment's Travel Rule originator PII.

Example:

"74fe686b-9142-43ab-9ba9-2e0c9b366d70"

chain

enum<string>

required

A blockchain that a given currency is available on.

Note: Arc (ARC) is only available in the sandbox environment (api-sandbox.circle.com).

Available options:

ALGO,

APTOS,

ARB,

ARC,

AVAX,

BASE,

BTC,

CELO,

CODEX,

ETH,

HBAR,

HYPEREVM,

INK,

LINEA,

NEAR,

NOBLE,

OP,

PLUME,

PAH,

POLY,

SEI,

SOL,

SONIC,

SUI,

UNI,

WORLDCHAIN,

XLAYER,

XDC,

XLM,

XRP,

ZKS,

ZKSYNC

address

string

required

An alphanumeric string representing a blockchain address. Formatting varies by blockchain. Be sure to preserve the exact formatting and capitalization of the address.
Important: For Ripple (XRP) addresses, only the classic address format is supported (for example, rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY).
The x-address format is NOT supported currently (for example, XV5sbjUmgPpvXv4ixFWZ5ptAYZ6PD2q1qM6owqNbug8W6KV).

Example:

"0x8381470ED67C3802402dbbFa0058E8871F017A6F"

metadata

object

required

Metadata for a refund address.

Show child attributes

ownership

object

required

Refund address ownership. ownership.custody.vaspId is required and must match the VASP recorded on the original payment.

Show child attributes

clientEntityId

string<uuid>

Optional child entity that should own the refund address. When omitted, the address is PSP-owned/shared.

Example:

"7c1fb25a-f814-4c57-b06f-d5a25bfbf935"

addressTag

string | null

The secondary identifier for a blockchain address. An example of this is the memo field on the Stellar network, which can be text, id, or hash format.

Example:

"123456789"

Response

Refund address successfully created, or original address replayed for a reused idempotency key.

data

object

Refund address-book entry used as a crypto refund destination.

Show child attributes

⌘I

API overview

Fiat payouts

Managed Payments

Stablecoin payments

Create a crypto payment refund address

Authorizations

Body

Response