How-to guide
Set up your organization
The order to set up a new organization, from the first key to the first review decision, with the onboarding checklist as your guide.
This guide takes an admin from a first sign-in to a first review decision. Yaqeen keeps a four-step checklist for your organization, and the steps below follow it. You need an admin account.
Before you start#
- The first admin account is created by whoever runs your deployment. See Getting started.
- Sign in as in Authentication. Then change the password you were given with
POST /api/v1/auth/password/and the body{"current_password": "...", "new_password": "..."}. The answer is204.
Check where you are#
GET /api/v1/onboarding/ returns the checklist. Reviewers and admins can call it. A merchant gets 403.
{
"steps": [
{ "id": "key", "title": "Create an API key", "hint": "...", "done": false },
{ "id": "data", "title": "Send your first payouts", "hint": "...", "done": false },
{ "id": "hold", "title": "See a recommended hold", "hint": "...", "done": false },
{ "id": "decision", "title": "Make a review decision", "hint": "...", "done": false }
],
"done": 0, "total": 4, "next": "key", "complete": false
}next is the id of the first step that is not done. complete becomes true when all four are done. Yaqeen reads each step from your data, so nothing needs to be ticked by hand. The checklist looks at your real organization only. A sandbox key or the sandbox sample data does not complete a step.
1. Create an API key#
The step key is done when your organization has an API key. Send POST /api/v1/keys/:
{ "name": "erp", "scopes": ["read", "decide", "ingest"], "days": 90 }The key is shown once. Give a system the ingest scope if it will send data. See Authentication for what each scope allows.
2. Send your first payouts#
The step data is done when at least one payout is loaded. Follow Load your data. Load owners and stores before payouts. To practise first, use the sandbox.
3. See a recommended hold#
The step hold is done when your organization has at least one hold. An admin queues a scoring run:
curl -X POST https://API/api/v1/scoring/runs/ \
-H "Content-Type: application/json" -H "X-CSRFToken: $CSRF" -H "Referer: https://API/" -b jar \
-d '{"recent_days": 7}'The answer is 202 and a job with the status queued. A worker picks it up within five minutes. Check it with GET /api/v1/jobs/{id}/. When the status is done, result looks like {"made": 3, "skipped": 0, "suppressed": 0}. recent_days is 1 to 60 and the default is 7.
With payouts alone, Yaqeen can only check how stores are tied to bank accounts. It looks at payouts from the last recent_days days of your data. Load orders and the other tables too, and Yaqeen checks much more. List the result with GET /api/v1/holds/?status=recommended.
A recommended hold holds no money. A person decides each one.
4. Make a review decision#
The step decision is done when any hold is approved, rejected or released. Follow Review a hold. When this step is done, complete is true.
After the four steps#
- Invite your team. See Invite users and set roles. Holds above the limit need a second person, so at least two people must be able to decide.
- Check the limits. The review time, the amount that needs a second person and the appeal window all have defaults. See Settings.
- Connect your systems. Use webhooks to hear about decisions.
- Find things fast.
GET /api/v1/search/?q=finds a store by its id or part of its name, and lists its open holds. Staff only. Send at least 2 characters. - Open the portal to your store owners. See Use the merchant portal.
If it does not work#
403on/api/v1/onboarding/: a merchant account called it. Use a staff account.- A step stays
falseafter you did it: you may have worked in the sandbox. The checklist reads your real organization only. - The scoring job stays
queued: jobs start within about five minutes. If it waits longer, ask your Yaqeen contact. - The job is
donewith"made": 0: nothing in the lastrecent_daysdays needed a hold. Check thedeposit_datevalues you loaded.
For more, see Troubleshooting.
Next steps#
- Load your data: the second step in detail.
- Review a hold: the fourth step in detail.
- Invite users and set roles: add your team.
- Organizations: how your data stays apart from other customers.