Use the NamiPay Cloud Middleware to integrate payment acceptance into POS applications via secure REST APIs.
This guide provides step‑by‑step instructions for:

• Authentication and credential management
• Merchant and terminal registration
• Webhook setup
• Transaction execution
• Response handling

For environment setup and SDK details, refer to the Cloud Middleware Library.

Supported Connections

Transaction Flow

Initialize Middleware → Authenticate → Register Merchant → Register Terminal → Configure Webhook → Execute Transaction → Receive Response → Parse Response

Integration Steps

Step 1: Authenticate

Use the following code to obtain an access token with client credentials.

Request:

POST /api/auth/getToken

Payload:

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI..."
}

Step 2: Register Merchant

Use the following code to register a merchant in the NamiPay system.

Request:

POST /api/merchants  [AUTH]

Payload:

{
  "merchantName": "ABC Store",
  "merchantId": "M123456"
}

Step 3: Register Terminal

Use the following code to register a POS terminal.

Request:

POST /api/terminals/register  [AUTH]
Content-Type: application/json
Authorization: Bearer <accessToken>

Payload:

{
  "terminalId": "T987654",
  "merchantId": "M123456"
}

Step 4: Configure Webhook

Use the following code to generate and register a webhook for transaction callbacks.

Request:

POST /api/webhooks/generate-url  [AUTH]
POST /api/webhooks/register      [AUTH]
Content-Type: application/json
Authorization: Bearer <accessToken>

Payload:

{
  "callbackUrl": "https://your-pos-app.com/webhook",
  "merchantId": "M123456"
}

Step 5: Execute Transaction

Use the following code to perform a transaction.

Request:

POST /api/payments/performTransaction/{terminalId}  [AUTH]
Content-Type: application/json
Authorization: Bearer <accessToken>

Payload (Purchase):

{
  "transactionType": "PURCHASE",
  "amount": "10000",
  "currency": "SAR",
  "ecrReferenceNo": "TX12345678",
  "dateTimeStamp": "140524193012"
}

Step 6: Process Response

Use the following code to parse the JSON response returned by the middleware.

Response Example:

{
  "responseCode": "00",
  "approvalCode": "APPROVED",
  "amount": "10000",
  "timestamp": "140524193012",
  "ecrRefNo": "TX12345678",
  "receiptData": "RECEIPT123"
}

Parsed Output Mapping:

• Response Code → 00 (Approved)
• Approval Code → APPROVED
• Amount → 10000 (minor units)
• Timestamp → 140524193012
• ECR Reference No → TX12345678
• Receipt Data → RECEIPT123

Key Rules

• Always call getToken first; tokens expire after 24 hours.
• PURCHASE is the end‑to‑end payment flow.
• Other transaction types (Refund, Reversal, Reconciliation, etc.) are supported via the same endpoint.
• Webhooks must be configured to receive signed callbacks.

Final Integration Flow

Authenticate (getToken)
↓
Register Merchant
↓
Register Terminal
↓
Configure Webhook
↓
Execute Transaction (performTransaction)
↓
Receive Response (JSON payload)
↓
Parse Response (map fields)

Installation Notes

• Requires Windows 10+ or server environment with HTTPS access.
• Requires JRE 8+ if running middleware locally.
• POS must have valid Client ID/Secret.
• Webhook endpoint must be reachable and secured (HTTPS).