A PKR settlement API you can audit
Connect an exchange, a payments business or a fintech product to Pakistani Rupee settlement. Below is what the API does today — and, just as importantly, what it does not do yet. You will find that out during integration anyway; better here.
API keys, scoped down to the call
A key is issued from the partner portal and shown to you exactly once. We store a hash of it — Argon2id, the same class of algorithm used for passwords — never the key itself. If you lose it, nobody at Meridian can recover it for you; you rotate and move on.
Eight scopes, granted individually
quotes:read, quotes:write, orders:read, orders:write, wallets:read, settlements:read, settlements:write, reports:read. A key can never be granted more access than the person issuing it holds.
Per-key IP allowlisting, enforced
Attach up to 50 entries to a key — exact IPv4 or IPv6 addresses, or IPv4 CIDR ranges. A key with a non-empty list is refused from anywhere else. The check uses the real connecting address; a spoofed X-Forwarded-For header is ignored unless the deployment is explicitly configured to trust a proxy.
Rotate without downtime
Rotation mints a replacement carrying the same label, scopes and allowlist, then revokes the old key. Keys can also be given an expiry between 1 and 730 days at issue, and revoked individually at any time.
Failures tell an attacker nothing
A wrong key, a revoked key, an expired key and a blocked IP all return the same 401 and the same message. An unrecognised key still pays the cost of a full hash comparison, so response timing cannot be used to guess which keys exist.
What the machine API does today
None of these endpoints takes an institution identifier. Your institution is resolved from the key on the request, so there is no id in any signature for a client to tamper with. That is the cross-tenant boundary, and it stays a boundary because it stays server-side.
| Endpoint | Scope required | Detail |
|---|---|---|
| Create a quote | quotes:write | A priced, server-locked quote. The rate cannot move between the quote and the order. |
| List orders | orders:read | Filter by status, with paging. Read a single order by id. |
| Read wallet balances | wallets:read | Your institution’s balances, resolved from your key — never from an id in the request. |
| Settlement report | settlements:read | Your most recent 100 settled and settling orders, with rate, gross, fee and net. |
The settlement report returns the most recent 100 orders. It has no date-range filter, no paging and no CSV export yet — if you need a full historical extract for reconciliation, tell us what shape you need it in before you build around this endpoint.
Order creation is not yet a machine endpoint
The orders:write and settlements:write scopes exist and can be granted, but no machine route requires them yet. Today a partner can price and read through the API; order placement runs through the portal. If your integration depends on programmatic placement, raise it with us before you plan around it.
What is defined but not yet enforced
These exist in the API’s design and its constants, and they are not switched on. Do not build as though they are.
Request signing
The header names and replay window are reserved — x-api-signature, x-api-timestamp, x-api-nonce, with a five-second window — but nothing verifies them yet. Authentication today is the x-api-key header over TLS, narrowed by the IP allowlist. Use the allowlist; it is the control that is actually enforced.
Outbound webhooks
You can set a webhook URL and generate an HMAC-SHA256 signing secret in the portal today, and the portal will show you a fingerprint of it. Deliveries are not being sent yet, and there is no delivery history to show you — the portal says so rather than displaying an empty table as though one were coming. Poll the order and settlement endpoints for now.
Per-key rate limits
Target tiers are defined — 600 reads and 60 writes per minute — but are not yet applied per key. Build your client to back off on errors anyway; these will be turned on, and we would rather you were ready than surprised.
No sandbox key
There is no test-mode key type. Every key issued is a live key. Plan your integration testing accordingly and talk to us before you point a test suite at it.
Team seats are not supported
An institutional account is exactly one user account: its owner. There is no invite flow, no second seat and no per-person roles, and the portal states this rather than implying a team model exists. If you need to delegate access to a colleague or a system, the supported way is to issue them their own API key with only the scopes they need and their own IP allowlist — which is also the version that leaves a usable audit trail.
Multi-seat support is a real gap, not a design decision we are proud of. It is worth telling us if it blocks you.
Settlement and reconciliation
Every figure traces to the ledger
Settlement rows are derived from the same double-entry, append-only ledger that carries every other movement on the platform. Ledger entries cannot be updated or deleted — the database refuses it — so a figure you reconciled last month is the same figure this month.
Per-order breakdown
Each settlement row carries the order reference, side, status, locked rate, asset amount, fiat amount, fee and net, plus creation and completion timestamps. That is enough to reconcile line by line rather than on a total.
A 30-day dashboard
Settled order count and volume, open orders, active keys, and your monthly volume limit with how much of it you have used. The window is fixed at 30 days today.
On-chain movement is sandboxed
The chain integration currently runs against a sandbox custody provider outside production. Until a live custody provider is configured, on-chain deposits and withdrawals do not move real funds. Internal balances, orders and rupee settlement are unaffected.
Talk to us before you build
Tell us the flow you need and the volume you expect, and we will tell you honestly whether the API supports it today. Contact the partnerships desk.