STEP 01THE FIRST SKETCH
WHAT WE ADD
WHY IT MATTERS
EXAMPLE SOFTWARE
All guides
Build a card payment,
GUIDE 01 / ONLINE CARD PAYMENTS
Build a card payment,
one piece at a time.
Start with a customer and a store. Add each part when a real problem calls for it. By the end, the full flow makes sense.
Each step adds one part to the system. Follow the path across the diagram, then read why that part exists.
THE INTERACTIVE BUILD
From first sketch to full flow.
This is a teaching model of a typical online card purchase. The exact path can vary by provider and region.
01 / PAYMENT PATHWho handles the card request?
Follow the shopper, store, provider, network, and issuer.
02 / EXAMPLE SOFTWAREWhat might a store build?
See where a checkout SDK, database, webhooks, and Kafka can fit. Jump to the stack →
BUILD PROGRESS01 / 08
PAYMENT PATH
A first sketchTHE REQUESTTOP TO BOTTOM
The arrows show the handoffs. Once added, secure checkout sends card details to the provider.
Issuer sends its decision back
KEEP THIS IN MIND
ONE POSSIBLE IMPLEMENTATION
Where tools like Kafka fit.
This is an example store-side stack. A real store may choose different tools or use fewer services.
THE BOUNDARYYour store builds the order flow.
The provider and banks handle the card route. The issuer makes the approval decision.
EXAMPLE TOOLS
Stripe Payment Element · Node.js · PostgreSQL · optional Kafka
YOUR STORE
Store API + PostgreSQL
The server creates an order and a payment request. PostgreSQL keeps the order amount and payment state. A unique request key makes retries safer.
Node.js, Java, or GoPostgreSQLIdempotency key
AT CHECKOUT
Hosted card form
The shopper enters card details in a provider-controlled form. The store receives a payment reference, not raw card details in its order record.
Stripe Payment Element, for example
OUTSIDE YOUR STORE
Provider → banks
The provider sends the authorization request through the acquirer and card network. The issuer approves or declines it. Kafka is not needed for this decision.
Payment provider APIAcquirerCard networkIssuer
YOUR STORE
Webhook handler + PostgreSQL
The provider sends a server-to-server update. The store verifies it, handles repeats safely, and updates the order record. This can happen after the shopper closes the page.
Webhook endpointSignature checkPostgreSQL
OPTIONAL AS THE STORE GROWS
Outbox → Kafka → workers
Once the store records a successful payment, it can publish an event for shipping, email, or analytics. An outbox helps keep the database change and event in sync. Kafka carries these events to other services.
Outbox tableApache KafkaFulfillment worker
So, should Kafka appear in the guide? Yes, as an optional way for the store’s services to share events after payment state changes. A small store can begin with a database and webhook handler.
FOLLOW THE MONEY
Approved does not mean paid.
Three different moments are often called “the payment.” They do different jobs.
↗
Authorization
The issuer says yes or no. A yes usually places a hold for the amount. Money has not reached the store.
Decision, usually in seconds◎
Capture & clearing
The approved charge is captured, sometimes automatically. Transaction details are sent through the card system so both banks can record it.
The charge is submitted✓
Settlement
Funds move between the banks. The acquirer then makes the merchant’s money available, after any fees.
Funds move later✳
Debit and credit follow the same broad route here. A debit card uses account funds; a credit card uses available credit. The shopper may see a pending charge before it is final.
THE WORDS YOU NEED
A small glossary.
Standard payment terms, translated into plain English.
Issuer
The shopper’s card bank. It decides whether to approve the payment.
Acquirer
The merchant’s bank or acquiring partner. It helps the store accept card payments.
Card network
The network, such as Visa or Mastercard, that routes messages between the two sides.
Payment provider
The service the store connects to for checkout and payment processing. Its exact role varies.
3-D Secure
An extra way for the issuer to check the shopper’s identity when needed.
Webhook
A server-to-server update that tells the store when a payment changes state.
Idempotency key
A unique label that helps the provider recognize a repeated request.
Outbox
A database table that holds events to send after the order record changes.
Kafka
A tool that can pass events to other store services. It is optional in this example.
YOU HAVE THE WHOLE PICTURESeven parts. One payment.
Walk through it again