YaqeenDocs
Back to Yaqeen

Explanation

How reasons are written

Why every hold carries a reason in Arabic and English, who writes the sentences, and what each reader sees.

Every hold recommendation carries one or more reasons. A reason says in plain words why the payout was flagged, and it points to the data behind it. This page explains how reasons are made, why they come in two languages, and what staff and merchants see.

What a reason contains#

A reason has a stable code, a sentence in English (text_en), the same sentence in Arabic (text_ar), and a list of evidence. Yaqeen refuses to save a hold without at least one reason, and refuses a reason that lacks a code or either language.

json
{
  "code": "failed_card_attempts",
  "text_en": "One or more declined card attempts came before an order in the last 30 days.",
  "text_ar": "وقعت محاولة دفع بالبطاقة مرفوضة أو أكثر قبل طلب خلال آخر 30 يومًا.",
  "evidence": [{ "feature": "declined_attempts", "value": "3" }],
  "orders_filter": "failed_card_attempts"
}

The values in this example are made up.

Who writes the sentences#

No language model writes a reason. Each check has one fixed sentence in each language, so every sentence traces to a check. The numbers in a sentence come from your data.

There are three kinds of reason:

  • Check reasons. One fixed sentence per check that matched, such as "Stores with different owners send their payouts to the same bank account." The evidence lists the stores and owners.
  • Score reasons. The factors that raised the score the most, each with its value, for example "The store is new (12 days)."
  • Link reasons. When the store owner is linked to other owners, the reason names the linked owners and their stores. A reviewer can check each one.

Why two languages#

The product serves readers of Arabic and of English. A merchant has to understand why money was held in order to appeal. So each reason is stored in both languages when the hold is created. The notice and the decision both use these stored reasons, so the explanation cannot drift from the decision.

What each reader sees#

ReaderSees
Staff, hold detailScore, every reason with its full evidence, and orders_filter.
Staff, GET /api/v1/holds/{id}/explain/The score with a percentile ("scored higher than 40 percent of all holds"), and the reasons with the count of evidence items.
Merchant, GET /api/v1/holds/{id}/explain/A notice with the reasons in both languages, what to do next, the appeal date and the documents that would help. No score, no model name and nothing about another party.
Merchant, hold detailThe reasons with an empty evidence list. No reviewer names and no internal notes.

The documents a merchant is asked for depend on the reason. For example, a shared bank account asks for a bank letter and the commercial registration.

Check the orders behind a reason#

Staff can list the orders a reason is about with GET /api/v1/holds/{id}/orders/?reason=<orders_filter>. The window is the store's 30 days before the deposit. When orders_filter is null, the reason has no orders behind it, for example a shared bank account or the payout amount, and the API says so instead of guessing.

Up Down to moveEnter to openEsc to close