Clear contracts. Connected partners.

01 / Provision access and agree the contract

Start with an institutional agreement covering merchant scope, permitted operations, data handling and support ownership. The production service must issue credentials through an authenticated provisioning process, with separate test and live access. The $ACCESS_TOKEN in the curl examples is an environment-variable reference, never a usable credential. Tokens must not be embedded in frontend code or shared screenshots.

Version the schema and publish the exact meaning of each status before implementation. Sales, payment callbacks and receipt lookup have different authorization requirements. Contract tests should cover required fields, unsupported currencies, duplicate references, malformed requests and out-of-order events. Authority-specific fields must be validated against the certified CIS/VSDC contract rather than inferred from these examples.

02 / Sale payload and validation rules

The sale example uses externalId as the stable partner reference, currency for the accounting unit, channel for origin and items for line-level evidence. Each item supplies a name, positive quantity, unitPrice and catalog classification. Production arithmetic must specify precision and rounding, verify the catalog and reject impossible quantities before any fiscal submission.

A retry must reuse the original externalId and the same payload. If the reference already exists with different content, the proposed contract returns a conflict rather than silently overwriting the first sale. Keep transport acknowledgement distinct from recorded status and authority acceptance. The example response explicitly sets simulated to true and rraSubmitted to false.

03 / Signed callbacks and reconciliation

A proposed payment event includes an event reference, sale reference, amount, currency and state. Verify the provider’s signature over the exact raw body before trusting it, using the signing method agreed in the partner contract. A timestamp and replay window protect against stale deliveries; store the event identity to prevent repeated processing. The example headers below illustrate requirements, not an active signing protocol.

A durable production receiver should acknowledge only after preserving an authenticated event. Processing can then reconcile amount, currency and sale ownership asynchronously. Failed deliveries use bounded retries, while unresolved cases enter a review queue. A successful wallet callback does not certify a fiscal receipt, and a payment reversal must follow its own correction workflow.

Illustrative callback envelope

POST /v1/payments/callback
Content-Type: application/json
X-Event-Id: PAY-001
X-Event-Timestamp: <unix_timestamp>
X-Signature: <contract_defined_signature>

{
  "externalId": "PAY-001",
  "saleId": "SALE-001",
  "provider": "Mobile Money",
  "amount": 45000,
  "currency": "RWF",
  "status": "SUCCESSFUL",
  "simulated": true
}

04 / Errors, retry policy and launch gates

The error reference below is a proposed contract design, not a promise of current endpoint behaviour. Clients should distinguish invalid input, missing authentication, forbidden access, idempotency conflicts, rate limits and temporary service failures. Retry only recoverable conditions, preserve the event identity and respect Retry-After when supplied. Do not retry a validation rejection without correcting its cause.

Before live access, complete contract tests, security review, telecom provisioning and certified authority validation. Exercise duplicate and out-of-order callbacks, long outages, receipt lookup and a complete export larger than 1,000 rows. Agree monitoring, escalation and rollback with the institution. Production release requires explicit approval; success in the public test environment is not certification.