Payment Service and Checkout Architecture
A self-study textbook covering essential theory, comparative examples, guided practice, quality review, and a capstone exercise. Central question: How do we track and recover the movement of money without duplication or loss?
Learning Goals and Study Routine
How do we track and recover the movement of money without duplication or loss? You complete today’s lesson when you can answer this question in your own words, produce the required artifact, and review its quality.
Model order and payment states separately.
Prevent duplicate charges with idempotency keys.
Distinguish authorization, capture, cancellation, and refund.
Handle webhook signatures and redelivery safely.
Design compensation for partial failures.
Detect monetary discrepancies through reconciliation and audit logs.
Recommended self-study routine
- Explain why a problem occurs before memorizing its terminology.
- Describe the difference between good and poor examples using observable criteria.
- Attempt the capstone before opening the model answer.
- Mark missing conditions in a second color and revise your artifact.
Table of Contents
- Study Guide and Learning GoalsPage 02
- Chapter 1. Core Theory and Design PrinciplesPage 04
- Chapter 2. Guided Design PracticePage 05
- Chapter 3. Case Review and Quality CheckPage 06
- Chapter 4. Capstone and Model AnswerPage 07
- Glossary and Final ChecklistPage 08
- Self-study reference and guided practicePages 09–11
Submit the capstone artifact, score at least 80/100 on the self-review, and write your own answers to the four concept questions.
Core Theory: Payment Service and Checkout Architecture
Each technical term exists to solve a recurring design problem. Study when and why the concept is needed, not merely its definition.
| Core concept | Working definition |
|---|---|
| Payment Intent | A business unit that represents and tracks a payment attempt. |
| Authorization | Approval that funds are available for a charge. |
| Capture | The step that actually collects an authorized amount. |
| Idempotency Key | An identifier that prevents duplicate processing of one request. |
| Webhook | An asynchronous request notifying the server of a payment-state change. |
| Reconciliation | Comparison of internal ledgers with gateway settlement records. |
Poor and Effective Approaches
Avoid
Create a new authorization every time the payment button is clicked and complete the order from the client response alone.
Prefer
Persist a payment intent and idempotency key, verify server and webhook state, and perform each allowed state transition once.
[Server-calculated Total] → [Payment Intent] → [Idempotent Authorization] → [Verification] → [Order Transition] → [Webhook, Reconciliation, Refund]
A Six-Step Design Workflow
Define the problem
Calculate the final amount on the server from products and discount rules.
Extract the structure
Store separate IDs and states for orders and payment attempts.
Design the core flow
Use an idempotency key and timeout for gateway calls.
Add failure conditions
Verify results on the server regardless of the client success screen.
Connect policies
Validate webhook signatures, event IDs, duplicates, and out-of-order delivery.
Verify and trace
Reconcile orders, payments, refunds, and fees against settlement data.
Worked Example
Questions for reading the example
- Are the input and initiating condition explicit?
- Are success and failure outcomes observable?
- Are duplication, authorization, concurrency, and dependency failure covered as needed?
- Can the result be traced back to a requirement?
Concept Check and Quality Review
- What breaks when order and payment states are combined?
- Why must a webhook signature be verified?
- Why must the server distrust an amount from the client?
- Why is reconciliation necessary beyond real-time processing?
Answer each in two or three sentences and add one example that supports your explanation.
Self-Assessment · 100 points
| Area | Standard | Points |
|---|---|---|
| Accuracy | Concepts and technical choices match the facts and requirements. | 25 |
| Completeness | Normal flow, boundaries, failures, and recovery are covered. | 25 |
| Consistency | Terms, IDs, states, and interfaces agree across artifacts. | 20 |
| Verifiability | Observable outcomes and completion criteria are present. | 20 |
| Reasoning | The choice and its tradeoffs can be explained clearly. | 10 |
Do not only correct the result. Record which question you failed to ask so your next design process prevents the same omission.
Capstone Exercise and Model Answer
The user refreshes five times after payment and the gateway webhook arrives twice. Design the flow and include a network failure during refund.
- List assumptions and unresolved decisions first.
- Produce the main design as a table, diagram, or code block.
- Include the normal flow and at least three failures or boundaries.
- Score it with the rubric and compare before and after revision.
Open the model answer
Reuse an order-based idempotency key for client and gateway requests. Store webhook event IDs to ignore duplicates and permit only valid state transitions. Record REFUND_PENDING before calling the gateway, then confirm the final state through lookup or webhook.
How to use the answer
The model is not the only valid design. If yours differs, explain the requirement, cost, complexity, or risk that justifies your choice.
Glossary and Final Checklist
| Term | Plain-English meaning |
|---|---|
| PG / Gateway | A provider that connects merchants with payment networks. |
| Authorization | Approval to use an amount from a payment method. |
| Capture | Actual collection of an authorized amount. |
| Webhook | A request sent by an external service after a state change. |
| Ledger | An append-oriented record of monetary changes. |
| Reconciliation | Comparing payment records to discover differences. |
Eight checks before submission
- Can you answer today’s central question in your own words?
- Are inputs, conditions, and results explicit?
- Did you include failures and recovery, not only the happy path?
- Did you review concurrency, duplicate requests, and permissions?
- Did you account for dependency failure and timeouts?
- Can you explain the disadvantages and alternatives to your choice?
- Are terminology and states consistent across artifacts?
- Is there an observable or testable completion standard?
How do we track and recover the movement of money without duplication or loss? Answer it now using evidence from the artifact you created.
Key Terms in Context
Learn each term as a decision tool. Read across each row: definition, reason to use it, and the failure it prevents.
| Term | Plain definition | Why it matters | Example or caution |
|---|---|---|---|
| Payment gateway | A provider connecting merchants with cards, banks, and payment methods. | It unifies authorization across payment rails. | The server must verify the provider result directly. |
| Authorization and capture | Authorization reserves funds; capture submits the charge for settlement. | They determine cancellation and settlement behavior. | Do not reduce payment state to only success and failure. |
| Webhook | An asynchronous server notification about a payment state change. | It updates final state even if the browser closes. | Verify signatures and process duplicate events safely. |
| Idempotency key | A unique key identifying one logical payment attempt. | It prevents duplicate charges during retries. | Store the key and result by order. |
| PCI DSS | A security standard for protecting cardholder data. | It limits sensitive-data handling scope and responsibility. | Avoid storing raw card numbers whenever possible. |
| Reconciliation | Matching provider transactions with the internal ledger. | It catches financial discrepancies. | Define daily matching and an exception workflow. |
The user clicks Pay twice; the first response times out although the provider approves it, and a webhook arrives later.
Guided Practice and Troubleshooting
Practice scenario
The user clicks Pay twice; the first response times out although the provider approves it, and a webhook arrives later.
Complete in order
- Define order, payment, and refund states with allowed transitions.
- Attach an idempotency key and persist the server result.
- Verify webhook signatures and use them to confirm final state independently of redirects.
- Reconcile provider transactions with the internal ledger on a schedule.
Save one artifact, three assumptions, and at least three failure cases. A classmate should be able to reproduce your reasoning without asking what you meant.
If the result is wrong, diagnose it
| Observed symptom | Likely cause | Next action |
|---|---|---|
| Duplicate charge | Retries are not identified | Order-scoped idempotency key |
| UI says failed but payment succeeded | Only browser response is trusted | Server lookup and webhook confirmation |
| Forged webhook accepted | Signature check missing | Verify raw-body signature and timestamp |
Check Your Understanding
Retrieval check — answer before opening
Why not trust the success page?
Browser responses can be interrupted or manipulated; the server must confirm with the provider.
Are void and refund always the same?
No. Pre-capture cancellation and post-capture refund can have different processing and settlement rules.
When is payment ready?
Duplicates, timeouts, webhooks, refunds, and reconciliation pass without money-state discrepancies.
Explain the day's main decision, one failure mode, and one verification method without reading the page. If you cannot connect all three, return to the row or diagnostic case you missed.