Reference
Hold statuses
The four hold statuses, the changes that are allowed between them, and who can make each change.
A hold has one of four statuses. This page lists them and the allowed changes. A change that is not on this page is refused with 409 bad_transition.
Statuses#
| Status | Meaning | Open | Final |
|---|---|---|---|
recommended | Yaqeen recommends a hold. No money is held yet. | Yes | No |
approved | A reviewer approved the hold. The payout is held. | Yes | No |
rejected | A reviewer declined the recommendation. | No | Yes |
released | The held payout was released. | No | Yes |
A hold is open when its status is recommended or approved. A payout can have only one open hold. A second recommendation for the same payout is refused with 409 already_open.
Allowed changes#
| From | To | How | Who | Note |
|---|---|---|---|---|
| (new) | recommended | A scoring run | The system | A reviewer sees it in the queue. |
recommended | approved | decision: approve | Reviewer, admin | Optional amount for a partial hold. |
recommended | rejected | decision: reject | Reviewer, admin | A note is required. |
approved | released | decision: release | Reviewer, admin | A note is required. |
approved | released | An appeal is accepted | Reviewer, admin | The appeal decision releases the hold. |
approved | released | Automatic release | The system | After hold_until passes, with no open appeal. |
rejected and released have no further changes. A hold that is recommended cannot be released. A hold that is approved cannot be rejected or approved again.
What each change does#
- Approve. The payout status becomes
held. Yaqeen setsappeal_byto the decision date plus the appeal window from the policy (14 days by default). The merchant is notified and ahold.approvedwebhook event is queued. If you sendamount, it must be above 0 and no more than the payout amount. The hold then covers that amount only. - Reject. The payout status is
paid. The merchant is told nothing, because the merchant never saw the recommendation. - Release. The payout status returns to
paid. The merchant is notified and ahold.releasedevent is queued. When an accepted appeal releases the hold, the merchant gets the appeal notice and the event isappeal.decided.
Second-person approval#
A decision to approve or release can wait for a second person. It waits when the amount is above the organization's limit, or when the holds on one owner add up above the daily limit. The defaults are 5,000 SAR and 10,000 SAR, and an admin can change them. The call then returns 202 with status: pending_approval and an approval_id. A rejection never waits.
If no other eligible person exists in the organization, the change runs at once. See Second-person approval.
Appeal statuses#
An appeal has its own status. A merchant, or staff for a merchant, can file an appeal only on an approved hold, and only until appeal_by. A hold can have one open appeal at a time.
| Status | Meaning | Changes to |
|---|---|---|
open | Waiting for a reviewer. | accepted, rejected |
accepted | A reviewer accepted it. The hold is released. | Final |
rejected | A reviewer rejected it. The hold stays approved. | Final |
An appeal decision needs decision (accept or reject) and a note.
Who sees a hold#
Staff see holds in every status. A merchant sees only approved and released holds of its own owner. A recommended or rejected hold returns 404 for a merchant. Filter the list with GET /api/v1/holds/?status=approved. A status that is not in the table gets 400 bad_status.
Related#
- How holds and appeals work: why a person decides.
- Webhook events: the events behind approve and release.
- Errors:
bad_transition,already_open,note_requiredand more. - Review a hold: the steps for a reviewer.