Skip to content
Documentation for: TrustOrder
HUuptools.io
Markdown

Check a buyer

POST /check

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

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

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.

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

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.