Payments: retries, refunds and reports
A payments API for online shops. A shop charges a customer by creating a payment; the server gives it an id. The network between the shop and the API sometimes times out, so shops send an Idempotency-Key with every charge. A charge completes before the API answers, and a repeat with the same key and body gets the first response again. Payments are never deleted. A refund is a separate record that belongs to a payment, and a payment can be refunded in parts. The monthly settlement report takes a few minutes to build: the API accepts the request, answers at once and builds the report in the background, at its own URL. Tokens carry scopes: payments:read or payments:write.
For each request, choose the method, the path and the status code the server returns.
1.Charge €19.99 for order 42, with Idempotency-Key K1.
2.The shop timed out, so it sends the same charge again with the same key K1. The first attempt had succeeded.
3.Refund €5 of payment p_9.
4.Check the state of payment p_9.
5.List the shop's payments, 50 at a time, newest first.
6.Request the October settlement report.
7.Check whether the report is ready.
8.A support tool whose token has only payments:read tries to refund payment p_9.
- POST /payments → 201 Created. Not idempotent by itself, which is why the shop sends a key.
- POST /payments → 201, the stored response from the first attempt. No second charge, no error: the retry is what idempotency keys are for.
- POST /payments/{id}/refunds → 201 Created. The payment itself isn't changed or deleted; a refund record is added under it.
- GET /payments/{id} → 200.
- GET /payments?limit=50&cursor=… → 200. Cursor paging stays stable while new payments arrive.
- POST /reports → 202 Accepted, with Location: /reports/{id}. The work is queued, not done.
- GET /reports/{id} → 200, with a status field: queued, running, succeeded or failed.
- POST /payments/{id}/refunds → 403 Forbidden: a valid token without the payments:write scope.
Methods
Paths
Status codes
Tap a slot, then a part. Or drag a part into a slot. Each part can be used many times.