Nearpay Remote Operations

this will explain how to connect a Nearpay terminal and perform remote operations using http request.

To use Nearpay's remote operations, follow these two main steps:

  1. Authenticate using JWT.

  2. Perform operations.

Generate JWT

To connect your user device to Nearpay Terminal, use your backend to sign the JWT with the following data:

  1. Login to Nearpay Merchant Dashboard.
  2. Go to the credentials page.
  3. You will find the following:
    • Merchant UUID
    • JWT Key: Once you click generate, it will download "Downloaded once" a file which is the private key (pos_key.pem) that you will use to sign the JWT.

for terminal_id, you can find all the terminals you have on the terminals page.

import * as fs from 'fs';
import * as jwt from 'jsonwebtoken';

function getToken() {
  var privateKey: Buffer = fs.readFileSync('./pos_key.pem');

  var terminal: any = {
    data: {
      ops: "auth",
      merchant_uuid: "<merchant_uuid>", 
      terminal_id: "PS239210" // get this number from terminal page which is (Tid)
    }
  }

  return jwt.sign(terminal, privateKey, {
    algorithm: "RS256"
  });
}

Enable the remote mode in the app

To enable that you should go to settings in the side menu and then select the remote mode

Remote Flow

Can't Load...
Can't Load...
Can't Load...

Base URL

https://sandbox-api.nearpay.io/proxy/operations/ 
POST/pair/jwt

Authentication

In this endpoint you will be able to create room id and token. This is a one-time process per session. Once authenticated, you will receive room_id and token . These values must be used in remote operations and should be cached to avoid repeating the JWT generation process.

Request

POST
/pair/jwt
{
  "jwt": "eyJhbGciOiJSUzI1"  
}

Response 201

  {
      "room_id": "<room_id>",
      "token": "<token>"
  }

POST/ping

Ping

In this endpoint you will be able to check if the connection is stable or not.

Request

POST
/ping
{
  "timeout":5000
}

POST/cancel

Cancel

In this endpoint you will be able to cancel the current transaction that running in SoftPOS.

Request

POST
/cancel
{}
{
  "command": 8,
  "status": 1,
  "message": ""
}

DELETE/delete

Delete

In this endpoint you will delete the current room running between Server and SoftPOS.

Request

DELETE
/delete
{}
{
  "command": 11,
  "status": 1
}

POST/purchase

Purchase

In this endpoint you will be able to perform a purchase operation on the connected terminal.

Request

POST
/purchase
{ 
  "amount": 700, 
  "jobId":"8758f786-2376-4bc8-801c-16e0c96266c3"
}
{
  "command": 0,
  "status": 1,
  "transactionReceipts": [
      {
          "id": "a1394f90-a58d-4154-b734-4d30a1f7cf8b",
          "merchant": {
              "id": "100000000000001",
              "name": {
                  "arabic": "NearPay Merchant Arabic",
                  "english": "NearPay Merchant"
              },
              "address": {
                  "arabic": "4321",
                  "english": "KAFD"
              },
              "category_code": "0763"
          },
          "start_date": "30/06/2025",
          "start_time": "10:29:51",
          "card_scheme_sponsor": "INMA",
          "tid": "0211263600112636",
          "system_trace_audit_number": "000590",
          "pos_software_version_number": "1.0.0",
          "retrieval_reference_number": "556679000000",
          "card_scheme": {
              "name": {
                  "arabic": "فيزا",
                  "english": "Visa"
              },
              "id": "VC"
          },
          "transaction_type": {
              "name": {
                  "arabic": "شراء",
                  "english": "PURCHASE"
              },
              "id": "00"
          },
          "pan": "4829 15** **** 0935",
          "card_expiration": "29/03",
          "amount_authorized": {
              "label": {
                  "arabic": "مبلغ الشراء",
                  "english": "PURCHASE AMOUNT"
              },
              "value": "7.00"
          },
          "amount_other": {
              "label": {
                  "arabic": "مبلغ النقد",
                  "english": "NAQD AMOUNT"
              },
              "value": "0.00"
          },
          "currency": {
              "arabic": "ر.س",
              "english": "SAR"
          },
          "status_message": {
              "arabic": "مقبولة",
              "english": "Approved"
          },
          "is_approved": true,
          "is_refunded": false,
          "is_reversed": false,
          "approval_code": {
              "label": {
                  "arabic": "رمز الموافقة",
                  "english": "Approval Code"
              },
              "value": "196689"
          },
          "verification_method": {
              "arabic": "تم التحقق من هوية حامل الجهاز ",
              "english": "DEVICE OWNER IDENTITY VERIFIED"
          },
          "end_date": "30/06/2025",
          "end_time": "10:29:51",
          "receipt_line_one": {
              "arabic": "",
              "english": ""
          },
          "receipt_line_two": {
              "arabic": "",
              "english": ""
          },
          "thanks_message": {
              "arabic": "شكرا لاستخدامكم مدى",
              "english": "Thank you for using mada"
          },
          "save_receipt_message": {
              "arabic": "يرجى الاحتفاظ بالفاتورة",
              "english": "please retain receipt"
          },
          "entry_mode": "CONTACTLESS",
          "action_code": "000",
          "application_identifier": "A0000000031010",
          "terminal_verification_result": "2480400080",
          "transaction_state_information": "0000",
          "cardholader_verfication_result": "1F0000",
          "cryptogram_information_data": "80",
          "application_cryptogram": "BD40C0F0B6C30DB3",
          "kernel_id": "03",
          "payment_account_reference": "V0010013021088567550590138607",
          "pan_suffix": "",
          "created_at": "",
          "updated_at": "",
          "qr_code": "https://sandbox-api.nearpay.io/ui/receipt/a1394f90-a58d-4154-b734-4d30a1f7cf8b",
          "transaction_uuid": "7038ae84-9b33-4585-814e-e2243bd3c3a5",
          "customer_reference_number": null,
          "vas_data": null
      }
  ],
  "message": "",
  "isNewTransaction": null
}

POST/refund

Refund

In this endpoint you will be able to perform a refund operation for a previous purchase on the connected terminal.

Request

POST
/refund
{ 
  "amount": 700, 
  "original_transaction_uuid":"7038ae84-9b33-4585-814e-e2243bd3c3a5",
  "jobId":"8758f786-2376-4bc8-801c-16e0c96266c3"
}
{
  "command": 1,
  "status": 1,
  "transactionReceipts": [
      {
          "id": "f352420f-9fea-4f3c-a429-2402045cf696",
          "merchant": {
              "id": "100000000000001",
              "name": {
                  "arabic": "NearPay Merchant Arabic",
                  "english": "NearPay Merchant"
              },
              "address": {
                  "arabic": "4321",
                  "english": "KAFD"
              },
              "category_code": "0763"
          },
          "start_date": "30/06/2025",
          "start_time": "11:36:34",
          "card_scheme_sponsor": "INMA",
          "tid": "0211263600112636",
          "system_trace_audit_number": "000596",
          "pos_software_version_number": "1.0.0",
          "retrieval_reference_number": "556686000000",
          "card_scheme": {
              "name": {
                  "arabic": "فيزا",
                  "english": "Visa"
              },
              "id": "VC"
          },
          "transaction_type": {
              "name": {
                  "arabic": "استرداد",
                  "english": "REFUND"
              },
              "id": "20"
          },
          "pan": "4829 15** **** 0935",
          "card_expiration": "29/03",
          "amount_authorized": {
              "label": {
                  "arabic": "المبلغ المسترد",
                  "english": "REFUND AMOUNT"
              },
              "value": "7.00"
          },
          "amount_other": {
              "label": {
                  "arabic": "مبلغ النقد",
                  "english": "NAQD AMOUNT"
              },
              "value": "0.00"
          },
          "currency": {
              "arabic": "ر.س",
              "english": "SAR"
          },
          "status_message": {
              "arabic": "مقبولة",
              "english": "Approved"
          },
          "is_approved": true,
          "is_refunded": false,
          "is_reversed": false,
          "approval_code": {
              "label": {
                  "arabic": "رمز الموافقة",
                  "english": "Approval Code"
              },
              "value": "418625"
          },
          "verification_method": {
              "arabic": "لا يتطلب التحقق",
              "english": "NO VERIFICATION REQUIRED"
          },
          "end_date": "30/06/2025",
          "end_time": "11:36:34",
          "receipt_line_one": {
              "arabic": "",
              "english": ""
          },
          "receipt_line_two": {
              "arabic": "",
              "english": ""
          },
          "thanks_message": {
              "arabic": "شكرا لاستخدامكم مدى",
              "english": "Thank you for using mada"
          },
          "save_receipt_message": {
              "arabic": "يرجى الاحتفاظ بالفاتورة",
              "english": "please retain receipt"
          },
          "entry_mode": "CONTACTLESS",
          "action_code": "000",
          "application_identifier": "A0000000031010",
          "terminal_verification_result": "2480400080",
          "transaction_state_information": "0000",
          "cardholader_verfication_result": "1F0000",
          "cryptogram_information_data": "00",
          "application_cryptogram": "DBAC5128796F417E",
          "kernel_id": "03",
          "payment_account_reference": "V0010013021088567550590138607",
          "pan_suffix": "",
          "created_at": "",
          "updated_at": "",
          "qr_code": "https://sandbox-api.nearpay.io/ui/receipt/f352420f-9fea-4f3c-a429-2402045cf696",
          "transaction_uuid": "e99c5ae1-e8e6-48fc-a7a0-9fb98d6cb05c",
          "customer_reference_number": null,
          "vas_data": null
      }
  ],
  "message": ""
}

POST/reverse

Reverse

In this endpoint you will be able to perform a reverse operation for a previous purchase or refund transaction on the connected terminal.

Request

POST
/reverse
{ 
  "transaction_uuid":"1b29d05f-d187-47cf-b684-3f21881a0d2a"
}
{
  "command": 3,
  "status": 1,
  "transactionReceipts": [
      {
          "id": "883aae30-956e-4759-b883-a22fe074e8c0",
          "merchant": {
              "id": "100000000000001",
              "name": {
                  "arabic": "NearPay Merchant Arabic",
                  "english": "NearPay Merchant"
              },
              "address": {
                  "arabic": "4321",
                  "english": "KAFD"
              },
              "category_code": "0763"
          },
          "start_date": "01/07/2025",
          "start_time": "11:47:36",
          "card_scheme_sponsor": "INMA",
          "tid": "0211263600112636",
          "system_trace_audit_number": "000601",
          "pos_software_version_number": "1.0.0",
          "retrieval_reference_number": "556933000000",
          "card_scheme": {
              "name": {
                  "arabic": "فيزا",
                  "english": "Visa"
              },
              "id": "VC"
          },
          "transaction_type": {
              "name": {
                  "arabic": "شراء",
                  "english": "PURCHASE"
              },
              "id": "00"
          },
          "pan": "4829 15** **** 0935",
          "card_expiration": "29/03",
          "amount_authorized": {
              "label": {
                  "arabic": "مبلغ الشراء",
                  "english": "PURCHASE AMOUNT"
              },
              "value": "7.00"
          },
          "amount_other": {
              "label": {
                  "arabic": "مبلغ النقد",
                  "english": "NAQD AMOUNT"
              },
              "value": "0.00"
          },
          "currency": {
              "arabic": "ر.س",
              "english": "SAR"
          },
          "status_message": {
              "arabic": "مقبولة",
              "english": "Approved"
          },
          "is_approved": true,
          "is_refunded": false,
          "is_reversed": false,
          "approval_code": {
              "label": {
                  "arabic": "رمز الموافقة",
                  "english": "Approval Code"
              },
              "value": "647331"
          },
          "verification_method": {
              "arabic": "تم التحقق من هوية حامل الجهاز ",
              "english": "DEVICE OWNER IDENTITY VERIFIED"
          },
          "end_date": "01/07/2025",
          "end_time": "11:47:36",
          "receipt_line_one": {
              "arabic": "",
              "english": ""
          },
          "receipt_line_two": {
              "arabic": "",
              "english": ""
          },
          "thanks_message": {
              "arabic": "شكرا لاستخدامكم مدى",
              "english": "Thank you for using mada"
          },
          "save_receipt_message": {
              "arabic": "يرجى الاحتفاظ بالفاتورة",
              "english": "please retain receipt"
          },
          "entry_mode": "CONTACTLESS",
          "action_code": "000",
          "application_identifier": "A0000000031010",
          "terminal_verification_result": "2480400080",
          "transaction_state_information": "0000",
          "cardholader_verfication_result": "1F0000",
          "cryptogram_information_data": "80",
          "application_cryptogram": "D6D3ECDEAD65A792",
          "kernel_id": "03",
          "payment_account_reference": "V0010013021088567550590138607",
          "pan_suffix": "",
          "created_at": "",
          "updated_at": "",
          "qr_code": "https://sandbox-api.nearpay.io/ui/receipt/883aae30-956e-4759-b883-a22fe074e8c0",
          "transaction_uuid": "1b29d05f-d187-47cf-b684-3f21881a0d2a",
          "customer_reference_number": null,
          "vas_data": null
      },
      {
          "id": "13a0236f-de51-4a1d-a8c9-43adad100293",
          "merchant": {
              "id": "100000000000001",
              "name": {
                  "arabic": "NearPay Merchant Arabic",
                  "english": "NearPay Merchant"
              },
              "address": {
                  "arabic": "4321",
                  "english": "KAFD"
              },
              "category_code": "0763"
          },
          "start_date": "01/07/2025",
          "start_time": "11:48:14",
          "card_scheme_sponsor": "INMA",
          "tid": "0211263600112636",
          "system_trace_audit_number": "000602",
          "pos_software_version_number": "1.0.0",
          "retrieval_reference_number": "556933000000",
          "card_scheme": {
              "name": {
                  "arabic": "فيزا",
                  "english": "Visa"
              },
              "id": "VC"
          },
          "transaction_type": {
              "name": {
                  "arabic": "عملية معكوسة",
                  "english": "REVERSAL"
              },
              "id": "00"
          },
          "pan": "4829 15** **** 0935",
          "card_expiration": "29/03",
          "amount_authorized": {
              "label": {
                  "arabic": "المبلغ الملغي",
                  "english": "REVERSED AMOUNT"
              },
              "value": "7.00"
          },
          "amount_other": {
              "label": {
                  "arabic": "مبلغ النقد",
                  "english": "NAQD AMOUNT"
              },
              "value": "0.00"
          },
          "currency": {
              "arabic": "ر.س",
              "english": "SAR"
          },
          "status_message": {
              "arabic": "مستلمة",
              "english": "ACCEPTED"
          },
          "is_approved": false,
          "is_refunded": false,
          "is_reversed": true,
          "approval_code": null,
          "verification_method": {
              "arabic": "تم التحقق من هوية حامل الجهاز ",
              "english": "DEVICE OWNER IDENTITY VERIFIED"
          },
          "end_date": "01/07/2025",
          "end_time": "11:48:14",
          "receipt_line_one": {
              "arabic": "",
              "english": ""
          },
          "receipt_line_two": {
              "arabic": "",
              "english": ""
          },
          "thanks_message": {
              "arabic": "شكرا لاستخدامكم مدى",
              "english": "Thank you for using mada"
          },
          "save_receipt_message": {
              "arabic": "يرجى الاحتفاظ بالفاتورة",
              "english": "please retain receipt"
          },
          "entry_mode": "CONTACTLESS",
          "action_code": "400",
          "application_identifier": "A0000000031010",
          "terminal_verification_result": "2480400080",
          "transaction_state_information": "0000",
          "cardholader_verfication_result": "1F0000",
          "cryptogram_information_data": "80",
          "application_cryptogram": "D6D3ECDEAD65A792",
          "kernel_id": "03",
          "payment_account_reference": "V0010013021088567550590138607",
          "pan_suffix": "",
          "created_at": "",
          "updated_at": "",
          "qr_code": "https://sandbox-api.nearpay.io/ui/receipt/13a0236f-de51-4a1d-a8c9-43adad100293",
          "transaction_uuid": "1b29d05f-d187-47cf-b684-3f21881a0d2a",
          "customer_reference_number": null,
          "vas_data": null
      }
  ],
  "message": ""
}