Refunds, Corrections & Retries
The rules and actions for undoing or retrying a transaction.
Alfred has no cancel endpoint. Refund covers both stopping something before it executes and pulling it back after.
Which action you need depends on whether the parent has reached a terminal state and, if it hasn't, whether it has already executed.
Refund
POST /v1/deposits/{depositId}/refund
POST /v1/conversions/{conversionId}/refund
POST /v1/payouts/fiat/{payoutId}/refund
POST /v1/payouts/stablecoin/{payoutId}/refundA refund is a request raised against the original transaction. It is an action on that transaction and does not create a transaction of its own.
When you can raise one
transaction_status | Requestable | What happens |
|---|---|---|
CREATED, PENDING_VALIDATION, PENDING_FUNDS | Yes | The lock unwinds and the balance is released. Nothing moved, so the parent lands CANCELLED. |
APPROVED_FOR_EXECUTION | Yes | The same unwind applies, as long as no leg went to a provider. |
PROCESSING | Yes | If the rail hasn't accepted it yet, the lock unwinds. If it has, a return is requested from the destination. |
PENDING_COMPLIANCE, PENDING_RFI | Yes | The request is queued behind the compliance decision and doesn't pre-empt it. |
COMPLETE | No | The transaction is terminal. |
FAILED, CANCELLED, BLOCKED | No | The transaction is terminal. Value already came back or never left. |
One call with two behaviors
The parent hasn't executed. The lock unwinds directly and the held balance is released. No provider is contacted and no value moves. This is the case that used to be a cancel.
The parent has executed but isn't terminal. The destination or provider is asked to return the funds. It completes only on confirmed receipt, so the refund itself can sit in processing for as long as the rail takes.
In both cases the parent lands CANCELLED. If value briefly moved, you can see that one level down, because the leg carries leg_status: RETURNED.
Two things that catch people
A refund has no amount. It unwinds the whole parent or none of it. There are no partial refunds, nothing accumulates, and there is no remaining-refundable figure to track.
The parent moves when the refund is confirmed. Raising the request doesn't change the parent's status. Read it back with GET /v1/refunds/{actionId}, because a refund is a request and that read is how you learn whether it was honored.
Wait on refund.updated.
Correction
POST /v1/payouts/fiat/{payoutId}/correctionUse a correction for a payout whose leg came back RETURNED. The money went out and the destination bounced it, so you need to send it somewhere else.
The original failed leg is preserved and a corrective leg is issued to the destination you supply. The single-writer rule guarantees the original and the correction are never live at two providers at once.
If you raise a correction against a payout that didn't return, you get not_returned.
Reprocess
POST /v1/payouts/fiat/{payoutId}/reprocessUse reprocess for a payout that FAILED without the money coming back. This is a partner-initiated retry.
A payout whose leg came back RETURNED needs a correction instead.
Choosing between them
| Situation | Verb |
|---|---|
| You changed your mind, nothing has executed | refund |
| It's executing and you want it back | refund |
| The destination bounced it | correction |
| It failed and the money never left | reprocess |
It's COMPLETE | None of these. See below. |
Terminal transactions stay closed
Once a transaction reaches COMPLETE, FAILED, CANCELLED or BLOCKED it is terminal. No refund, reversal or correction reaches back into it.
Moving value back at that point is an ordinary new pay-in or payout in the opposite direction. It has its own lifecycle, its own controls and its own idempotency key, and it can fail on its own.
This reflects how cross-border settlement actually works, because a completed payout genuinely isn't recallable. It also keeps the ledger append-only, so a terminal transaction records what happened and can't be edited.
A recovery transaction carries no reference to what it recovers. Nothing points back at a closed transaction. If you need the two associated for your own reconciliation, use the reference and metadata fields.
Vocabulary
These three words often get used interchangeably. They mean different things.
- Refund is an action you request against a transaction.
- Returned describes value that an external institution sent back without being asked.
- Reversed is a state on a payment leg. It doesn't describe something you requested.
Updated 5 days ago