Tutorial
Your first hold in the sandbox
Create a sandbox, load made-up payouts, read a recommended hold and approve it with curl in about five minutes.
In this tutorial you create a sandbox, read a recommended hold and approve it. It takes about five minutes. Nothing touches real data: the sandbox is a separate organization with made-up stores and payouts.
Before you start#
- An admin account. The first admin is created by whoever runs your deployment (see Getting started).
curland a terminal. Any shell that runscurlworks.- Your API address. The examples use
https://yaqeen.example.test. Replace it with yours. - For step 5, your Yaqeen contact. They score your sandbox for you.
1. Sign in#
Set two variables. Then get a CSRF token (a value that proves a request comes from your own session) and sign in. Use your own username and password.
API=https://yaqeen.example.test
curl -s -c jar $API/api/v1/auth/csrf/ > /dev/null
CSRF=$(grep csrftoken jar | awk '{print $7}')
curl -s -b jar -c jar -X POST $API/api/v1/auth/login/ \
-H "Content-Type: application/json" -H "X-CSRFToken: $CSRF" -H "Referer: $API/" \
-d '{"username":"YOUR-USERNAME","password":"YOUR-PASSWORD"}'
CSRF=$(grep csrftoken jar | awk '{print $7}')The response shows who you are:
{"username":"YOUR-USERNAME","role":"admin"}2. Create the sandbox and load the sample data#
curl -s -b jar -X POST $API/api/v1/sandbox/ -H "X-CSRFToken: $CSRF" -H "Referer: $API/"
curl -s -b jar -X POST $API/api/v1/sandbox/seed/ -H "X-CSRFToken: $CSRF" -H "Referer: $API/"The two responses:
{"exists":true,"slug":"example-sandbox"}
{"owners":3,"stores":3,"payouts":6}The sample data is generated. It has three owners whose stores all pay out to one bank account. It has six payouts of 500 to 700 SAR.
3. Make a test key#
A test key starts with yq_test_ and sees only the sandbox. The next command saves the key in a shell variable. The key is shown once.
KEY=$(curl -s -b jar -X POST $API/api/v1/keys/ \
-H "Content-Type: application/json" -H "X-CSRFToken: $CSRF" -H "Referer: $API/" \
-d '{"name":"quickstart","scopes":["read","decide"],"days":7,"sandbox":true}' \
| sed -E 's/.*"key":"([^"]+)".*/\1/')
echo "$KEY" | cut -c1-14The output is the start of the key:
yq_test_x8mvAl4. Read the sample payouts#
curl -s "$API/api/v1/payouts/?limit=2" -H "Authorization: Bearer $KEY"{"count":6,"next":"https://yaqeen.example.test/api/v1/payouts/?limit=2&offset=2","previous":null,"results":[
{"payout_id":"sbx-p0","store_id":"sbx-s1","amount":"500.00","fee":"5.00","deposit_date":"2026-11-15","status":"paid"},
{"payout_id":"sbx-p1","store_id":"sbx-s2","amount":"540.00","fee":"5.00","deposit_date":"2026-11-15","status":"paid"}]}The deposit_date is the day you loaded the sample data. The list of holds is still empty, because nothing has scored these payouts yet.
5. Make the holds#
A scoring run that you queue with the API runs on your real organization, not the sandbox. So ask your Yaqeen contact to score your sandbox. When they confirm, the holds are there:
curl -s "$API/api/v1/holds/?status=recommended" -H "Authorization: Bearer $KEY" | grep -o '"count":[0-9]*'A recommended hold is only a recommendation. No payout is held until a person approves it.
6. Read one hold#
HOLD=$(curl -s "$API/api/v1/holds/?status=recommended&limit=1" -H "Authorization: Bearer $KEY" \
| sed -E 's/.*"results":\[\{"id":"([^"]+)".*/\1/')
curl -s "$API/api/v1/holds/$HOLD/" -H "Authorization: Bearer $KEY"The response is long. This is a shortened copy with the fields to read. The ids and dates differ in your sandbox.
{
"id": "dc40fe16-b0a8-4445-846a-35e3416918af",
"status": "recommended",
"score": "0.7400",
"payout_amount": "700.00",
"reason_codes": ["shared_beneficiary"],
"reasons": [{
"code": "shared_beneficiary",
"text_en": "3 stores with 3 different owners send their payouts to the same bank account.",
"text_ar": "3 متاجر لـ 3 ملاك مختلفين تحوّل مدفوعاتها إلى حساب بنكي واحد.",
"evidence": [ ... ]
}],
"hold_until": "2026-11-23",
"appeal_by": null
}The reason is written in Arabic and English. The evidence list names the three stores and owners behind it.
7. Approve the hold#
A note is optional when you approve, but it tells the next reader why. The payout is below the default limit of 5,000 SAR, so no second person is needed.
curl -s -X POST "$API/api/v1/holds/$HOLD/decision/" \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"decision":"approve","note":"Three owners share one bank account."}'In the response, status is now approved, decision_note holds your note and appeal_by has a date. That date is the last day the merchant can appeal.
Check that it worked#
curl -s "$API/api/v1/holds/?status=approved" -H "Authorization: Bearer $KEY"The response has "count":1. The payout of that hold now has the status held.
Start over#
Reset empties the sandbox. Your real organization and your test keys stay. Then you can load the sample data again.
curl -s -b jar -X POST $API/api/v1/sandbox/reset/ -H "X-CSRFToken: $CSRF" -H "Referer: $API/"Next steps#
- Review a hold: what a reviewer reads and decides, in more detail.
- Set up your organization: the same steps with your real data.
- Authentication: keys, scopes and sessions for your systems.
- The sandbox: what the sandbox can and cannot do.