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.
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.
Make sure you have a successful crypto payment for the given payment intent.
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"
}
}
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"
}
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"
}
- 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.
In addition to the APIs, Circle provides merchants with the ability to refund a crypto payment intent using the Circle Account interface.
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.
On the subsequent page, enter the recipient details, amount, and balance and currency to fund 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.
Did this page help you?
© 2023-2025 Circle Technology Services, LLC. All rights reserved.
