# Shield

> What Shield scores, what it does with the score, and what it never does.

Shield gives every live payment a risk score from 0 to 100: above one of your thresholds the payment
is refused outright, above the other it goes through and lands in a queue for you to look at. It
runs whether or not you have configured it; what you configure is how strict it is and what it may
do beyond scoring.

## Where it sits in a payment

A payment is two calls. Shield runs when you charge the payment, in the second one, before any
provider is contacted.

| Step                  | What happens                                                         |
| --------------------- | -------------------------------------------------------------------- |
| `POST /payments`      | The transaction is created. Nothing is scored                        |
| `POST /payments/{id}` | Your limits are checked, then Shield scores                          |
| A block               | The call returns `403` before a single provider is called            |
| Everything else       | The payment continues into [orchestration](https://docs.wajub.com/orchestration) as normal |

The order matters: a payment your own limits refuse is not scored, and does not show up in your
review queue.

## Three outcomes, and only one of them stops anything

| Score against your thresholds          | Decision | What the payer sees                           |
| -------------------------------------- | -------- | --------------------------------------------- |
| Below the review threshold             | Allowed  | A normal payment                              |
| Review threshold or above, below block | Flagged  | A normal payment                              |
| Block threshold or above               | Blocked  | A `403`, with a reference to quote to support |

> [!CAUTION]
> **A flagged payment is not held**
>
> `review` means money came in and you should look at it. The payment is charged, credited and
> settled exactly like any other, and only enters your review queue once it has actually been
> collected. Shield has no mechanism that holds funds pending a decision, so if a review is a
> reason for you not to ship, that logic belongs in your own system.

A blocked attempt goes to the same queue straight away, with nothing collected. If it was a mistake,
close it with **Always allow customer** and their next attempt goes through, whatever your plan.

## Two layers, and only one is yours

Wajub screens its own platform, and your settings sit on top of that.

**The platform layer** applies Wajub's own block and review thresholds to every account. It is not
something you switch off, and it is what applies before you have configured anything. Read the
thresholds that apply to you from `GET /shield/settings` rather than writing a number into code.

**Your layer** replaces those thresholds with your own once you activate Shield. You can be
stricter than Wajub, never laxer: a block threshold above the platform's is brought back down to
it. Turning Shield off again does not leave you unprotected, it just hands the decision back to the
platform thresholds.

Everything else Shield can do, the custom rules, the lists, the automatic 3D Secure, only exists
while your own configuration is on.

> [!WARNING]
> **Sandbox is never enforced**
>
> Shield enforces nothing in sandbox: no refusal, no queue entry. Sandbox scoring never affects
> live payers, and the Shield endpoints refuse a test key. You cannot rehearse a fraud decision,
> which is the reason the thresholds have floors: they are the guard rail you do not get to test
> against.

## What each plan actually gets

Baseline screening is on every plan. What you pay for is the ability to act on it.

|                                     | Shield | Shield Advanced |
| ----------------------------------- | ------ | --------------- |
| Every live payment scored           | Yes    | Yes             |
| Your own thresholds                 | Yes    | Yes             |
| Review queue                        | Yes    | Yes             |
| Closing a review as approved        | Yes    | Yes             |
| Allowing a customer from a review   | Yes    | Yes             |
| Custom rules                        | No     | Yes             |
| Blocklist                           | No     | Yes             |
| Automatic 3D Secure on cards        | No     | Yes             |
| Blocking or refunding from a review | No     | Yes             |

Shield Advanced is included on **Scale** and **Enterprise**, and available as a paid add-on on the
lower plans. Rules and list entries left behind by a downgrade are kept and stop applying, so they
come back as they were if you subscribe again. The customers you allowed from a review are the
exception: they stay allowed on every plan.

## What your integration can see

Nothing. There is no `shield` object in the payment response, no risk score on the payment, and no
webhook that fires on a Shield decision. The one thing your code sees is the refusal, which carries
`error_code: shield_blocked` and the support reference in `block_reference`.

```json title="Response · 403 Forbidden"
{
  "code": 403,
  "status": "Forbidden",
  "error_code": "shield_blocked",
  "message": "Payment blocked: transaction risk score too high. Please contact support and reference BLK-K3M9XQ2P.",
  "block_reference": "BLK-K3M9XQ2P"
}
```

The transaction is left at `pending` and untouched. Branch on `error_code`, not on the message. The
`BLK-` reference in `block_reference` identifies that exact decision, so a payer who insists they
are legitimate can quote it and you can find them in the Dashboard. The attempt sits in your review
queue, where **Always allow customer** releases them for their next try.

## The endpoints

Shield is configured from the Dashboard under **Shield**, and the same settings are reachable from
the API with your private key.

| Method                | Endpoint                           | Used for                                                    |
| --------------------- | ---------------------------------- | ----------------------------------------------------------- |
| `GET` `PUT`           | [`/shield/settings`](https://docs.wajub.com/api/shield)  | The on switch, the thresholds, the two Advanced toggles     |
| `GET`                 | [`/shield/stats`](https://docs.wajub.com/api/shield)     | Blocked, reviewed and disputed counts for the current month |
| `GET` `POST` `DELETE` | [`/shield/blocklist`](https://docs.wajub.com/api/shield) | The blocklist                                               |

All of them are live only and require a secret key. There is no endpoint for the custom rules or the
review queue: those are Dashboard surfaces.

- [Quickstart](https://docs.wajub.com/risk/shield/quickstart): Turn it on, set thresholds that hold, and work the queue.
- [Shield Rules](https://docs.wajub.com/risk/shield/rules): Custom rules, the blocklist and the allowlist, and which one wins.
- [Risk Scoring](https://docs.wajub.com/risk/shield/risk-scoring): What the score means, and the levers that are yours.
- [Identity verification](https://docs.wajub.com/risk/identity): Check a payout destination before money leaves: an IBAN, a number, a name.
- [Payments](https://docs.wajub.com/payments): The two-call flow Shield runs inside.
