Check a buyer
POST /checkCall it before the order is placed, with the hashes of the buyer’s identifiers (hashing). Only email_hash is required; send every hash you have.
{ "email_hash": "8cd79ce2224abde026ddc67563fe5edb8b5eb41846c63cd550a76ea76cc2eddd", "phone_hash": "038e5821814169825ae568bfefdb18ca31d4d2e0a0f5941b6da27df45d50ddf4", "address_hash": "956b4ad633a194c484c3fdd6d6145ec1ac929b211438b3452e79b4853f65df96", "email_domain_hashes": ["4672a2431309380c7954c449b3ff20d2cd31968853d6e98137dd3b0be3652dae"], "email_domain_mx": true, "strictness": "normal"}| Field | Type | |
|---|---|---|
email_hash |
hash | required |
phone_hash |
hash or null |
|
address_hash |
hash or null |
shipping address |
email_domain_hashes |
array of hashes, at most 5 | the domain and its parent suffixes |
email_domain_mx |
true, false or null |
your own MX check |
strictness |
lenient, normal (default), strict |
how a risky buyer is handled |
Unknown fields are rejected with 400. A test key sees test reports only.
Response
Section titled “Response”{ "verdict": "block", "level": "blocked", "score": 33, "reasons": ["NEGATIVE_MULTI_ACCOUNT", "NEGATIVE_RECENT", "LOW_SCORE"], "stats": { "delivered": 0, "refused": 2, "accounts_refused": 2 }, "check_id": "01a1a17c-7e54-7032-95b4-ba478164249b"}| Field | Meaning |
|---|---|
verdict |
what to do: allow, flag or block |
level |
trusted, unknown, risky or blocked |
score |
0 to 100; 75 without any history |
reasons |
the codes below, in a fixed order |
stats |
pick-ups, refusals and the number of accounts that reported a refusal, for the worst identifier, over three years |
check_id |
an id for support requests; also in the X-Check-Id header |
Each identifier (e-mail, phone, address) is scored on its own, and the worst one counts. A new e-mail address cannot clean a phone number with refusals.
| Level | When |
|---|---|
blocked |
fresh refusals from at least two accounts, and a score below 60 |
risky |
a refusal in the last 365 days, or a score below 60, or a disposable or mail-less e-mail domain |
trusted |
at least three pick-ups and no fresh refusal |
unknown |
everything else, for example no history |
A refusal counts as fresh for 365 days. The address weighs half as much as the e-mail and the phone, because many people share one (blocks of flats, parcel points).
Verdict
Section titled “Verdict”The level and the strictness of the request give the verdict:
| Strictness | blocked |
risky |
unknown, trusted |
|---|---|---|---|
lenient |
block |
allow |
allow |
normal |
block |
flag |
allow |
strict |
block |
block |
allow |
A shop exception overrides it: allow always gives allow, deny always gives block (exceptions). The level and the score are still computed.
Reasons
Section titled “Reasons”| Code | Meaning |
|---|---|
NEGATIVE_MULTI_ACCOUNT |
refused at several accounts: this made the level blocked |
NEGATIVE_RECENT |
a refusal in the last 365 days |
LOW_SCORE |
the score is below 60 |
DISPOSABLE_DOMAIN |
the e-mail domain belongs to a disposable e-mail service |
DOMAIN_NO_MX |
the e-mail domain cannot receive mail (your email_domain_mx was false) |
NO_HISTORY |
no report for any identifier yet |
SHOP_ALLOW |
your exception allows this buyer |
SHOP_DENY |
your exception blocks this buyer |
What to do with the verdict
Section titled “What to do with the verdict”The verdict is a suggestion; the shop decides. For example: on block hide cash on delivery and offer prepayment, on flag show a note to the shop staff, on allow change nothing. Never leave the buyer with no way to pay.