Cloud Middleware (REST)

The NamiPay Cloud Middleware is a cloud-hosted REST API that connects your Electronic Cash Register (ECR) or POS software to Nami payment terminals for payment processing. Unlike the Local API Middleware (REST) — a Windows service you run on the same machine as the till — the Cloud Middleware is hosted by NamiPay and reached over HTTPS, so a single integration can route transactions to many terminals across locations.

Base URL (UAT): https://mw-uat.namipay.com.sa

📘

This is the UAT base URL

mw-uat.namipay.com.sa is the user-acceptance-testing environment. Confirm the production base URL with NamiPay before going live.

What it does

The API covers the full lifecycle: authenticate, register a merchant, register terminals under that merchant, run transactions against a terminal, and receive real-time results via webhooks.

It supports token-based authentication with a 24-hour expiry, the full set of transaction types (Purchase, Refund, Cash Advance, Authorization, Pre-Authorization and its lifecycle, Reversal, Reconciliation, Purchase Advice, and Bill Payment), webhook notifications for real-time transaction status, terminal health monitoring, and HMAC-SHA256-signed webhook URLs.

How a transaction flows

Payment requests return immediately with status: PROCESS and statusCode: 100 — the terminal then processes the card, and the final result is delivered to your server via a webhook, not in the original HTTP response. So a working integration needs both halves: the transaction call and a registered webhook receiver.

Your ECR ──POST /api/payments/performTransaction──► Cloud Middleware ──► Terminal
   ▲                                                      │
   └──────── webhook callback (final result) ◄────────────┘

Where to go next

• Authentication — get a 24-hour access token.
• Merchant Management — register a merchant.
• Terminal Management — register terminals and list recent registrations.
• Payment Transactions — one endpoint, all transaction types.
• Webhooks — generate, register, and receive real-time results.
• Status Codes — HTTP and transaction status codes.