Circle’s Crypto Payments API allows you to take payments from your customers on-chain and receive settlement in USDC, BTC and ETH.From time to time, customers may need to refund or reverse the payment back to the sender/buyer after the payment has been made. Crypto refunds enables this refund use case for our customers.Some key points to note about the feature:* Allows for a full or partial refund within 30 days of the creation of payment intent.

Provides flexibility to fund the refund from the Circle account using either the settlement currency or payment currency (assuming there is a balance in the Circle account).
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 Payment Quickstart guide 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

{
  "idempotencyKey": "9aed1aab-292a-427f-aae1-e0e358fef1c9",
  "destination": {
    "chain": "ETH",
    "address": "0xcd7475eaed9ee9678cf219cec748e25aba068a69"
  },
  "amount": {
    "currency": "ETH"
  },
  "toAmount": {
    "amount": "0.000001",
    "currency": "ETH"
  }
}

Response

{
  "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

{
  "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

{
  "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 will return all crypto payments and crypto refunds when passing in payment intent id in the query param.

Request GET v1/payments?paymentIntentId={paymentIntentId}

Response

{
  "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”
}
{
  "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.

Step3: 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.

The refund should be viewable under the payment intent detail page after initiated.