Anton.Docs
Dashboard (opens in a new tab)

Handle returns and failures

A failed payout did not go through, and a returned one went out and came back. Your code reads a different field for each.

Both are final, and neither can be retried in place. failed carries a failure_code. returned carries none, because the money went out first.

Before you begin

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.

GET/v1/payouts/{id}Read a failed payout

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.

Reference
Not yet tested in sandbox
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_codeMeansDo
cannot_be_processedAnton 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_rejectedThe rail refused the payout, including when it rejects the receiving account.Check the payee and instrument, then create a new payout.
provider_unavailableThe rail reported it was unavailable.Create a new payout later.
insufficient_fundsThe 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_foundAnton 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.

When it goes wrong

409payout_not_cancellable
You tried to cancel a payout that is already with a rail, or finished.
404resource_missing
The payout does not exist or belongs to another merchant.

Something wrong or missing here? Open an issue (opens GitHub in a new tab) ↗