Refunds, Corrections & Retries
The rules and actions for undoing or retrying a transaction.
Alfred has no cancel endpoint. A deposit refund covers sending a pay-in back to the payer. For a payout that fails, you send a new one.
Refunding a deposit
POST /v1/deposits/{depositId}/refund
A refund is a request raised against the original deposit. It is an action on that deposit and does not create a transaction of its own.
When you can raise one
You can request a refund while the deposit hasn't reached a terminal state. Once it is COMPLETE, FAILED, CANCELLED or BLOCKED, the request is refused with parent_terminal.
If the deposit is waiting on compliance (PENDING_COMPLIANCE or PENDING_RFI), the request is queued behind the compliance decision and doesn't pre-empt it.
Two things that catch people
A refund has no amount. It unwinds the whole deposit or none of it. There are no partial refunds, nothing accumulates, and there is no remaining-refundable figure to track.
The deposit moves when the refund is confirmed. Raising the request doesn't change the deposit'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.
When a payout fails
A payout that fails leaves the funds on the customer's balance. Read the failure reason on the payout, fix the cause (usually the destination details), and send a new payout with a new idempotency key.
Once the provider accepts a payout it cannot be canceled, so confirm the destination before you instruct.
Terminal transactions stay closed
Once a transaction reaches COMPLETE, FAILED, CANCELLED or BLOCKED it is terminal. Nothing 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 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 words often get used interchangeably. They mean different things.
* Refund is an action you request against a deposit.
* 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 11 days ago

