Who sees the card number?
A small online school is about to sell its first course, twelve weeks of data engineering for €240, paid by card. The developers' first question is whether their server will ever hold a card number, because anything that stores, processes or transmits card data falls under PCI DSS, the card industry's security standard, with its controls and its audits.
The usual answer is that it never arrives. The school integrates a payment gateway (Stripe, PayPal) and lets the provider collect the card in the browser, through its hosted fields or its hosted checkout page. The provider swaps the card for a token, a reference that means something only to the provider, so the school's servers only ever see a token, never the card details. That can shrink the school's PCI scope a lot, by how much depends on the integration, but it does not remove the school's responsibilities: a script injected into that page could swap the fields for a look-alike form that sends the card elsewhere.
Paid, declined, or not yet
With the token, the school's Billing Service asks the provider to charge €240, sent as amount: 24000 in cents with currency: "eur". The developers expected paid or declined. What comes back is a payment with a status that is often neither: a payment moves through states, and the first response catches it wherever it is. The names differ between providers; the path is much the same:
- Requires action. The student's bank wants them to confirm the payment in its app or with a code, a step called 3-D Secure that many European card payments trigger. The provider's response to the school comes back now, before the student has confirmed.
- Authorized. The bank has put a hold on €240 of the student's available funds. No money has moved.
- Captured. The school claims the held money. A shop shipping goods may capture later, at dispatch; the school gives access at once, so it captures with the authorization.
- Succeeded or failed. Where the charge ends. A card payment usually gets there in seconds; a bank debit can sit in processing for days.
Two related operations, each with its own status, can come much later: a refund, money sent back, and a dispute, where the student contests the charge with their bank. A dispute can become a chargeback, and the provider may take the disputed amount from the school as soon as the dispute opens, returning it if the school wins; the school can submit evidence, under the card network's and the provider's rules. A payment that succeeded in March can be lost in May.
Sometimes there is no response at all: the call times out, and the Billing Service cannot tell whether a charge was made or learn its payment id. A retry or a second press of Pay can then charge twice for one course. The defence is an idempotency key on charge creation, derived from the order and passed to the provider on every attempt. To find the payment, the school retries with that key or, where the provider allows it, looks the charge up by an order reference it sent along; Idempotency Key explains what the provider does with a repeated key.
Which answer to believe
Requires action is where the school's first checkout went wrong. The browser took the student through the bank's confirmation and back to a thank-you page, and that page told the server the payment was done. That broke in two ways. Students who closed the tab on the bank's screen never came back, so courses they had paid for stayed unpaid in the school's records. And the server trusted a message from the browser, which anyone can send with a few lines of script, so a student could enrol without paying.
The fix is to take the result from the provider, server to server. When a payment changes state, the provider sends a webhook, an HTTP request to an endpoint the school registered, saying which payment changed and how. It arrives asynchronously, often after the request that created the charge has returned, because authorization can complete after that request returns. The school's Webhook Ingress verifies the request's signature, the Billing Service finds the payment by the provider's payment id and, if the event reports a succeeded charge for the order's amount, marks it paid, and only then does the student get the course. The redirect back from the bank still decides which page the student sees; it no longer decides whether they paid.
The card travels from the browser to the provider, and the school's servers see only a token. The paid state arrives by webhook, and a daily job checks the school's payments against the provider's.
Webhooks can also arrive twice or out of order, so the Billing Service ignores an event id it has already applied and only applies a change the payment can make from its current state, so a late processing event never pulls a succeeded payment back. Receiving them safely, signatures included, is what Webhooks & third-party integration teaches.
When the webhook is late, or never comes
Most webhooks land within seconds. Some do not: the provider is behind, or the school's endpoint was down longer than the provider kept retrying, which can be hours or days. The payment then sits as pending at the school while the provider may already hold it as succeeded or failed. Two rules keep that honest.
Do not decide on silence. A missing webhook does not mean the payment failed, and cancelling the order can leave a student who paid without the course; the page says the payment is being confirmed and an email will follow. And do not wait forever. When a payment has been pending longer than usual, say fifteen minutes, the Billing Service asks the provider's API for that payment's current status and applies the answer through the same code a webhook goes through, so the webhook for that same change, when it turns up, changes nothing.
Your records against the provider's
The status check only covers payments the school knows are pending. It misses a webhook applied to the wrong order, a refund issued from the provider's dashboard, a dispute event that failed halfway. For those, a daily reconciliation job pulls the provider's payments, refunds and disputes that changed since its last completed run, matches each to the school's row by payment id, also checks the school's own payments not yet reconciled, since a payment the provider never had is not in its list, and reports three kinds of mismatch:
- Succeeded at the provider, pending or missing at the school: an event was lost. Apply it, then find out how.
- Paid at the school, failed or absent at the provider: a bug, or a status from somewhere it should not come from. A student may have a course nobody paid for.
- Present on both sides with a different amount, or with a refund or dispute only the provider has: an operation the school's records missed or recorded wrong.
Payouts, which arrive in batches net of fees, are checked against the payments, refunds and fees each batch bundles, and keeping every euro traceable in your own books is the double-entry ledger in Worked design: a digital wallet. Two neighbours stay outside this article: refunding when the enrolment step after a successful payment fails, a compensation that Saga handles, and charging each month for usage, in Usage metering & billing pipelines.
Where the paid state comes from
The Payment Processing System Challenge asks for this design, from PCI constraints to refunds, chargebacks and provider webhooks. Of its many requirements, three are easy to drop: confirm the charge outcome via the provider's webhook (dedupe by event id, match by payment id); send the idempotency key on charge creation; never trust the client's response. Before you submit, find the edge on your Grid that writes paid into the payments store. If anything but the provider's answer can reach it, the student who forged the browser's message still gets the course; if nothing reaches it when the webhook is missing, the one who closed the tab still does not.