PARTNERING INSURTECH LIMITED Aggregator: Merchant API

Every endpoint lives under /api/v1. Authenticate with the x-api-key header, sent as <keyId>:<secret>; the key id prefix decides the environment (sk_test_ reads and writes test data, sk_live_ production data), and a live key on a business that is not activated for production is refused with 403 PRODUCTION_NOT_ACTIVATED.

Every response carries X-Request-Id: the value sent on the request when it matches ^[A-Za-z0-9._-]{1,64}$, otherwise a freshly minted req_<uuid>. Every authenticated response also carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; requests over the per-minute budget are refused with 429 and a Retry-After.

Every failure (including the ones raised by an insurer behind this API) answers the same error envelope, whose correlationId is the request id. When the failure came from an insurer, its own correlation id is preserved as details.providerCorrelationId and its OIIS code and status are passed through unchanged, so codes and statuses beyond the ones listed on an operation are possible.

Text fields are trimmed before they are used and a value that is only whitespace is rejected as empty, while the documented length bounds are measured before trimming.

Request bodies must be JSON and are capped at 1 MiB; a larger body is refused with 413 PAYLOAD_TOO_LARGE and a malformed one with 400 BAD_REQUEST.

Writes are idempotent: send a UUIDv4 Idempotency-Key. Repeating a key with the same body replays the stored result: 200 instead of 201, with Idempotency-Replayed: true. Repeating it with a different body is 409 IDEMPOTENCY_KEY_CONFLICT.