API Reference

PaySecure Malawi Escrow-as-a-Service

The PaySecure Malawi Escrow API allows businesses to integrate secure escrow transactions into their platforms. Built on a strict double-entry ledger architecture, it guarantees decimal-perfect balancing across buyer, seller, platform revenue, and escrow accounts.

Base URL

https://trustlink.up.railway.app/api/v1

Authentication

Our API utilizes two modes of authentication depending on the requested resource. End-user entities (Buyers / Sellers) never authenticate directly with our API; your business platform acts as the proxy.

1. Business JWT

Required for business registration and login operations. Supplied as a Bearer token.

Authorization: Bearer <YOUR_JWT>

2. X-API-Key

Required for all User Management and Escrow operations. You can obtain your API key via the Developer Dashboard or the login endpoint.

X-API-Key: <YOUR_API_KEY>

Rate Limits

To ensure system stability, requests are limited according to functionality tiers over a 15-minute rolling window.

Tier Group	Limit (15 min)	Scope
General	100 requests	All non-critical GET routes
Authentication	10 requests	Login & Registration
Financial	30 requests	Escrow create/fund/release/refund

Escrow Ops

Create an Escrow

POST /api/v1/escrow/create X-API-Key

Instantiates a new escrow arrangement. Both `buyerId` and `sellerId` must reference verified Users created under your business account. Only `VERIFIED` users can participate in escrows.

Request Body (JSON)

buyerId
number
The primary ID of the buying User.
sellerId
number
The primary ID of the selling User.
amount
decimal
Transaction value (e.g. 50000.00). Must be positive.

Example Request

POST /api/v1/escrow/create
X-API-Key: sk_live_a1b2c3...
Content-Type: application/json

{
  "buyerId": 105,
  "sellerId": 814,
  "amount": 245000.50
}