API
You need to get your own api key from NearPay team and you can set it every request header
to manage your merchants , you can add or list merchants
https://sandbox-api.nearpay.io/v1/clients-sdk/merchants
api-key String Required
{
"name": "nearpay's store",
"name_ar": "متجر نيرباي",
"reference_id": "01112"// you can add a refrence number here
"user": {
"name": "Nearpay",
"email": "[email protected]",
"mobile": "+966555555555"
}
}
{
"id": "7e87b216-715c-4357-bb86-a3c40ce0342e",
"name": "nearpay's store",
"name_ar": "متجر نيرباي",
"reference_id": "01112",
"user": {
"id": "a7f45b45-cde5-4e56-be5c-e06021485c22",
"name": "Nearpay",
"mobile": "+966555555555",
"email": "[email protected]"
}
}
https://sandbox-api.nearpay.io/v1/clients-sdk/merchants
api-key String Required
Query
page number
limit number
{
"merchants": [
{
"id": "7e87b216-715c-4357-bb86-a3c40ce0342e",
"name": "nearpay's store",
"name_ar": "متجر نيرباي",
"reference_id": "01112",
"created_at": "2022-11-16T06:44:58.595Z"
},
{
"id": "0727ee2f-9c46-4ad1-a42c-d5d713ebfb51",
"name": "nearpay's store",
"name_ar": "متجر نيرباي",
"reference_id": "",
"created_at": "2022-08-23T08:17:50.702Z"
}
],
"pages": 1
}
https://sandbox-api.nearpay.io/v1/clients-sdk/merchants/{id}
api-key String Required
You can manage users and assign them to terminals.
https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal_id}/assign
api-key String Required
"terminal": {
"id": "3011473a-5784-4ea8-983a-d7a1d9a315da",
"tid": "0200010400000104",
"merchant": {
"name": "nearpay's store",
"name_ar": "nearpay's store"
},
"user": {
"id": "3a6e9685-8325-4844-8584-61fd022f52ad",
"name": "nearpay user",
"mobile": "+966500000000",
"email": "[email protected]"
},
"device": {},
"is_connected": false,
"is_assigned_to_user": true
}
}
https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal_id}/unassign
api-key String Required
you can manage your terminals throw api you can register new terminal or even list them.
https://sandbox-api.nearpay.io/v1/clients-sdk/terminals
api-key String Required
{
"trsm_code": "000112",
"merchant_id": "01b22f94-f8f3-41c6-aa58-304005acaa44"
}
{
"merchant": {
"id": "01b22f94-f8f3-41c6-aa58-304005acaa44",
"name": "api test",
"name_ar": "api test",
"reference_id": null,
"status": "active",
"created_at": "2022-10-19T15:40:02.743Z",
"updated_at": "2022-10-19T15:40:02.743Z"
},
"terminal": {
"id": "d02c4c62-6a77-41ad-995d-b3f32645a19b",
"tid": "0000000000000031",
"user": {
"id": "df3aef9e-60a3-465a-8373-cdbaa2fd2c35",
"name": "nearpay",
"mobile": "+966500000000",
"email": "[email protected]",
"is_active": true,
"is_email_verified": true,
"is_mobile_verified": true,
"created_at": "2022-10-19T15:40:02.743Z",
"updated_at": "2022-10-19T15:40:02.743Z"
},
"device": {
"id": "ba020c3f-bcf2-4e5f-bb1d-e67d1c5e33ed",
"publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQl5wYhK\n7QIDAQAB\n-----END PUBLIC KEY-----\n",
"location": null,
"lat": null,
"lon": null,
"status": "new",
"deviceType": "phone",
"is_active": true,
"created_at": "2022-10-19T15:40:02.743Z",
"updated_at": "2022-10-19T15:40:02.743Z"
},
"created_at": "2022-10-19T15:40:02.743Z",
"updated_at": "2022-10-19T15:40:02.743Z"
}
}
https://sandbox-api.nearpay.io/v1/clients-sdk/terminals
api-key String Required
tid number
is_connected boolean(true or false)
is_assigned boolean(true or false)
page number
limit number
{
"terminals": [
{
"id": "c25b24b2-0ca9-4f81-a24e-5ae06b4e545a",
"tid": "0000000000000024",
"merchant": {
"id": "01b22f94-f8f3-41c6-aa58-304005acaa44",
"name": "api test",
"name_ar": "api test"
},
"user": {
"id": "571da042-c806-40ce-8397-57d52351bbdf",
"name": "nearpay",
"mobile": "+966555555555",
"email": "[email protected]"
},
"device": null,
"is_assigned_to_user": true,
"is_connected": false,
"created_at": "2022-10-19T15:40:02.743Z",
"updated_at": "2022-10-20T07:11:45.350Z"
},
{
"id": "1c94a589-54c1-446e-afda-17634b4ca426",
"tid": "0000000000000011",
"merchant": {
"id": "01b22f94-f8f3-41c6-aa58-304005acaa44",
"name": "api test",
"name_ar": "api test"
},
"user": null,
"device": {
"id": "516e89aa-bd38-42d9-9b18-c00b5fa2dfb5",
"status": "new",
"deviceType": "phone"
},
"is_assigned_to_user": false,
"is_connected": true,
"created_at": "2022-10-19T15:40:02.743Z",
"updated_at": "2022-10-19T15:40:02.743Z"
}
],
"pages": {
"total": 1,
"current": 1
}
}
https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal id}
api-key String Required
{
"terminal": {
"id": "c25b24b2-0ca9-4f81-a24e-5ae06b4e545a",
"tid": "0000000000000024",
"merchant": {
"id": "01b22f94-f8f3-41c6-aa58-304005acaa44",
"name": "api test",
"name_ar": "api test"
},
"user": {
"id": "571da042-c806-40ce-8397-57d52351bbdf",
"name": "nearpay",
"mobile": "+96655555555",
"email": "[email protected]"
},
"device": null,
"is_connected": false,
"is_assigned_to_user": true
}
}
https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal id}/disconnect
api-key String Required
Create session is used to open a session that allow your user to make transaction ,it's used to validate that the session is done and mobile users can not make another transaction till another session is created.
https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal id}/sessions
api-key String Required
{
"type": "purchase",
"amount": 40
}
{
"status": "new",
"type": "purchase",
"client_id": "6d92404e-d5ff-4fcd-6553-548a54657450",
"amount": 40,
"terminal": {
"id": "5d2501a3-1a75-4f70-6553-c8369f10b065"
},
"original_transaction": {},
"expired_at": 1674383924746,
"reference_id": null,
"id": "c049bfad-fdda-4a42-6553-e1cd35a77813",
"created_at": "2023-01-22T10:28:44.745Z",
"updated_at": "2023-01-22T10:28:44.745Z"
}
https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal id}/sessions
api-key String Required
page number
limit number
{
"sessions": [
{
"id": "d375f694-da43-4f5d-88c4-15706821bd6d",
"status": "new",
"type": "purchase",
"client_id": "6d92404e-d5ff-4fcd-8590-548a54657450",
"amount": "40",
"expired_at": "1674380418962",
"reference_id": null,
"created_at": "2023-01-22T09:30:18.962Z",
"updated_at": "2023-01-22T09:30:18.962Z",
"original_transaction": null,
"transaction": null
},
{
"id": "00c0e5e3-48ac-45d6-9b3d-164070aac485",
"status": "closed",
"type": "purchase",
"client_id": "6d92404e-d5ff-4fcd-8590-548a54657450",
"amount": "5000",
"expired_at": "1676805924069",
"reference_id": null,
"created_at": "2023-02-19T11:15:24.068Z",
"updated_at": "2023-02-19T11:20:03.927Z",
"original_transaction": null,
"transaction": {
"id": "8568",
"uuid": "12e4953c-0b8c-4c90-ba1c-aa126010edde",
"amount_authorized": "5000",
"transaction_currency_code": "000",
"cardholder_verification_result": "00",
"lat": "24.8037412",
"lon": "46.6051712",
"transaction_type": "00",
"card_scheme_id": "P1",
"system_trace_audit_number": "000000",
"is_approved": true,
"is_reversed": false,
"is_reconcilied": true,
"device_id": "c6042bdb-3fe5-4e27-b9f6-a13cce023415",
"user_id": "a7f45b45-cde5-4e56-be5c-e06021485c22",
"merchant_id": "a33d09d3-3a8e-4680-86c2-bc91713b7b79",
"customer_reference_number": null,
"pos_confirmed": true,
"created_at": "2023-02-19T11:20:03.880Z",
"updated_at": "2023-02-19T11:20:13.372Z",
"receipts": [
{
"id": "9bf0fc82-f1d0-4c85-ad4e-a4d1c6266ff8",
"merchant": {
"id": "100000000000001",
"name": {
"arabic": "123455",
"english": "NearPay-Test Terminal INMA"
},
"address": {
"arabic": "4321",
"english": "KAFD"
},
"category_code": "0763"
},
"type": "purchase",
"start_date": "19/02/2023",
"start_time": "14:20:03",
"card_scheme_sponsor": "INMA",
"tid": "0100009100000091",
"system_trace_audit_number": "000056",
"pos_software_version_number": "1.0.0",
"retrieval_reference_number": "000000008568",
"card_scheme": {
"name": {
"english": "mada",
"arabic": "مدى"
},
"id": "P1"
},
"transaction_type": {
"name": {
"arabic": "شراء",
"english": "PURCHASE"
},
"id": "00"
},
"pan": "5069 68** **** 4655",
"card_expiration": "24/04",
"amount_authorized": {
"label": {
"arabic": "مبلغ الشراء",
"english": "PURCHASE AMOUNT"
},
"value": "50.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": {
"value": "385890",
"label": {
"arabic": "رمز الموافقة",
"english": "Approval Code"
}
},
"verification_method": {
"english": "NO VERIFICATION REQUIRED",
"arabic": "لا يتطلب التحقق"
},
"end_date": "19/02/2023",
"end_time": "14:20:03",
"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": "A000000200010",
"terminal_verification_result": "0080008000",
"transaction_state_information": "0000",
"cardholader_verfication_result": "000000",
"cryptogram_information_data": "80",
"application_cryptogram": "D42C53D9D2DA92FA",
"kernel_id": "2d",
"payment_account_reference": "",
"pan_suffix": "",
"transaction_uuid": "12e4953c-0b8c-4c90-ba1c-aa126010edde",
"created_at": "2023-02-19T11:20:03.918Z",
"updated_at": "2023-02-19T11:20:03.918Z",
"qr_code": "https://staging-api.nearpay.io/ui/receipt/9bf0fc82-f1d0-4c85-ad4e-a4d1c6266ff8"
}
],
"card_scheme": {
"english": "mada",
"arabic": "مدى"
},
"type": {
"arabic": "شراء",
"english": "PURCHASE"
},
"verification_method": {
"english": "NO VERIFICATION REQUIRED",
"arabic": "لا يتطلب التحقق"
}
}
}
],
"pages": {
"total": 1,
"current": 1
}
}
```
https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal id}/sessions/{session_id}}
api-key String Required
{
"session": {
"id": "00c0e5e3-48ac-45d6-9b3d-164070aac485",
"status": "closed",
"type": "purchase",
"client_id": "6d92404e-d5ff-4fcd-8590-548a54657450",
"amount": "5000",
"expired_at": "1676805924069",
"reference_id": null,
"created_at": "2023-02-19T11:15:24.068Z",
"updated_at": "2023-02-19T11:20:03.927Z",
"transaction": {
"id": "8568",
"uuid": "12e4953c-0b8c-4c90-ba1c-aa126010edde",
"amount_authorized": "5000",
"transaction_currency_code": "000",
"cardholder_verification_result": "00",
"lat": "24.8037412",
"lon": "46.6051712",
"transaction_type": "00",
"card_scheme_id": "P1",
"system_trace_audit_number": "000000",
"is_approved": true,
"is_reversed": false,
"is_reconcilied": true,
"device_id": "c6042bdb-3fe5-4e27-b9f6-a13cce023415",
"user_id": "a7f45b45-cde5-4e56-be5c-e06021485c22",
"merchant_id": "a33d09d3-3a8e-4680-86c2-bc91713b7b79",
"customer_reference_number": null,
"pos_confirmed": true,
"created_at": "2023-02-19T11:20:03.880Z",
"updated_at": "2023-02-19T11:20:13.372Z",
"receipts": [
{
"id": "9bf0fc82-f1d0-4c85-ad4e-a4d1c6266ff8",
"merchant": {
"id": "100000000000001",
"name": {
"arabic": "123455",
"english": "NearPay-Test Terminal INMA"
},
"address": {
"arabic": "4321",
"english": "KAFD"
},
"category_code": "0763"
},
"type": "purchase",
"start_date": "19/02/2023",
"start_time": "14:20:03",
"card_scheme_sponsor": "INMA",
"tid": "0100009100000091",
"system_trace_audit_number": "000000",
"pos_software_version_number": "1.0.0",
"retrieval_reference_number": "000000000000",
"card_scheme": {
"name": {
"english": "mada",
"arabic": "مدى"
},
"id": "P1"
},
"transaction_type": {
"name": {
"arabic": "شراء",
"english": "PURCHASE"
},
"id": "00"
},
"pan": "5069 68** **** 4655",
"card_expiration": "24/04",
"amount_authorized": {
"label": {
"arabic": "مبلغ الشراء",
"english": "PURCHASE AMOUNT"
},
"value": "50.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": {
"value": "385890",
"label": {
"arabic": "رمز الموافقة",
"english": "Approval Code"
}
},
"verification_method": {
"english": "NO VERIFICATION REQUIRED",
"arabic": "لا يتطلب التحقق"
},
"end_date": "19/02/2023",
"end_time": "14:20:03",
"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": "A0000000000000",
"terminal_verification_result": "0080008000",
"transaction_state_information": "0000",
"cardholader_verfication_result": "000000",
"cryptogram_information_data": "80",
"application_cryptogram": "D42C53D9D2DA92FA",
"kernel_id": "2d",
"payment_account_reference": "",
"pan_suffix": "",
"transaction_uuid": "12e4953c-0b8c-4c90-ba1c-aa126010edde",
"created_at": "2023-02-19T11:20:03.918Z",
"updated_at": "2023-02-19T11:20:03.918Z",
"qr_code": "https://staging-api.nearpay.io/ui/receipt/9bf0fc82-f1d0-4c85-ad4e-a4d1c6266ff8"
}
],
"card_scheme": {
"english": "mada",
"arabic": "مدى"
},
"type": {
"arabic": "شراء",
"english": "PURCHASE"
},
"verification_method": {
"english": "NO VERIFICATION REQUIRED",
"arabic": "لا يتطلب التحقق"
}
},
"original_transaction": null
}
}
you can view all terminals transactions or just one transactions.
https://sandbox-api.nearpay.io/v1/clients-sdk/transactions
api-key String Required
Query
page number
limit number
tid number
from Timestamp in milliseconds
to Timestamp in milliseconds
{
"transactions": [
{
"id": "cd10c49c-ab61-4214-9e5c-022985b73110",
"device": {
"id": "85790240-c949-4f9f-baa0-4d3f6aaa1b63",
"status": "new",
"type": "phone"
},
"merchant": {
"id": "01b22f94-f8f3-41c6-aa58-304005acaa44",
"name": "api test",
"name_ar": "api test"
},
"user": {
"id": "95c91158-fc5e-47eb-ad6b-c3a0dc0a4ced",
"name": "Nearpay",
"mobile": "+966555555555",
"email": "[email protected]"
},
"receipts": [
{
"id": "d183262e-fcce-4672-a44f-1b24c9e6c24a",
"merchant": {
"id": "000000000000001",
"name": {
"arabic": "123455",
"english": "NearPay-Test Terminal INMA"
},
"address": {
"arabic": "4321",
"english": "KAFD"
},
"category_code": "0763"
},
"type": "purchase",
"start_date": "17/10/2022",
"start_time": "17:23:13",
"card_scheme_sponsor": "INMA",
"tid": "0000000000000018",
"system_trace_audit_number": "000046",
"pos_software_version_number": "1.0.0",
"retrieval_reference_number": "000000000001",
"card_scheme": {
"name": {
"english": "Visa",
"arabic": "فيزا"
},
"id": "VC"
},
"transaction_type": {
"name": {
"arabic": "شراء",
"english": "PURCHASE"
},
"id": "00"
},
"pan": "4941 46** **** 3714",
"card_expiration": "23/12",
"amount_authorized": {
"label": {
"arabic": "مبلغ الشراء",
"english": "PURCHASE AMOUNT"
},
"value": "5.00"
},
"amount_other": {
"label": {
"arabic": "مبلغ النقد",
"english": "NAQD AMOUNT"
},
"value": "0.00"
},
"currency": {
"arabic": "ر.س",
"english": "SAR"
},
"status_message": {
"arabic": "مقبولة",
"english": "Approved"
},
"is_approved": true,</