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:
-
Authenticate using JWT.
-
Perform operations.
Generate JWT
To connect your user device to Nearpay Terminal, use your backend to sign the JWT with the following data:
- Login to Nearpay Merchant Dashboard.
- Go to the credentials page.
- 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
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",
"customer_reference_number":"1234"
}
{
"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",
"customer_reference_number":"1234"
}
{
"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": ""
}