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.


Did this page help you?