YaqeenDocs
Back to Yaqeen

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).
  • curl and a terminal. Any shell that runs curl works.
  • 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.

bash
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:

json
{"username":"YOUR-USERNAME","role":"admin"}

2. Create the sandbox and load the sample data#

bash
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:

json
{"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.

bash
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-14

The output is the start of the key:

text
yq_test_x8mvAl

4. Read the sample payouts#

bash
curl -s "$API/api/v1/payouts/?limit=2" -H "Authorization: Bearer $KEY"
json
{"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:

bash
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#

bash
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.

json
{
  "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.

bash
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#

bash
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.

bash
curl -s -b jar -X POST $API/api/v1/sandbox/reset/ -H "X-CSRFToken: $CSRF" -H "Referer: $API/"

Next steps#

Up Down to moveEnter to openEsc to close