Quickstart
Turn Shield on, set thresholds that hold, and work the review queue.
Shield is already scoring your live payments at the platform thresholds. Turning it on is how you replace those with your own and unlock everything that acts on a score rather than just reporting it.
Five steps, all of them in live mode.
There is nothing to try first
Sandbox payments are not scored at all, and the Shield endpoints refuse a test key. Whatever you set here takes effect on real customers on the next payment. This is why the thresholds have floors and why the sensible order is to activate, watch, then tighten.
1. Turn it on
In the Dashboard, Shield shows an activation screen until you activate it. Activating sets nothing else: you start on 80 and 50, the same numbers that were already applying.
From the API it is one call.
curl -X PUT https://api.wajub.com/shield/settings \
-H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
-H "Content-Type: application/json" \
-d '{ "enabled": true }'The response returns the settings as they now stand, including an advanced flag telling you
whether rules, lists and automatic 3D Secure are available to you.
2. Set thresholds that are actually accepted
Both thresholds are bounded, and a value outside the bounds is either refused or quietly brought back inside. This is the part that surprises people.
| Field | Accepted | What happens outside it |
|---|---|---|
block_threshold | 40 to 100 | Below 40 or above 100, the request is rejected |
block_threshold | Never above 80 | A value above the platform threshold is brought down to 80 |
review_threshold | 10 to 99 | Below 10 or above 99, the request is rejected |
review_threshold | Always below block | A value at or above your block threshold is brought down to one under it |
So a request asking for a block threshold of 90 succeeds, and leaves you on 80. Read the
settings back after writing them rather than assuming what you sent is what applies.
curl -X PUT https://api.wajub.com/shield/settings \
-H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"block_threshold": 70,
"review_threshold": 45,
"auto_3ds_enabled": true,
"blocklist_enabled": true
}'auto_3ds_enabled and blocklist_enabled are stored on any plan and only take effect while you
hold Shield Advanced. A stored true on a plan without it reads back as false.
Why 40 is the floor
A legitimate first-time payer scores 20 to 30 on nothing but first-seen signals: a phone the platform has never met, an email it has never met, no browser data on a server-to-server call. A block threshold under 40 would refuse ordinary new customers, and at 0 it would refuse everyone. Start at the default, look at what got flagged, and come down from there.
3. Read what it decided
Not from the API. The payment response carries no score, and no webhook fires on a Shield decision. Everything is in the Dashboard.
| Where | What it holds |
|---|---|
| Shield, overview | This month's blocked, flagged and reviewed counts, and the split between them |
| Shield, reviews | The queue of flagged payments waiting on you |
| The payment itself | Its score and the flag codes that produced it |
The overview counters are cached for five minutes. The queue is not.
4. Work the review queue
The queue holds every flagged payment from the last 90 days that you have not yet closed, newest first, twenty to a page. Each row carries the score, the flag codes, the customer and what a full refund would return.
Closing a row takes one of four decisions.
| Decision | What it does |
|---|---|
| Approve | Marks it reviewed. Nothing else changes |
| Allow this customer | Also writes an allow rule on their email and phone, so their next payments bypass the score |
| Block this customer | Also blocklists their email and phone. This payment stays collected |
| Block and refund | The same, plus a full refund of this payment |
Approve is available on every plan. The other three are Shield Advanced, because each of them writes to a list or a rule.
Blocking alone leaves you holding the money
A flagged payment was collected. Blocking the customer only protects you from their next attempt. If you have decided a payment is fraud, block and refund is the decision that acts on the one in front of you, and it goes through the ordinary refund flow so you can follow it on the payment page.
5. Know what a block looks like
A blocked payment never reaches a provider. The call returns immediately, the transaction stays
pending, and your integration gets a message with a reference.
Because the transaction is untouched, the payer can be offered another attempt on the same payment. It will be scored again from scratch, and unless something about it changed it will be blocked again.
If you run your own checkout
Wajub's hosted pages send a small block of browser data with every charge. If you built your own
payment page, send the same block under data._client and Shield can tell a real browser from a
script.
Every field is optional and each one is used differently. The timezone and the language are
compared against the country of the payer's IP. The screen resolution catches headless browsers,
which report 0x0. The fingerprint is what lets Shield recognise a device across payments, which
is how device velocity and device reputation work at all.
Sending signals can raise a score as well as lower it
A server-to-server call with no _client block picks up three points and nothing else. Sending
the block removes those three, and turns on the consistency checks: a payer behind a VPN whose
browser timezone disagrees with their IP country is worth thirty-five. That is the correct
answer, not a regression, but it is worth knowing before you compare scores from before and
after.
Related pages
- ShieldWhere the score sits in a payment, and what the plans differ on.
- Shield RulesCustom rules, the blocklist and the allowlist, and which one wins.
- Risk ScoringEvery signal, what it is worth, and why a first payment starts above zero.
- DisputesWhat a lost dispute does to the reputation Shield reads next time.