02Trace the requirements
Map each of the ten requirements to the contract, and record the ones the contract does not satisfy.
The requirements arrive
Product has written ten requirements for the launch. They are short, numbered, and mostly testable, which is better than usual. Your job is not to judge them. It is to check whether the contract can satisfy each one.
How to trace
A traceability line has three parts: the requirement, the contract element that implements it, and your verdict. Keep the verdict to one of three words:
- Covered. The contract has an element that satisfies the requirement as written.
- Partial. The contract has something related, but it does not satisfy the requirement as written. Say what is missing.
- Gap. Nothing in the contract addresses it.
A partial is the dangerous case. It is where a developer builds against what the contract has and discovers in testing that the requirement wanted more. Be precise about the missing piece: “the endpoint exists but has no way to request the next page” is actionable. “Pagination is weak” is not.
What to look for
Read each requirement for its nouns and its constraints. The nouns tell you which endpoint to look at. The constraints (a limit, a retention period, a state, an error the merchant can display) tell you what to check in the schema. When a requirement names a state, find it in the enum. When it names an error the merchant must handle, find the error code. When it names a header, find the header.
Your task
For each requirement REQ-01 to REQ-10, write one line: the endpoint, field, header, or webhook that satisfies it, or the word GAP with one sentence saying what is missing. Add every GAP to your findings list with a severity.
Evidence for this step
Read it in the page or download it and open it in your own tools.
Mission artifact requirements.md 21 lines download show
# Marketplace Payments v2: launch requirements
Owner: Product, marketplace checkout squad
Status: approved for build
Provider: Northline Pay, Merchant API v1
| ID | Requirement | Acceptance |
|---|---|---|
| REQ-01 | The marketplace creates a payment for a buyer with authorization and capture as separate steps. Capture can happen up to 7 days after authorization. | A payment authorized on day 0 can be captured on day 7. |
| REQ-02 | Payment creation is idempotent. The marketplace sends a unique key with every create request. A retry with the same key within 24 hours returns the original payment. The same key with a different body is rejected with an explicit error. | Sending the same request twice creates exactly one payment. |
| REQ-03 | Amounts are integers in minor units. Currencies at launch are CAD and EUR only. | A request with a decimal amount or another currency is rejected. |
| REQ-04 | A payment can be split across up to 10 seller accounts. The sum of the splits equals the payment amount. | A split that does not add up is rejected before authorization. |
| REQ-05 | A captured payment can be refunded partially, several times. The cumulative refunded amount never exceeds the captured amount. A refund above the remaining amount is rejected with an error code the marketplace can map to a customer-facing message. | Two partial refunds of 60 and 50 on a 100 capture: the second is rejected with a specific code. |
| REQ-06 | Finance lists payments for daily reconciliation, filtered by creation date range and status, and paginates through up to 50,000 payments per day. | The reconciliation job retrieves every payment of a given day, exactly once. |
| REQ-07 | When the issuer requires 3-D Secure, the payment enters a `requires_action` state and the response carries the redirect URL for the buyer. | The checkout redirects the buyer and resumes when the payment becomes authorized. |
| REQ-08 | The marketplace receives webhooks for payment authorized, captured, failed, and settled, and for refund succeeded. Every webhook is signed so the marketplace can verify it came from Northline. | A webhook with a bad signature is discarded and logged. |
| REQ-09 | The API never returns more card data than brand, last four digits, and expiry. | No response contains a full card number or a CVC. |
| REQ-10 | The marketplace may send up to 100 requests per second. Above that, the API returns 429 with a `Retry-After` header the client honors. | A burst above the limit backs off and completes without errors surfacing to buyers. |
Notes from the review meeting: REQ-06 is the finance team's hard requirement; the current provider's list endpoint cannot do it and reconciliation is done by hand every morning. REQ-02 exists because of the duplicate charge incident in March.