How-to: Refund a stablecoin payin

Use the Managed Payments API to return funds from a settled stablecoin payin to the original sender or another recipient address. For context on how payins are received, see Receive stablecoin payins.

Crypto refunds are irreversible. Circle does not default to a return mode. Always confirm with your customer which wallet and exchange they want funds returned to. Many exchanges send from omnibus wallets shared across users. Refunding to the original sender address can route funds to an omnibus wallet, making the refund difficult to attribute and potentially resulting in lost customer funds.

Prerequisites

Before you begin, ensure that you’ve:

Enabled Managed Payments with your Circle legal entity.
Received a completed crypto payment with status: "paid" and noted the payment intent ID.
Created an API key with Managed Payments access from the CPN Console.
(Circle Singapore Mode 2 only) Obtained the Address Book entitlement from Circle and noted the paymentId of the original payment from paymentIds[] on the intent.

Steps

The refund flow differs by Circle entity. Circle LLC (US) merchants refund to a raw blockchain address. Circle Singapore (CIRCLE_SG) merchants must refund through a registered address book entry or back to the original sender—raw addresses are not permitted. Select the tab for the Circle entity that books your payins.

Circle LLC (US)
Circle Singapore (CIRCLE_SG)

Initiate the refund

Send a POST request to /v1/paymentIntents/{paymentIntentId}/refund. Set destination.address to the recipient’s blockchain address and destination.chain to the correct network.

curl -X POST 'https://api-sandbox.circle.com/v1/paymentIntents/{paymentIntentId}/refund' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "destination": {
      "address": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799",
      "chain": "ETH"
    },
    "amount": {
      "currency": "USD"
    },
    "toAmount": {
      "amount": "5.00",
      "currency": "USD"
    }
  }'

A successful response returns a Refund object with status: "pending":

{
  "data": {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "paymentIntentId": "c3d4e5f6-7890-4ab2-cdef-3456789012cd",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "status": "pending"
  }
}

Circle settles the refund onchain and updates the status to paid when complete. For the full lifecycle, see Stablecoin payin states.

Circle Singapore (CIRCLE_SG) merchants must issue Travel Rule-compliant refunds. Raw onchain addresses are not permitted. Every refund request requires a paymentId from paymentIds[] on the intent. Circle uses it to carry forward Travel Rule data from the original payment. Two modes are available: return to the original sender, or refund to a new address book entry.

Mode 1: Return to the original sender

No address book entry is needed.

Initiate the refund

Send a POST request to /v1/paymentIntents/{paymentIntentId}/refund. Set destination.useOriginalSender to true and include the paymentId of the original payment.

curl -X POST 'https://api-sandbox.circle.com/v1/paymentIntents/{paymentIntentId}/refund' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "destination": {
      "useOriginalSender": true
    },
    "amount": {
      "currency": "USD"
    },
    "toAmount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "paymentId": "2e7b6557-1967-4348-ad81-daf3cee4c175"
  }'

A successful response returns a Refund object with status: "pending":

{
  "data": {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "paymentIntentId": "c3d4e5f6-7890-4ab2-cdef-3456789012cd",
    "paymentId": "2e7b6557-1967-4348-ad81-daf3cee4c175",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "status": "pending"
  }
}

Circle settles the refund onchain and updates the status to paid when complete. For the full lifecycle, see Stablecoin payin states.

Mode 2: Return to a different address

This mode sends the refund to a new recipient. It reuses the PII from the original payment. Register the recipient address in the address book first, using the original paymentId to link the PII. The recipient’s Virtual Asset Service Provider (VASP) must match the sender’s VASP. Verify this before you register the address.

Step 1. Register the refund address

Send a POST request to /v1/payments/refundAddresses. Set paymentId to link the PII from the original payment to this new address.

curl -X POST 'https://api-sandbox.circle.com/v1/payments/refundAddresses' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotencyKey": "bfcd6dc1-05a1-420a-a68f-8f9bf47a9394",
    "chain": "ETH",
    "address": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799",
    "metadata": {
      "nickname": "Refund Address 1"
    },
    "ownership": {
      "custody": {
        "type": "hosted",
        "vaspId": "581b9b20-28e1-464d-a257-e408733d0857"
      },
      "type": "third_party"
    },
    "paymentId": "2e7b6557-1967-4348-ad81-daf3cee4c175"
  }'

The response returns an entry with a generated id (the addressBookId) and status: "pending".

{
  "data": {
    "id": "7418ddb1-1bbf-5506-88f9-209a25c63b8b",
    "status": "pending",
    "chain": "ETH",
    "address": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799"
  }
}

In sandbox, use paymentId: "c0000000-0000-0000-0000-000000000000" to trigger instant address approval.

Step 2. Poll until the address is active

Send a GET /v1/addressBook/recipients/{id} request and poll until status returns "active".

curl -X GET 'https://api-sandbox.circle.com/v1/addressBook/recipients/{id}' \
  --header 'Authorization: Bearer $API_KEY'

When the address is approved, the response returns status: "active":

{
  "data": {
    "id": "7418ddb1-1bbf-5506-88f9-209a25c63b8b",
    "status": "active",
    "chain": "ETH",
    "address": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799"
  }
}

Step 3. Initiate the refund

Send a POST request to /v1/paymentIntents/{paymentIntentId}/refund. Set destination.addressBookId to the id from Step 1 and include the same paymentId.

curl -X POST 'https://api-sandbox.circle.com/v1/paymentIntents/{paymentIntentId}/refund' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotencyKey": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "destination": {
      "addressBookId": "7418ddb1-1bbf-5506-88f9-209a25c63b8b"
    },
    "amount": {
      "currency": "USD"
    },
    "toAmount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "paymentId": "2e7b6557-1967-4348-ad81-daf3cee4c175"
  }'

A successful response returns a Refund object with status: "pending":

{
  "data": {
    "id": "b2c3d4e5-6789-01ab-cdef-2345678901bc",
    "paymentIntentId": "c3d4e5f6-7890-4ab2-cdef-3456789012cd",
    "paymentId": "2e7b6557-1967-4348-ad81-daf3cee4c175",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "status": "pending"
  }
}

Circle settles the refund onchain and updates the status to paid when complete. For the full lifecycle, see Stablecoin payin states.

Error handling

If the request fails, the response contains a numeric error code and message. Common failures include an invalid paymentId, an inactive address book entry, or a VASP mismatch between the sender and recipient. For the full list of codes and remediation steps, see Error codes.

Fiat payouts

Managed Payments

Stablecoin payments

How-to: Refund a stablecoin payin

Prerequisites

Steps

Initiate the refund

Mode 1: Return to the original sender

Initiate the refund

Mode 2: Return to a different address

Step 1. Register the refund address

Step 2. Poll until the address is active

Step 3. Initiate the refund

Error handling

​Prerequisites

​Steps

​Initiate the refund

​Mode 1: Return to the original sender

​Initiate the refund

​Mode 2: Return to a different address

​Step 1. Register the refund address

​Step 2. Poll until the address is active

​Step 3. Initiate the refund

​Error handling

Prerequisites

Steps

Initiate the refund

Mode 1: Return to the original sender

Initiate the refund

Mode 2: Return to a different address

Step 1. Register the refund address

Step 2. Poll until the address is active

Step 3. Initiate the refund

Error handling