Both are final, and neither can be retried in place. failed carries a failure_code. returned carries none, because the money went out first.
Read the ending
payout.failed and payout.returned carry the payout in data.object, the same object GET /v1/payouts/{id} returns. Branch on status, then on failure_code.
For a failed payout, failure_code says what the rail reported, and failed_at says when. status_message is set only for cannot_be_processed.
curl https://api.antonpayments.dev/v1/payouts/pay_dbvqrpqukoh470i0bco0 \ -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \ -H "DPoP: $DPOP_PROOF"
Failed
A payout fails before it is sent, or while the rail has it. processing can go to failed, on_hold can go to failed, and so can sent.
failure_code | Means | Do |
|---|---|---|
| cannot_be_processed | Anton could not process the payout and cannot say more. | Don't retry to the same payee. Contact support with the payout id and the request_id. |
provider_rejected | The rail refused the payout, including when it rejects the receiving account. | Check the payee and instrument, then create a new payout. |
provider_unavailable | The rail reported it was unavailable. | Create a new payout later. |
insufficient_funds | The rail reported a shortfall after Anton sent the payout. Your own balance is checked earlier, at create, as 422 insufficient_balance. | Check the amounts, then create a new payout. Contact support if it repeats. |
beneficiary_not_found | Anton could not load the payee when it went to send, for example because the payee was deleted after the payout was created. | Check the payee still exists, then create a new payout. |
Treat a code you don't know as a plain failure. New values can be added without breaking you.
A failed payout cannot be revived. Fixing the cause means a new payout, with a new Idempotency-Key, since the old key would give you the failed payout back for 24 hours. Mark your own record as failed from the event, then decide whether to pay again.
Create the replacement only when you know the first did not pay. A failed status is final, so it is safe. A payout that is only taking long is not.
Returned
returned is reachable only from sent: the funds came back after being sent, and payout.returned says the receiving institution returned them. Your user did not get paid.
The whole amount comes back to your balance, fee included. The movement shows in the transactions list; Reconcile with transactions covers reading it.
What to tell your user
- Failed: the payment did not go out. Say so, and say what you will do next. For
cannot_be_processed, don't invent a reason; Anton gives none. - Returned: the payment went out and came back. Say the payee's institution sent it back, and ask for corrected details before you pay again.
Don't show failure_code to your user as text. It's for your code.