Skip to content
Wajub
Loading keys…

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.

MethodEndpointWhat it does
GET/shield/settingsRead your thresholds and switches
PUT/shield/settingsChange them
GET/shield/statsBlocked, reviewed and disputed this month
GET/shield/blocklistList your blocked values
POST/shield/blocklistBlock a value
DELETE/shield/blocklist/{id}Unblock it

Settings

GEThttps://api.wajub.com/shield/settings
curl https://api.wajub.com/shield/settings \
-H "Authorization: $WAJUB_API_KEY"
Response · 200 OK
{
"code": 200,
"status": "OK",
"settings": {
"enabled": true,
"advanced": false,
"block_threshold": 75,
"review_threshold": 45,
"auto_3ds_enabled": false,
"blocklist_enabled": false,
"sanctions_near_match_action": "review"
}
}
enabledbooleanoptional
Whether your own thresholds, blocklist and rules apply. See the note below on what false really means.
advancedbooleanoptional
Read-only. true when your plan includes Shield Advanced, which is what unlocks the blocklist, automatic 3-D Secure and custom rules.
block_thresholdintegeroptional
A payment scoring at or above this is refused. Between 40 and the platform ceiling.
review_thresholdintegeroptional
A payment scoring at or above this is queued for review. Between 10 and block_threshold minus one.
auto_3ds_enabledbooleanoptional
Challenge a card payment that lands in your review band with 3-D Secure, where the card provider supports it. A payment over your block threshold is still refused. Requires Shield Advanced.
blocklist_enabledbooleanoptional
Whether your blocklist is consulted. Requires Shield Advanced.
sanctions_near_match_actionstringoptional
What happens to a payer whose name is close to a sanctions listing without being it: review (default: the payment is sent to your review queue) or block (it is refused). On every plan, and whether or not enabled is true. An exact match is always refused.

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 a value above the platform ceiling and the response shows the capped value. Trust the response, not your request.

Blocklist

The blocklist refuses a payment outright, before scoring. Five kinds of value can be blocked:

typestringrequired
One of email, phone, ip, country, card_bin.
valuestringrequired
The value to block, checked against its type and stored in one form: an email lower-cased, a phone as + and 6 to 15 digits, one IPv4 or IPv6 address (no range), an ISO 3166-1 alpha-2 country code upper-cased, a card BIN of 6 to 8 digits. Anything else answers 422.
reasonstringoptional
A note for your own team, up to 500 characters. Never shown to the customer.
curl 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:

Response · 201 Created
{
"code": 201,
"status": "Created",
"message": "Entry added to blocklist.",
"blocklist": [
{
"id": "01JXXXXXXXXXXXXXXXXXXXXXXX",
"type": "phone",
"value": "+237670000000",
"reason": "Three chargebacks in September",
"created_at": "2026-09-14T09:12:44.000000Z",
"updated_at": "2026-09-14T09:12:44.000000Z"
}
]
}

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, and +237 670 00 00 00 and 237670000000 are the same entry. DELETE /shield/blocklist/{id} removes one and returns the remaining list; an id that is not one of your entries answers 404.

A card_bin entry blocks cards whose first 6 to 8 digits match: see the blocklist.

Statistics

GET /shield/stats covers the current calendar month, live traffic only.

Response · 200 OK
{
"code": 200,
"status": "OK",
"stats": {
"blocked_this_month": 14,
"review_this_month": 39,
"open_disputes": 2,
"total_transactions": 4127,
"blocklist_entries": 6,
"block_rate": 0.34
}
}
blocked_this_monthintegeroptional
Payment attempts Shield refused since the 1st.
review_this_monthintegeroptional
Payments collected and sent to your review queue since the 1st, once each.
open_disputesintegeroptional
Live disputes not settled yet, open or under_review, all periods.
total_transactionsintegeroptional
Live payments created since the 1st.
blocklist_entriesintegeroptional
Entries in your blocklist, or 0 while blocklist_enabled is false.
block_ratenumberoptional
Blocked as a percentage of total, rounded to two decimals.

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

Related pages

What did you think of this content?