We refreshed our doc site!
Bookmarked links may have changed
Read release notesCircle’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.
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.
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
{
"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"
}
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"
}
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”
}
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.
Note: Once the refund details have been confirmed and submitted, the refund cannot be canceled.