Skip to main content
The Crypto Deposits API allows you to take payments from your customers onchain and receive settlement in USDC and EURC. Sometimes, customers may need to refund or reverse the payment back to the sender/buyer after the payment was made. Crypto refunds enables this refund use case. Some key points to note about the feature:
  • Allows for a full or partial refund within 30 days of the creation of payment intent.
  • Refunds are linked to the original intent.
  • Payment intent information and reporting include refund information.

​
How Crypto Refunds Work

After successfully processing a crypto payment (Please follow the Crypto Refunds quickstart if you haven’t done so yet) and receiving the settlement in your Circle account, you will have the option to initiate a refund/reversal if so needed for the payment intent. These refunds can be initiated using either the refund APIs or the Circle Account UI. Refunds can be initiated up to 30 days after the payment intent creation for intents that have had a successful payment associated with it. These can be partial or for the full amount and supports multiple refunds within this time period. After the refund has been initiated, the payment intent status will be moved to refunded, and the payment intent will no longer accept any new incoming crypto payments.

​
Crypto Refund API

Make sure you have a successful crypto payment for the given payment intent.

​
Refund Crypto

You will be able to refund crypto payments at the payment intent level by making the following request: Request POST /v1/paymentIntents/{id}/refund
JSON
{
  "idempotencyKey": "9aed1aab-292a-427f-aae1-e0e358fef1c9",
  "destination": {
    "chain": "ETH",
    "address": "0xcd7475eaed9ee9678cf219cec748e25aba068a69"
  },
  "amount": {
    "currency": "ETH"
  },
  "toAmount": {
    "amount": "0.000001",
    "currency": "ETH"
  }
}
Response
JSON
{
  "id": "d445342e-11c5-3060-9e91-0a93d658c075",
  "type": "refund",
  "status": "pending",
  "amount": {
    "amount": "0.000000001000000000",
    "currency": "ETH"
  },
  "createDate": "2022-12-06T14:55:01.013267Z",
  "updateDate": "2022-12-06T14:55:01.013267Z",
  "merchantId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
  "merchantWalletId": "1000563095",
  "paymentIntentId": "5a925c4e-959e-4b75-9558-6f9af3ca52af",
  "settlementAmount": {
    "amount": "0.000000001000000000",
    "currency": "ETH"
  },
  "depositAddress": {
    "chain": "ETH",
    "address": "0xcd7475eaed9ee9678cf219cec748e25aba068a69"
  }
}

​
List Payment Intents

Returns both crypto payments and crypto refunds associated with the payment intent. Request GET v1/paymentIntents/{id} Response
JSON
{
  "id":"5a925c4e-959e-4b75-9558-6f9af3ca52af",
  "amount":{
    "amount":"0.100000000000000000",
    "currency":"ETH"
  }
  "amountPaid":{
    "amount":"0.100000000000000000",
    "currency":"ETH"
  }
  "amountRefunded":{
    "amount":"0.091011010050000000",
    "currency":"ETH"
  }
  "settlementCurrency":"USD",
  "paymentMethods":[
    {
      "type":"blockchain",
      "chain":"ETH",
      "address":"0x6b20d7236bab7b62423e3fcd8530611be1cdea19"
    }
  ]
  "fees":[
    {
      "type":"blockchainLeaseFee",
      "amount":"0.000000000000000000",
      "currency":"ETH"
    }
    {
      "type":"totalPaymentFees",
      "amount":"3.34",
      "currency":"USD"
    }
  ]
  "paymentIds":[
    "ba8502e3-515f-3c3a-a409-8ab99a2e72c7"
  ]
  "refundIds":[
    "a23800d8-369b-3f1a-9ec0-d73f6d439aea",
  ]
  "timeline":[
    {
      "status":"refunded",
      "time":"2022-11-23T17:36:26.781268Z"
    }
    {
      "status":"complete",
      "context":"paid",
      "time":"2022-11-23T13:00:17.980355Z"
    }
    {
      "status":"pending",
      "time":"2022-11-23T12:57:15.726331Z"
    }
    {
      "status":"created",
      "time":"2022-11-23T12:57:12.175413Z"
    }
  ]
  "createDate":"2022-11-23T12:57:12.173979Z",
  "updateDate":"2022-12-06T14:57:18.039362Z",
  "expiresOn":"2022-11-23T13:57:15.557966Z"
}

​
Get payment information

Returns payment information based on a Payment ID. Request GET v1/payments/{id} Response
JSON
{
  "id": "ba8502e3-515f-3c3a-a409-8ab99a2e72c7",
  "type": "refund",
  "status": "paid",
  "amount": {
    "amount": "0.100000000000000000",
    "currency": "ETH"
  },
  "fees": {
    "amount": "3.34",
    "currency": "USD"
  },
  "createDate": "2022-11-23T12:58:44.543392Z",
  "updateDate": "2022-11-23T13:00:17.772601Z",
  "merchantId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
  "merchantWalletId": "1000563095",
  "paymentIntentId": "5a925c4e-959e-4b75-9558-6f9af3ca52af",
  "settlementAmount": {
    "amount": "371.02",
    "currency": "USD"
  },
  "depositAddress": {
    "chain": "ETH",
    "address": "0x6b20d7236bab7b62423e3fcd8530611be1cdea19"
  },
  "transactionHash": "0x830050e5afbcc85e4f3"
}
The get payment endpoint returns all crypto payments and crypto refunds when passing in payment intent id in the query parameter. Request GET v1/payments?paymentIntentId={paymentIntentId} Response
JSON
{
  "id": "ba8502e3-515f-3c3a-a409-8ab99a2e72c7",
  "type": "refund",
  "status": "paid",
  "amount": {
    "amount": "0.100000000000000000",
    "currency": "ETH"
  },
  "fees": {
    "amount": "3.34",
    "currency": "USD"
  },
  "createDate": "2022-11-23T12:58:44.543392Z",
  "updateDate": "2022-11-23T13:00:17.772601Z",
  "merchantId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
  "merchantWalletId": "1000563095",
  "paymentIntentId": "5a925c4e-959e-4b75-9558-6f9af3ca52af",
  "settlementAmount": {
    "amount": "371.02",
    "currency": "USD"
  },
  "depositAddress": {
    "chain": "ETH",
    "address": "0x6b20d7236bab7b62423e3fcd8530611be1cdea19"
  },
  "transactionHash": "0x830050e5afbcc85e4f3"
}
JSON
{
  "id": "d445342e-11c5-3060-9e91-0a93d658c075",
  "type": "payment",
  "status": "paid",
  "amount": {
    "amount": "0.100000000000000000",
    "currency": "ETH"
  },
  "fees": {
    "amount": "3.34",
    "currency": "USD"
  },
  "createDate": "2022-11-23T12:58:44.543392Z",
  "updateDate": "2022-11-23T13:00:17.772601Z",
  "merchantId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
  "merchantWalletId": "1000563095",
  "paymentIntentId": "5a925c4e-959e-4b75-9558-6f9af3ca52af",
  "settlementAmount": {
    "amount": "371.02",
    "currency": "USD"
  },
  "depositAddress": {
    "chain": "ETH",
    "address": "0x6b20d7236bab7b62423e3fcd8530611be1cdea19"
  },
  "transactionHash": "0x76e3a2638e413a718673b695ce4cf5bbe"
}

​
Notes about Refund Limitations

  • Refunds can’t be initiated if there is a pending crypto payment.
  • Refunds can only be initiated after a complete crypto payment and within 30 days of the payment intent expiry.
  • Once a refund is initiated, the payment intent state changes to “refunded”, and no further payments will be accepted on this payment intent. It is important to ensure that a refunded intent is not used for payments. In case any crypto payments are sent to a refunded intent, these will not get associated with the intent and will need to be investigated and resolved manually through the customer care team. Not be associated with the payment go to unsupported funds.

​
Initiate Refund from Circle Account

In addition to the APIs, Circle provides merchants with the ability to refund a crypto payment intent using the Circle Account interface.

​
Step 1: Navigate to the Payment Intent Page

Refunds can be initiated from the Payment intent detail page. Click the icon on the top right of the page (three dots) to start the Crypto refund.

​
Step 2: Initiating the Refund

On the subsequent page, enter the recipient details, amount, and balance and currency to fund the refund.

​
Step 3: Confirm the Refund

After you have successfully entered the information review and confirm the details to initiate the refund Note: Once the refund details have been confirmed and submitted, the refund cannot be canceled.
⌘I