Shield
Fraud thresholds, blocklist and statistics, from the API.
Shield scores every live payment and acts on the score: below your review threshold it passes, between the two it is queued for review, at or above your block threshold it is refused. These endpoints read and write that configuration.
| Method | Endpoint | What it does |
|---|---|---|
GET | /shield/settings | Read your thresholds and switches |
PUT | /shield/settings | Change them |
GET | /shield/stats | Blocked, reviewed and disputed this month |
GET | /shield/blocklist | List your blocked values |
POST | /shield/blocklist | Block a value |
DELETE | /shield/blocklist/{id} | Unblock it |
Live only, private key only
/shield needs a private key (sk.) and refuses a sandbox key with
403 This feature is only available in live mode. Unlike every other resource, there is no
Shield scope, so a restricted key cannot reach it at all.
Settings
https://api.wajub.com/shield/settingscurl https://api.wajub.com/shield/settings \
-H "Authorization: $WAJUB_API_KEY"enabledbooleanoptionalfalse really means.advancedbooleanoptionaltrue when your plan includes Shield Advanced, which is what unlocks the blocklist, automatic 3-D Secure and custom rules.block_thresholdintegeroptionalreview_thresholdintegeroptionalblock_threshold minus one.auto_3ds_enabledbooleanoptionalblocklist_enabledbooleanoptional`enabled: false` does not turn fraud protection off
It sets aside your thresholds, blocklist and rules. Wajub's own platform-wide thresholds still apply to every payment. There is no way to accept a payment the platform refuses.
Changing thresholds
Send only what you want to change; anything you leave out keeps its current value.
curl -X PUT https://api.wajub.com/shield/settings \
-H "Authorization: $WAJUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "enabled": true, "block_threshold": 70, "review_threshold": 45 }'Two rules are enforced, and both bend your value rather than rejecting it.
A block_threshold outside 40 to 100 is a 422. Inside that range, it is capped at the
platform's own ceiling: you may be stricter than Wajub, never laxer. A review_threshold outside
10 to 99 is also a 422, and inside the range it is pulled below block_threshold so the review
band is never empty.
Read back what you wrote
The PUT returns the settings as they were actually stored, after capping. Send 95 on an
account whose platform ceiling is 80 and the response says 80. Trust the response, not your
request.
Blocklist
The blocklist refuses a payment outright, before scoring. Five kinds of value can be blocked:
typestringrequiredemail, phone, ip, country, card_bin.valuestringrequiredreasonstringoptionalcurl https://api.wajub.com/shield/blocklist \
-H "Authorization: $WAJUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "phone",
"value": "+237670000000",
"reason": "Three chargebacks in September"
}'Every write returns the whole list back, so you never need a second call to refresh your view:
Blocking the same type and value twice updates the existing entry's reason rather than
creating a duplicate, so re-running your import is safe. DELETE /shield/blocklist/{id} removes
one and returns the remaining list.
The blocklist needs Shield Advanced
blocklist_enabled is forced to false while your plan does not include Shield Advanced, and
the entries are then ignored no matter what you stored. GET /shield/settings is the place to
check: read advanced before you rely on the list.
Statistics
GET /shield/stats covers the current calendar month, live traffic only.
blocked_this_monthintegeroptionalreview_this_monthintegeroptionalopen_disputesintegeroptionaltotal_transactionsintegeroptionalblocklist_entriesintegeroptionalblocklist_enabled is false.block_ratenumberoptionalWatch the block rate, not the count
A rising blocked_this_month on rising traffic is normal. A rising block_rate is the signal:
either an attack, or a threshold set too low and now refusing real customers. Compare it with
review_this_month before you move a threshold.