Follow the Money.

Payment lifecycleno payment yet

Idempotency-Key

Send a request to see the response.

Designer notes

Teaching a payments API by letting people call it

A hands-on technical tutorial for developers and solutions architects integrating a payments API for the first time. Learners follow one order for an outdoor gear shop from checkout to chargeback, making realistic API calls against a simulated server. The lesson pane explains; the console is where the learning happens.

Learning objectives

By the end, learners can…	Practiced	Assessed
Express amounts in the smallest currency unit	Step 1	Q4
Use auth-and-capture when fulfillment is delayed	Steps 1–3	Q2
Read a decline and recover the payment	Step 2	Q5
Fulfill on a webhook event, not a client redirect	Step 3	Q3
Make retries safe with idempotency keys	Step 4	Q1
Issue partial refunds and respond to disputes	Steps 5–6	Q6

Design decisions

Productive failure first. Step 1's example sends 42.50 on purpose. The 400 error teaches the integer-amount rule better than a callout would, and it teaches learners to read error objects.
One order, start to finish. A single story ("Bramble & Co.") ties every endpoint to a business reason: ship later, one item out of stock, a return, a chargeback.
State is always visible. The lifecycle bar and the webhook log make an asynchronous system concrete. Learners see the event their server would receive at the moment it's sent.
Gated by outcome, not clicks. Each step unlocks when the server state is correct, however the learner got there, so editing the JSON freely is encouraged.
Hints escalate. A nudge first, then the exact fix, so stuck learners don't abandon the step.
Scenario-based check. The final questions are business situations, not definitions, and each maps to one objective.

Measurement

Each request, error, hint, and step completion is captured as an xAPI-style statement an LMS or LRS could store. Item-level quiz results show which concepts need better content. Here's this session's data, live:

(no activity yet)

How it's built

A single HTML page with vanilla JavaScript: a small in-browser API simulator (routing, validation, state machine, idempotency cache, event emitter) and a data-driven step engine where each step declares its story, tasks, example request, hints, and a completion check. Built with AI coding tools; designed and reviewed by me.

Ferrypay is a fictional API created for this sample. Its design mirrors common patterns across payments APIs; it is not affiliated with any payments company. Bramble & Co. is fictional.