Cloud Middleware

Cloud API v1.0

REST | HTTPS | JSON

Complete reference for integrating your POS system with NamiPay terminals via Cloud REST APIs.

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

Integration Steps

1. Authenticate - Get a Bearer token. Valid 24 hours.
2. Register - Register merchants and terminals.
3. Webhooks - Set up signed callback URLs.
4. Transact - POST transactions to a single endpoint.

System Architecture

ECR / Cashier (Your POS) → NamiPay Middleware (mw-uat.namipay.com.sa) → POS Terminal Adapter App → Your Webhook (Results)

Authentication

Obtain an access token using your client credentials. Tokens expire after 24 hours.

POST /api/auth/getToken
Get Access Token

Merchants

Register merchants in the NamiPay system.

POST /api/merchants  [AUTH]
Register Merchant

Terminals

Register POS terminals and check their status.

POST /api/terminals/register  [AUTH]
Register Terminal

Webhooks

Set up webhooks for real-time transaction results. Uses HMAC SHA-256 signed URLs.

POST /api/webhooks/generate-url  [AUTH]
Generate Webhook URL

POST /api/webhooks/register  [AUTH]
Register Webhook

Transactions

All payment transactions use a single endpoint with different TransactionType values.

Supported Transaction Types: PURCHASE | REFUND | AUTHORIZATION | PRE_AUTHORIZATION | PURCHASE_ADVICE | REVERSAL | PRE_AUTH_VOID | PRE_AUTH_EXT | CASH_ADVANCE | RECONCILIATION

POST /api/payments/performTransaction/{terminalId}  [AUTH]
Purchase

POST /api/payments/performTransaction/{terminalId}  [AUTH]
Refund

POST /api/payments/performTransaction/{terminalId}  [AUTH]
Authorization

POST /api/payments/performTransaction/{terminalId}  [AUTH]
Reconciliation