How-to guide
Handle an appeal
Find an open appeal, read the statement and documents, talk to the merchant, and accept or reject it.
This guide shows how to decide an appeal that a merchant filed against an approved hold. You need a reviewer or admin account.
Before you start#
- The hold is
approved. Only an approved hold can be appealed. - The merchant has not passed
appeal_by, the last day to appeal. The window is 14 days by default and starts on the day of the approval. After that day a new appeal answers400 appeal_closed. - A hold can have only one open appeal. A second one answers
409 already_open.
In the dashboard#
Open Appeals. The ones that wait for a decision come first, the longest wait on top. Open one to see the payout and its risk, why it was held, what the merchant wrote, the files they sent next to the documents they were asked for, and what has happened on the hold so far. Open case and Open hold take you to the records, and Back returns you to the same appeal. From the same panel you can ask the merchant for more, or accept or reject the appeal. After a decision, Next appeal opens the one that has waited longest. The steps below use the API.
1. Find the appeal#
Yaqeen has no list of open appeals and sends no webhook when one is filed. Use one of these:
GET /api/v1/audit/?subject_type=appeallists appeal events. A row with the actionappeal.filedhas the hold id inpayload.holdand the appeal id insubject_id. Reviewers and admins can read the audit log.GET /api/v1/holds/?status=approvedlists approved holds. For each one,GET /api/v1/holds/{id}/appeals/lists its appeals, andGET /api/v1/holds/{id}/has them inappeals.
An appeal has a status of open, accepted or rejected.
2. Read the statement and documents#
The merchant writes a statement of up to 1,000 characters. Read it in the statement field of the appeal.
To read uploaded documents:
- Call
GET /api/v1/holds/appeals/{appeal_id}/documents/. It lists the files that finished uploading. - Call
GET /api/v1/holds/appeals/{appeal_id}/documents/{document_id}/download/. The answer has aurlandexpires_in. The link works for 300 seconds. Each opening is written to the audit log.
The hold lists the documents that would help in documents_needed, for example a bank letter.
3. Ask the merchant for more (optional)#
If you need a paper or an answer, write in the thread of the hold:
curl -X POST https://API/api/v1/portal/holds/$HOLD_ID/messages/ \
-H "Authorization: Bearer yq_live_..." -H "Content-Type: application/json" \
-d '{"text":"Please upload a bank letter for the shared account."}'The merchant sees the message from "Review team", not from your name. A message is at most 1,000 characters. GET on the same path lists the thread.
4. Decide#
Send POST /api/v1/holds/appeals/{appeal_id}/decision/. A note is required.
| Decision | Result |
|---|---|
accept | The hold is released with your note, and the payout is paid. The appeal is accepted. |
reject | The hold stays. The payout stays held until hold_until. The appeal is rejected. |
curl -X POST https://API/api/v1/holds/appeals/$APPEAL_ID/decision/ \
-H "Authorization: Bearer yq_live_..." -H "Content-Type: application/json" \
-d '{"decision":"reject","note":"The bank letter names a different owner."}'What you see now#
The response is the appeal with its new status and your decision_note. The merchant gets a notice in Arabic and English: Your appeal for Store 3 was rejected. The payout of 5400.00 SAR stays on hold until 2026-11-23. An appeal.decided event goes to your webhooks. The audit log records the decision.
If it does not work#
400 note_required: add a note. Both decisions need one.409 bad_transition: the appeal was already decided. Another reviewer may have done it.403: your role cannot decide. Ask a reviewer or an admin.
For more, see Troubleshooting.
Next steps#
- Use the merchant portal: what the merchant sees while you handle the appeal.
- How holds and appeals work: the life of a hold and the rules for appeals.
- Webhooks: get
appeal.decidedevents in your own systems. - Export and verify the audit trail: prove who decided what.