Skip to main content
Use the Stablecoin Payins API to return funds against a payment intent that has already received at least one settled payment. You can issue a single full refund, a single partial refund, or multiple partial refunds up to the settled total. For the mental model that underpins this procedure, see Stablecoin payins and payouts.
Refunds are subject to four hard constraints:
  • You have 30 days from the payment intent’s creation date to start a refund.
  • At least one payment on the intent must be settled. You cannot start a refund while a payment is still pending.
  • Once a refund starts, the payment intent transitions to refunded and stops accepting new payins. Treat the intent as terminal and create a new intent for any future checkout.
  • Refunds initiated from the Circle Mint console cannot be canceled after submission.
Regional availability also affects which payment intents are refundable today.
Refunds for Stablecoin Payins booked through Circle Singapore (CIRCLE_SG) are not supported. Refunds for Circle SAS (CIRCLE_FR) accounts are supported with restrictions. See Step 2 for details.

​
Prerequisites

Before you begin, ensure that you’ve:
  • Confirmed that a settled payment exists on the payment intent you want to refund. If you haven’t accepted a payin yet, see Receive a stablecoin payin.
  • Identified a refund destination address you control on the same blockchain as the original payment. The destination is merchant-supplied; Circle doesn’t automatically return funds to the source wallet. For CIRCLE_FR accounts, see Step 2 for destination requirements.
  • Obtained a Circle Mint sandbox API key. See Getting started for setup.

​
Steps

1

Inspect the intent to confirm a settled payment

Before you initiate a refund, retrieve the payment intent and confirm that at least one payment in paymentIds is settled. Send a GET request to /v1/paymentIntents/{id}.
A refund-eligible response has a populated paymentIds array and a non-zero amountPaid. The latest timeline entry shows status complete with context paid.
2

Issue the refund

Send a POST request to /v1/paymentIntents/{id}/refund. The body specifies the destination you control, the refund amount, and an idempotency key. The request uses two amount fields:
  • amount carries the source-currency basis; only currency is required, and the value is derived from toAmount.
  • toAmount carries the actual refund amount that reaches the destination and must include both amount and currency.
For memo-based blockchains, add an addressTag to the destination object.For CIRCLE_FR accounts, three requirements differ from Circle LLC behavior:
  • paymentId (required): include the ID of the settled payment from paymentIds[] on the intent. Circle uses this to associate the refund with the original payin and inherit its Travel Rule data.
  • Destination must be the original sender: set destination to { "useOriginalSender": true }. Raw address destinations are rejected with error 1166 (ADDRESS_BOOK_DESTINATION_REQUIRED).
  • Cross-VASP refunds: refunds to a wallet address at a different VASP than the original payin are not supported.
Add paymentId and the useOriginalSender destination to the request body:
For the full EEA data model, see Travel Rule compliance.
Specify an amount lower than the settled total to return a portion of the payment.
The response is a payment object with type refund and status pending. The depositAddress field shows where Circle sends the onchain transfer.
The payment intent’s timeline immediately gains a refunded entry and the intent becomes terminal. New payins sent to the original deposit address after this point may not match the intent. Circle Support may need to reconcile them.
3

Track refund completion

Refunds settle asynchronously after the onchain transfer confirms. Use webhooks or polling to detect settlement.
Subscribe to payments notifications. The same channel delivers both inbound payment events and refund events. Use the type field to tell them apart.
4

(Optional) Issue an additional partial refund

If the original refund was partial and the intent still has refundable balance, you can issue further partial refunds up to the total settled amount. Each additional refund still requires the intent to be within 30 days of its creation date, and each call must use a unique idempotencyKey.