Rules

Custom rules, the blocklist and the allowlist, and which one wins.

The score decides on its own most of the time. On top of it sit three deterministic overrides, for the cases where you know something the signals cannot see: a customer you trust, a number you have seen defraud you, a bracket of payments you want challenged whatever they score.

All three are Shield Advanced, and all three only run while your own Shield configuration is on.

The order a decision is settled in

Nothing here replaces the score, everything here acts after it. Reading the sequence once explains every outcome on this page.

Step	What happens
1	The signals are collected and the score is computed
2	A blocklist or sanctions match forces the score to 100
3	The score is compared against your thresholds, giving allow, review or block
4	Your rules are walked in order, and the first matching live rule decides
5	That rule's action is applied on top of the score decision

Step 4 is where "first match wins" applies, and only there. Step 2 is why an allow rule cannot rescue a blocklisted customer.

What a rule is made of

namestringrequired

Up to 120 characters. It is what appears on the reasons of a payment this rule decided, so name it after what it catches.

conditionsarrayrequired

One to ten conditions, each a field, an operator and a value. Every one of them must hold: there is no OR, and an empty list matches nothing.

actionenumrequired

block, review, challenge_3ds or allow. See the table below for what each does.

modeenumrequireddefault : live

live rules decide. test rules are evaluated and counted, and never change anything.

priorityintegeroptionaldefault : ten above your highest

Lower runs first. Rules sharing a priority are walked newest first, so the most recent one wins a tie.

enabledbooleanoptionaldefault : true

A disabled rule is not loaded and does not count hits.

Every rule also carries a hit counter and the time it last matched, both updated on every payment it hits, test rules included. That counter is the honest measure of whether a rule is doing anything.

The eight fields

The builder is a closed catalogue. There is no expression language and no access to anything not on this list, including the risk score itself.

Field	Type	Operators
Transaction amount	number	`gt` `gte` `lt` `lte` `eq`
Currency	list	`in` `not.in`
Payment method	list	`in` `not.in`
Customer email	text	`eq` `contains` `matches`
Customer phone	list	`in` `not.in`
IP country	list	`in` `not.in`
First transaction from this customer	boolean	`is_true` `is_false`
Matches an entry in the blocklist	boolean	`is_true`

A few behaviours are worth knowing before you write anything.

The amount is in major units, the same units as the payment, so 50000 is fifty thousand XAF.

Payment method is the channel's type, not its slug: card, mobile_money, wallet, bank, crypto. It is the one place in the product where a product-level word is the right answer.

Phone numbers are compared on their digits alone, so +237 6 70 00 00 00 and 237670000000 are the same value. Email comparison is case-insensitive, and so is matches, where * is the only wildcard and it is anchored at both ends.

First transaction means this customer has never had a live payment succeed with you before. A payment with no customer attached counts as a first.

The four actions

What an action does depends on what the score already decided, which is the part that catches people out.

Action	Effect
`block`	The payment is refused, whatever it scored
`review`	The payment is flagged, unless the score already blocked it. A review never rescues a block
`challenge_3ds`	3D Secure is requested on a card payment. The allow, review or block decision is unchanged
`allow`	The score decision is dropped and the payment goes through, except against a blocklist or sanctions match

Allow is the only action that can undo a decision

And it deliberately cannot undo all of them. A payment matching your blocklist, or a sanctions watchlist, keeps its refusal no matter how many allow rules point at it. An explicit deny always wins over an explicit allow, which is the only arrangement that makes a blocklist worth anything.

challenge_3ds only reaches the issuer through providers whose driver can ask for it. Everywhere else the provider applies its own 3D Secure policy and the rule changes nothing.

Test mode

A rule in test mode is evaluated on every live payment, counts its hits, and is recorded on the payment as having matched, without ever deciding anything. It is the closest thing Shield has to a dry run, and it is the only one: there is still no sandbox.

The way to use it is to write the rule you are considering in test mode, leave it for a week, and read its hit counter. A rule that would have blocked four hundred payments is a rule you want to know about before it is live.

The blocklist

An entry on the blocklist forces the score to 100, which means a refusal on any threshold you could possibly set. It is the bluntest thing in Shield and the only one that needs no rule.

typeenumrequired

One of email, phone, ip, country or card_bin.

valuestringrequired

Up to 255 characters. Emails match case-insensitively, phones on their digits alone, IPs exactly, countries on the two-letter code, and a card BIN against the first six digits of the card, so an entry longer than six digits never matches.

reasonstringoptional

Up to 500 characters, for you. It is what the decision records as the reason.

A country entry is matched against the country of the payer's IP address, not their phone number and not the currency. Blocking NG stops every payment made from a Nigerian IP, including your own Nigerian customers paying while they are there.

The list only applies while it is switched on

A blocklist entry does nothing unless blocklist_enabled is true on your settings. Adding an entry from the Dashboard switches it on for you, adding one through the API does not.

The blocklist is the one part of this page with an API.

POSThttps://api.wajub.com/shield/blocklist

The type and the value are required, the reason is yours to fill in and is what the decision records when the entry matches.

Block a number

curl https://api.wajub.com/shield/blocklist \
  -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "value": "+237690000000",
    "reason": "confirmed fraud, chargeback March"
  }'

The full list comes back on every write, so you never need a second call to see the result.

The allowlist

There is no allowlist table. An allowed customer is an ordinary rule with the allow action, and the Dashboard writes one for you when you close a review with allow this customer: one rule per identifier, at priority 0 so it runs before everything else, matching the email exactly or the phone digit for digit.

You can write the same thing by hand, and you should keep it just as narrow. An allow rule on contains rather than eq would let x-attacker@mail.com through along with attacker@mail.com.

What a rule cannot do

It cannot see the score. There is no risk score field in the catalogue, so you cannot write "block anything over 60 that is also a first payment". Thresholds are the only lever on the score.

It cannot combine conditions with OR. Every condition in a rule must hold. Two alternatives are two rules.

It cannot read your metadata. Nothing you send on the payment, beyond the amount, the currency, the channel and the customer's email and phone, is visible to a rule.

It cannot lower a payment out of a blocklist. That is step 2 above, and it is settled before rules are read at all.