Risk rules and reviews

What is checked

When somebody presses the pay button, and before anything is sent to the bank, we build a small set of facts about the attempt and run your rules against them. The facts are:

The velocity counts are of attempts that were evaluated — every press of the pay button, whether or not a card was ever entered. That is the number that matters: card testing is a hundred registrations and two successes.

What is not checked

No card data. The card number is typed on a page hosted by the bank, so there is no card number in this system to test a rule against — not the number, not the BIN, not the issuing country. If a rule about the issuing country would be useful to you, tell us; it is not something we can offer today and we would rather say so than publish an attribute that silently never matches.

No device fingerprinting. We do not load a script into your checkout, we do not build a device graph, and we do not track a payer between merchants. The IP address and the email address are what we have.

No machine-learned score. Every decision is a rule you can read, written by you or published by us on this page. A payment that was refused was refused by a named rule, and the record says which.

Our defaults

Four rules apply to every business on Secure Processing, in test and live alike. They are evaluated before yours, they are listed in your dashboard, and you cannot edit or switch them off — an entry on your allow list is what lets a payment past one.

The only one that refuses a payment is the first, and it catches a pattern that is never a customer. The other three ask a person to look at money that has already arrived.

Precisely, for the first: the email is the payment’s receipt_email; failing that, the checkout session’s customer_email on a checkout page, or the customer record’s email when you charge a saved card with confirm: true. It is never anything typed on the bank’s page, which we never see. An attempt is one assessed payment: a press of Pay by card on a checkout page, payment link or invoice, card entered or not, or a saved-card charge — and every assessment is recorded, refused ones included. A payment is allowed only while there are fewer than five recorded attempts from that email in the last hour, per business and per mode. So the sixth in an hour is refused, and so is every press after it: each refusal is itself an attempt, so pressing again keeps the count at five or more. Stop, and it clears an hour after the attempts that filled it. A payment with no email has no email count and never trips it.

Writing a rule

A rule is a name, an action and a predicate. The predicate is an AND of one to eight conditions. There is no any and no nesting: an OR is two rules, which is also two rules you can switch off independently and two reasons on a review that say which one fired.

curl https://api.secureprocessing.app/v1/risk_rules \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Review large payments from a new address",
    "action": "review",
    "predicate": { "all": [
      { "attr": "amount_minor", "op": "gte", "value": 200000 },
      { "attr": "email_domain", "op": "not_in", "value": ["seascape.bz", "example.com"] }
    ] }
  }'

The operators, and what each one takes:

action is block or review. There is no allow action: an allow-rule with a predicate would need an ordering nobody can reason about, and letting a specific payer past is what the allow list is for.

Lists

A list entry is an exact value rather than a test, and it is checked before any rule runs. An allow hit ends the assessment there and the payment proceeds — it beats every rule, including ours. A block hit refuses the payment.

curl https://api.secureprocessing.app/v1/risk_lists \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"list": "block", "kind": "email_domain", "value": "mailinator.com", "note": "Three chargebacks in March"}'

The kinds are email, email_domain, ip and card_fingerprint. Values are stored lowercased and trimmed, and comparisons ignore case on both sides.

DELETE /v1/risk_lists/{id} really deletes, which is unusual in this API — everywhere else a delete is a disable. A list is a live control surface, and unblocking somebody has to actually unblock them. What the entry did is kept in the risk evaluations it decided, which cannot be edited.

Reviews

A review outcome does not hold the payment. The customer pays, the money lands in your balance, and a review opens for you to look at afterwards. Holding it would mean a card failing at a counter in front of the person who entered it, for a rule whose job is to notice a pattern rather than to be certain.

A review is opened only when the payment actually succeeds — an abandoned checkout never produces one — and there is exactly one per payment however many of our settlement paths reach it first.

There are two ways to close one, and both are final:

A refund made this way carries origin: "review", so you can tell it apart from one you decided on the payment’s own page.

When a payment is blocked

Nothing is sent to the bank. The payment intent moves to requires_payment_method with a last_payment_error, and payment_intent.payment_failed is emitted — the same event your handler already has a branch for. The API answers 402:

{
  "error": {
    "type": "card_error",
    "code": "payment_blocked",
    "decline_code": "blocked",
    "message": "This payment can't be completed. Please contact the business."
  }
}

It is payment_blocked rather than card_declined on purpose. No card was declined — none was even entered — and telling a payer their card failed sends them to try another one, which is precisely what somebody testing stolen cards is hoping to be told to do.

On the payment object

Every payment intent carries risk_outcome and, if a review was opened, review. You can filter the list with /v1/payment_intents?risk_outcome=review.

Events

A blocked payment does not emit an event of its own: it emits payment_intent.payment_failed, like every other payment that did not happen, and last_payment_error.code is what tells them apart.

Who can change what

Writing a rule, editing a list and approving a flagged payment need the owner or an admin role. Refunding one needs the same role as any other refund, which support has. The separation is deliberate: someone who can close one review should not also be able to quietly loosen the rule that opened it.