Payment Gateway

Card acceptance for merchants

Design the gateway that sits between merchants and card acquirers: a merchant API, card collection that keeps card numbers out of merchant systems, 3-D Secure, safe calls to acquirers, and signed webhooks.

Overview

A payment gateway is the part of a card payment that a merchant talks to. The merchant's website or app sends it an amount and a card; the gateway turns that into an authorization request to an acquirer (the merchant's bank for card payments), which passes it over a card network to the issuer (the customer's bank). The answer comes back the same way in a second or two.

The Payment System topic covers what happens to the money afterwards: the ledger, settlement and reconciliation. This page is about the edge. How does a card number get from a customer's browser to the acquirer without passing through the merchant's servers? Where does 3-D Secure, the customer-authentication step, fit? What does the gateway do when an acquirer does not answer, given that the issuer may already have put a hold on the card? And how do merchants learn, reliably and securely, what happened?

Questions to ask first

Who calls us? — Merchants' servers with a secret key; their customers' browsers and apps with a publishable key
Volume? — 20 million payments a day, peak 5 times the average
Do we connect to card networks directly? — No: through several acquirers, each over its own link
Must merchants avoid handling card numbers? — Yes; card entry happens in fields we host
Customer authentication? — 3-D Secure when a regulation, the issuer or our risk rules ask for it
How do merchants learn outcomes? — The API response, plus signed webhooks for anything that finishes later

What you will be able to do

Name the parties in a card payment and say which messages the gateway sends to each.
Design card collection so that merchant servers never see a card number, and say what that does to PCI DSS scope.
Place 3-D Secure in the payment flow and explain frictionless and challenge flows.
Handle an acquirer timeout with a reversal instead of a guess, and route around a failing acquirer safely.
Sign and deliver webhooks that merchants can verify and deduplicate.

Key concepts

Four-party card model
Acquirer and issuer
Payment intents
Hosted card fields
Tokenization vault
PCI DSS scope
3-D Secure 2
Timeout reversals
Acquirer routing
Signed webhooks

Functional requirements

Create a payment intent for an amount and currency; confirm it with a card token
Authorize now and capture later, or capture at once; cancel an uncaptured authorization
Refund all or part of a captured payment
Collect card details in fields hosted by the gateway and return a token
Run 3-D Secure when required and resume the payment afterwards
Send signed webhooks for every payment event

Non-functional requirements

Confirm answers within 3 seconds at p99 when no customer challenge is needed (a target we chose; most of it is the acquirer and issuer)
A lost acquirer reply never leaves a customer with an unexplained hold or a double charge
Card numbers exist only in the vault and the acquirer adapters
99.99% availability for creating and confirming payments (a target we chose)
Webhooks are delivered at least once, signed, for up to about three days

Interview questions

Walk me through what happens when a customer clicks Pay.
The acquirer timed out. What do you do?
How do you keep card numbers out of merchants' systems, and out of most of yours?
Explain 3-D Secure in one minute.
Why 422 for a decline and not 402?
How do merchants know a webhook really came from you?
How does the gateway choose between acquirers, and what happens when one fails?
How is this different from designing the payment system behind it?