Purpose

The NamiPay Cloud Middleware provides REST APIs over HTTPS for integrating POS systems with NamiPay terminals. It abstracts direct terminal communication and enables secure, cloud‑based transaction processing.

Prerequisites

• Access to NamiPay Cloud Middleware (UAT or Production)
• Valid client credentials (Client ID, Client Secret)
• HTTPS connectivity to https://mw-uat.namipay.com.sa
• Webhook endpoint configured to receive signed callbacks

Base URL

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

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 client credentials. Tokens expire after 24 hours.

Endpoint

POST /api/auth/getToken

Description: Get Access Token

Merchants

Register merchants in the NamiPay system.

Endpoint

POST /api/merchants  [AUTH]

Description: Register Merchant

Terminals

Register POS terminals and check their status.

Endpoint

POST /api/terminals/register  [AUTH]

Description: Register Terminal

Webhooks

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

Endpoints

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.

Endpoint

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

Supported Transaction Types

• PURCHASE
• REFUND
• AUTHORIZATION
• PRE_AUTHORIZATION
• PURCHASE_ADVICE
• REVERSAL
• PRE_AUTH_VOID
• PRE_AUTH_EXT
• CASH_ADVANCE
• RECONCILIATION

Transaction Flow

HTTP POST → Cloud Middleware → Terminal Adapter → POS Terminal → Response → Webhook Callback