# 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.