YaqeenDocs
Back to Yaqeen

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#

StatusMeaningOpenFinal
recommendedYaqeen recommends a hold. No money is held yet.YesNo
approvedA reviewer approved the hold. The payout is held.YesNo
rejectedA reviewer declined the recommendation.NoYes
releasedThe held payout was released.NoYes

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#

FromToHowWhoNote
(new)recommendedA scoring runThe systemA reviewer sees it in the queue.
recommendedapproveddecision: approveReviewer, adminOptional amount for a partial hold.
recommendedrejecteddecision: rejectReviewer, adminA note is required.
approvedreleaseddecision: releaseReviewer, adminA note is required.
approvedreleasedAn appeal is acceptedReviewer, adminThe appeal decision releases the hold.
approvedreleasedAutomatic releaseThe systemAfter 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 sets appeal_by to the decision date plus the appeal window from the policy (14 days by default). The merchant is notified and a hold.approved webhook event is queued. If you send amount, 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 a hold.released event is queued. When an accepted appeal releases the hold, the merchant gets the appeal notice and the event is appeal.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.

StatusMeaningChanges to
openWaiting for a reviewer.accepted, rejected
acceptedA reviewer accepted it. The hold is released.Final
rejectedA 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.

Up Down to moveEnter to openEsc to close