Anton.Docs
Dashboard (opens in a new tab)

Payouts that need approval

Approval is a person's decision in the dashboard, and your credentials cannot make it. The API only tells you a payout is waiting.

When a payout matches one of your own approval policies, it waits for a second person on your team. Approving or rejecting happens in the dashboard, because it takes a signed-in person with the right role. No API call can do it.

Before you begin

What you see at creation

POST /v1/payouts returns the payout as pending_approval instead of created.

A policy can also refuse the request outright. That is 422 policy_blocked, and no payout is created.

422policy_blocked
Your own approval policy blocks the payout. Review the rule on your account; retrying the same request gets the same answer.

Events

Three events track the wait. payout.approval_required and payout.approval_expired are in the Approvals category of GET /v1/webhooks/event-types, and payout.approved is with the other payout events.

EventMeans
payout.approval_requiredThe payout matched a policy and is waiting on an approver.
payout.approvedThe payout was approved and will be sent.
payout.approval_expiredThe approval window lapsed with no decision, and the payout was cancelled.

Each carries the payout in data.object. approved_at on the payout is null until it is approved.

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

A payout that waits shows pending_approval, and approved_at stays null until someone approves it.

Reference
Not yet tested in sandbox
curl https://api.antonpayments.dev/v1/payouts/pay_dbvqrpqukoh470i0a400 \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"

How the wait ends

pending_approvalWaiting on a second person
approved
processingApproved, checked and submitted

A payout in pending_approval can also become cancelled.

Approved goes to processing, and the checks in How Anton evaluates payouts still apply from there, so a payout can still be held. You can cancel it yourself from pending_approval with POST /v1/payouts/{id}/cancel.

When the approval window lapses, the payout is cancelled and the money it held goes back to your balance; payout.approval_expired follows. If a compliance review is holding the payout at that moment, the expiry waits until the review ends.

Who can approve

The creator can never approve their own payout. created_by names the user for a payout made in the dashboard, and it is null for one made with programmatic credentials or in a batch. Because a credential can never approve, a payout your integration creates always needs a person on your team. If nobody else can approve, it waits.

What to build

  • Notify your approvers on payout.approval_required, with the payout id. Don't poll.
  • Show your user a waiting state, not a failure.
  • Alert on a payout that stays in pending_approval past your own deadline, and on payout.approval_expired.
  • Update your records from the event. The payout in it is the same object GET /v1/payouts/{id} returns.

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