YaqeenDocs
Back to Yaqeen

How-to guide

Review a hold

Find the next recommended hold, read its reasons and evidence, and approve, reject or release it.

This guide shows how to review one recommended hold and decide it. You need a reviewer or admin account. A system can decide with an API key that has the decide scope.

Before you start#

  • At least one hold has the status recommended. An admin makes holds with a scoring run.
  • You are signed in. A key with the read or decide scope can call the GET endpoints and the decision endpoint. Claiming from the queue needs a signed-in person. See Authentication.

1. Find a hold#

The review queue ranks recommended holds. The priority is built from the risk score, the amount and the time the hold has waited.

  • POST /api/v1/queue/next/ gives you the best hold that nobody else has claimed. The claim lasts 30 minutes by default, and one person can hold 3 claims by default. Both limits are settings.
  • GET /api/v1/queue/ lists your claimed holds and the best unclaimed ones, with the parts of each priority.
  • POST /api/v1/queue/{hold_id}/release/ gives a claim back.
  • GET /api/v1/search/?q=Test finds stores by their id or part of a name, and lists the open holds of those stores. Open means recommended or approved. Send at least 2 characters.

To filter the full list, use GET /api/v1/holds/ with status, deposit_from, deposit_to, amount_min and amount_max.

2. Read the hold#

GET /api/v1/holds/{id}/ returns the score, the reasons and the documents that would help the merchant. Each reason has a code, a sentence in English (text_en) and one in Arabic (text_ar), and the evidence behind it.

GET /api/v1/holds/{id}/explain/ adds how the score compares: This hold scored higher than 62 percent of all holds. The number is an example.

3. Look at the parties around the payout#

GET /api/v1/holds/{id}/case/ returns a graph of stores, owners, customers, devices and bank accounts. Each link is exact or weak. An exact link, such as a shared bank account, shows the same party. A weak link is a hint for you to check. It does not prove that two people are the same.

To see the orders behind a reason, take its orders_filter value and call GET /api/v1/holds/{id}/orders/?reason={orders_filter}. If orders_filter is null, that reason has no orders to list, and the call answers 400 reason_has_no_orders.

When a reason is about chats that ask the buyer to pay outside the platform, call GET /api/v1/holds/{id}/chats/. It lists the store's flagged lines from the 30 days before the deposit, newest first. Each line comes in pieces, so you can mark the words that matched, and carries the buyer's next line when there is one. No buyer is named and no buyer id is returned. Every page you read is written to the audit log as hold.chats_opened, with the number of lines, the page offset and your name. Only a reviewer or an admin can read it.

In the dashboard, a hold with this reason has a Chats tab, and Ask the merchant about these chats opens a message you can edit before it is sent. The message goes to the hold's thread, so the store can answer in its portal.

4. Decide#

Send POST /api/v1/holds/{id}/decision/.

DecisionAllowed when the hold isNoteResult
approverecommendedOptionalThe payout is held until hold_until. The merchant is told and can appeal.
rejectrecommendedRequiredThe recommendation is dropped. The payout is paid as usual.
releaseapprovedRequiredThe payout is released. The merchant is told.
bash
curl -X POST https://API/api/v1/holds/$ID/decision/ \
  -H "Authorization: Bearer yq_live_..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c2a-approve-001" \
  -d '{"decision":"approve","note":"Three owners share one bank account."}'

A note is at most 500 characters. To hold only part of a payout, add "amount": "1000.00" to an approval. The amount must be above zero and no more than the payout.

If the payout is above the limit, the answer is 202 with "status": "pending_approval". Nothing is held yet. A second person must approve the change. See Approve a change as the second person. Send an Idempotency-Key so a retry cannot decide twice. See Safe retries.

What you see now#

The response is the hold with its new status, your name in decided_by, and your note in decision_note. After an approval it also has appeal_by, the last day the merchant can appeal. The appeal window is 14 days by default. Every decision is written to the audit log.

If it does not work#

  • 400 note_required: add a note. Rejecting and releasing need one.
  • 409 bad_transition: the hold was already decided, or the decision does not fit its status. Read the hold again.
  • 403: your role cannot decide. Ask a reviewer or an admin.
  • 409 too_many_claims: you hold your limit of claims. Decide one or release one.
  • 404 queue_empty: no unclaimed hold is waiting.

For more, see Troubleshooting.

Next steps#

Up Down to moveEnter to openEsc to close