Building a Payment Address Book for a Fintech Product
Every payments product eventually needs an address book — a place where users keep the people they pay. It looks trivial until you build it. A payment address book is not a contact list with phone numbers; it is a trust-bearing data structure where each entry can route real money. Here is how to build one that stays correct as it grows.
Model the alias, not the account
The first design decision is what an entry points at. Store aliases — a handle, a phone, an email — rather than raw account numbers wherever possible. Aliases are stable across a person changing banks, they are safer to keep because they are less sensitive than account details, and they let the routing engine choose the rail at send time.
- Prefer a resolvable alias over a stored raw account.
- Capture the rail each alias implies for later routing.
- Record verification status alongside every entry.
Verification is a first-class field
An address-book entry should carry whether its destination is verified and, ideally, the resolved recipient name. Showing that name when a user pays a saved contact is the cheapest fraud defense you can build — it lets the sender confirm they are paying who they think. Never treat "saved" as equivalent to "trusted"; a saved bad address is still a bad address.
| Field | Why it matters |
|---|---|
| Alias | The resolvable identity |
| Rail hint | Guides routing |
| Verified | Gates payability |
| Resolved name | Powers confirmation of payee |
Deduplication and identity
Users will save the same person twice — once by phone, once by handle. A good address book detects that these resolve to the same directory identity and merges them, or at least flags the overlap. Deduplication keeps the list clean and prevents the confusion of two entries that pay the same person by different rails.
Privacy by default
An address book is a map of who a user pays, which is sensitive relationship data. Store the minimum needed, encrypt at rest, and be careful about what you expose in search and autocomplete. Resolving an alias should reveal only what the recipient has agreed to make public — typically a display name, not their full contact details.
Search that respects consent
Letting users find people by name or phone is convenient but risky. A directory search must respect the recipient's consent about being discoverable, and it should never turn into a way to enumerate the user base. Rate limits, exact-match requirements, and opt-in discoverability keep the feature helpful without becoming a scraping tool.
How it ties into KibiPay
In KibiPay, the address book is a personal view onto the shared directory: entries are aliases that resolve to directory identities, complete with verification status and resolved names. That means a saved contact is not a frozen account number but a live pointer that stays correct as people change banks or add wallets. For the addressing formats behind those entries, see addressing a payment, and for the trust layer, confirmation of payee.
Keeping entries fresh
An address book decays if you let it. Because entries point at aliases that resolve to live directory identities, they can be re-resolved periodically to catch a recipient who changed banks or whose alias was revoked. A stale saved contact is worse than no contact, because it carries false confidence into a payment. Re-checking verification status on a schedule, and re-confirming the resolved name before a payment to a long-dormant contact, keeps the list honest. The payoff is that a name a user saved a year ago still pays the right person today — not because the account behind it never changed, but because the alias quietly absorbed the change on their behalf. That is the whole reason to store aliases rather than raw account numbers in the first place.
Build the address book as a trust structure, not a contact list, and paying saved people becomes both effortless and safe.