Engineering · By the Paypled team ·

How to implement anti-phishing codes in a fintech product.

A practical design for user-chosen anti-phishing codes: where the code must appear, how to store and rotate it, the threat model it covers and the one it does not, how to roll it out, and how to measure whether it works. Written from building Paypled Shield.

Several large exchanges and banks print a customer-chosen code on their messages, and the idea is simple enough to describe in a sentence. Building it so that it actually reduces successful phishing is less simple. This is the design Paypled uses for Shield codes, written for engineering and product teams at other financial firms who want to do the same. Copy it freely.

The attack you are defending against

The common fintech phishing chain has three links: a message that looks official, a page that looks like your sign-in, and a session that moves money. Most controls sit on the third link (2FA, allow-lists, approvals). An anti-phishing code attacks the first link, which is where the victim’s judgement is weakest, because logos, fonts and sender names are trivially copied.

The control works because the attacker cannot reproduce something they have never seen. It fails the moment the code becomes visible to them, which shapes every decision below.

Let the user choose it

An assigned code (a random string) is secure but forgettable; users stop checking for it within weeks. A user-chosen phrase is remembered and recognised at a glance. Require between 4 and 24 characters, allow spaces and punctuation, and reject the obvious: the user’s name, the company name, the product name, and anything that appears in their public profile. Show a live preview of an official message header with the code in place so the user learns where to look before the first real message arrives.

Treat it as a secret with an unusual property

The code has to be rendered in plaintext into outbound messages, so it cannot be stored as a one-way hash like a password. Store it encrypted at rest with the key held outside the application database, decrypt it only in the message-rendering path, and log every read with the reason. Support staff should not be able to view it; they do not need to, because the user, not support, is the one who checks it.

Rotation is a one-click action for the user and takes effect immediately for every message after that moment. Prompt a rotation after any login alert the user reports as unfamiliar.

Never ask for it

The most important rule in the whole design: the provider must never ask the user to enter, confirm or repeat the code, anywhere, ever. The moment a legitimate flow asks for the code, attackers build a fake version of that flow and harvest it. Write this into support training, into the help centre, and into the message template itself (‘we will never ask for this code’). Paypled’s help pages say it on every relevant article.

Know what it does not cover

An anti-phishing code proves a message is genuine. It does nothing for a user who reaches a fake sign-in page through a search ad, a typo-squatted domain, or a link in a chat. It does nothing for a compromised device. Ship it alongside an authenticator code on new devices, login alerts, origin-bound sessions, and withdrawal allow-lists with a cool-off period. Each control closes a different link in the chain; none closes all three.

Roll it out so that people actually set it

Prompt at onboarding with the preview, and again on the first sign-in from a new device. Make the control default-on in the sense that the settings page shows it as the first item and the prompt recurs until a code is set. Explain in one sentence why it exists; users adopt controls they understand. Do not gate it behind a security tier or a paid plan.

Measure it

Two numbers matter. The share of active accounts with a code set, which should pass 80% within a quarter if the prompts work. And the rate at which users report messages as suspicious, which should rise after launch (users now have a test to apply) and then stabilise. Track reported messages that carried a valid code separately; a non-zero rate there means a template is placing the code somewhere users do not see it.

Checklist

User-chosen phrase, 4–24 characters, with a live preview. Printed in the header of every email, SMS, push and signed-in screen. Encrypted at rest, decrypted only to render, every read logged, invisible to support. One-click rotation, immediate effect. Never requested by any flow, and the templates say so. Paired with 2FA, login alerts, origin-bound sessions and allow-lists. Adoption and report rates on a dashboard.

Takeaways

  • The code works because the attacker has never seen it; every design choice protects that property.
  • Same position, every message, or the control trains users to ignore its absence.
  • Never ask the user for the code anywhere. That rule is the whole product.
  • It covers the message, not the fake page or the stolen device; pair it with the rest of the stack.

Related