04Apply the business rules and write the gap register
Northline's own rules confirm some of your findings and reveal that the contract is missing behavior the provider actually enforces. Write the register.
The provider’s own rules
You asked Northline for anything beyond the contract, and their payments operations team sent an internal page: eight business rules the platform enforces. This is the artifact most integrations never see, and it is the one that explains most production surprises.
Business rules from the provider are different from your requirements. Your requirements say what you need. Their rules say what the platform does whether you need it or not. The interesting cases are where the rules describe behavior the contract does not document: an error code, a header, a state, a time limit. Each of those is a place where the implementation is ahead of its documentation, and where your developers will build against the wrong thing.
What to check
For each rule, ask two questions:
- Does the contract document this behavior? If a rule names an error code, a header, or a state, search the OpenAPI file for it.
- Does this rule confirm or change one of my earlier findings? Some of your gaps from step two will turn out to be documentation gaps, not capability gaps: the platform does it, the contract just does not say so. That changes the severity and the question you ask.
Write the register
Use the template. One row per finding. Severity is about consequence for your integration, not about how big the fix is:
- High: without resolution, the integration will produce wrong money movements, duplicate payments, or a failed reconciliation.
- Medium: the integration will work but a client that follows the contract will break on real traffic.
- Low: documentation debt that will cost a support ticket or a wasted hour.
The last column is the one that matters: the question, written so the API team can answer it in one line. “Is Idempotency-Key enforced on POST /payments, and what does a reused key with a different body return?” gets an answer. “Can you clarify idempotency?” gets a meeting.
When your register is done, open the solution and score yourself. Mark only the findings you actually had written down. The gap between your list and the solution is the thing to learn from.
Your task
Read the eight business rules against the contract. Then write your gap register using the template: every finding, its severity, the evidence (which artifact, which line), and the exact question you would send the API team. Then compare with the solution.
Evidence for this step
Read it in the page or download it and open it in your own tools.
Mission artifact business-rules.md 20 lines download show
# Northline Pay: platform business rules (merchant-facing)
Source: Payments Operations, internal wiki, shared on request. These rules are enforced by the platform in sandbox and production.
**BR-1 Authorization validity.** A card authorization can be captured for 7 calendar days. After that the payment moves to status `expired` and cannot be captured. Merchants must create a new payment.
**BR-2 Refund limits.** The cumulative amount of succeeded and pending refunds on a payment cannot exceed `captured_amount`. A refund request above the remaining amount is rejected with HTTP 400 and error code `refund_exceeds_captured`. The `message` field states the remaining refundable amount.
**BR-3 Amounts and currencies.** Amounts are integers in the smallest currency unit. Supported currencies are `CAD` and `EUR`, upper case. Requests with a non-integer amount or another currency are rejected with `invalid_request` and `param` set to the offending field.
**BR-4 Idempotency.** When a request carries an `Idempotency-Key`, the platform stores the key with the request body hash for 24 hours. A retry with the same key and the same body returns the original response with the original status code. The same key with a different body is rejected with HTTP 422 and error code `idempotency_key_reused`. Requests without the header are processed every time.
**BR-5 Webhook signatures.** Every webhook carries a `Northline-Signature` header: `t=<unix timestamp>,v1=<HMAC-SHA256 of "<timestamp>.<raw body>" with the endpoint secret>`. Merchants must reject a signature older than 5 minutes. The endpoint secret is shown once when the endpoint is created.
**BR-6 Split payments.** A split lists at most 10 seller accounts. Each split amount is at least 100 minor units. The sum of split amounts must equal the payment amount, or the request is rejected with `invalid_request` and `param: split`.
**BR-7 Settlement.** Captured amounts settle to the merchant on the second business day after capture (T+2). When a payment is included in a paid settlement, the `payment.settled` webhook is sent with the `settlement_id`.
**BR-8 Card data.** Responses never include the full card number or the CVC. The buyer email is returned only on payments created by the same merchant account.Mission artifact gap-register-template.md 21 lines download show
# Gap register: <integration name>
Analyst: <you>
Date: <date>
Artifacts reviewed: OpenAPI v<version>, requirements v<version>, sample responses (<count>), business rules (<date>)
| # | Finding | Severity | Requirement / rule | Evidence (artifact, location) | Question for the API team | Status |
|---|---|---|---|---|---|---|
| 1 | <one sentence: what disagrees with what> | High / Medium / Low | REQ-xx, BR-x | <file, path or line> | <one line, answerable in one line> | Open |
| 2 | | | | | | |
Severity guide
- High: wrong money movement, duplicates, or failed reconciliation if unresolved.
- Medium: a client that follows the contract will break on real traffic.
- Low: documentation debt; costs a support ticket or an hour.
Rules for a good row
- Name the exact field, header, code, or state. Never "the pagination" or "the errors".
- Evidence is a location someone else can open, not a memory.
- One question per row. If you need two, it is two findings.