How-to guide
Use the merchant portal
Give a store owner an account, and see what that account can read, send and file through the API.
The merchant portal is the set of API calls that a store owner's account can use. The owner can sign in to Yaqeen and use them there, or your own app can call them for the owner. This guide shows how an admin gives an owner access, and what the account can see and do.
Give a store owner access#
An admin creates a merchant account for one owner with POST /api/v1/users/merchants/. See Invite users and set roles. The owner signs in with the same POST /api/v1/auth/login/ as staff.
A merchant account belongs to one owner. It sees only that owner's stores, payouts and holds. A hold appears only after a reviewer approves it, so the owner never sees a hold that is still a recommendation.
What the owner can read#
The table lists the calls that read data. All paths start with /api/v1.
| Call | What the owner gets |
|---|---|
GET /portal/summary/ | Active holds, released holds, amount held, next appeal deadline, next release date, open appeals, unread notices and unread messages. |
GET /holds/ | The owner's approved and released holds. |
GET /holds/{id}/explain/ | Why the payout is held, in plain Arabic and English, what to do, and the documents that would help. It carries no score and nothing about other parties. |
GET /portal/holds/{id}/timeline/ | The story of one hold in order, in both languages. |
GET /portal/ledger/?months=6 | Paid, held and released-after-hold amounts by month. months is 1 to 24. |
GET /reserves/mine/ and GET /reserves/disputes/mine/ | Money held back, and open disputes with the date to answer by. |
GET /portal/export/ | The owner's own holds and payouts as a CSV file. |
GET /notifications/ | The owner's notices. POST /notifications/{id}/read/ and POST /notifications/read-all/ mark them read. |
What the owner can send#
| Call | What it does |
|---|---|
GET and POST /portal/holds/{id}/messages/ | A thread with the review team. The owner sees "Review team", never a reviewer's name. A message is at most 1,000 characters. |
POST /holds/{id}/appeals/ | File an appeal with a statement of up to 1,000 characters. Only an approved hold can be appealed, and only until appeal_by. |
POST /holds/appeals/{id}/documents/ | Ask to upload a document. Send file_name, content_type and size. The answer holds a signed form to upload to. |
POST /holds/appeals/{id}/documents/{document_id}/confirm/ | Confirm the upload. |
POST /reserves/disputes/{id}/respond/ | Answer a dispute. The owner has 10 days. |
GET and PUT /portal/preferences/ | language (ar or en), push_enabled and appeal_reminders. |
In the dashboard, the thread is in the payout's panel, under the appeal and its documents. A notice that says the review team wrote opens that panel. When a hold is about chats, the documents list also asks for a short written explanation of those chats and of who writes to buyers for the store.
A document is a PDF, JPEG or PNG of at most 10 MB. An appeal takes up to 5 documents. How a reviewer answers is in Handle an appeal.
Notices and reminders#
The owner gets a notice, in Arabic and English, when a hold is approved or released, when an appeal is decided, and when the review team writes a message. Phones that the owner registered also get a short push message, unless the owner turns push off.
If the owner has not appealed, a reminder comes 3 days and 1 day before the appeal window closes. The owner can turn reminders off with appeal_reminders.
If it does not work#
404on a hold: the hold belongs to another owner, or it is still a recommendation. Both answer the same way.403on a staff call such as/onboarding/: merchant accounts cannot use staff endpoints./search/is open to merchants and returns only their own payouts.400 appeal_closed: the appeal window ended. The message gives the date.409 already_open: the hold already has an open appeal.
For more, see Troubleshooting.
Next steps#
- Handle an appeal: the reviewer side of what the owner files.
- How holds and appeals work: the life of a hold from the owner's side.
- Privacy and trust: what is stored and who can see it.
- Webhooks: tell your own app when a hold changes.