Search…
⌃K
Links

API

Authentication

You need to get your own api key from NearPay team and you can set it every request header

Merchants

to manage your merchants , you can add or list merchants

POST Create Merchant

https://sandbox-api.nearpay.io/v1/clients-sdk/merchants

Headers

api-key String Required

BODY raw

{
"name": "nearpay's store",
"name_ar": "متجر نيرباي",
"reference_id": "01112"// you can add a refrence number here
}
{
"id": "7e87b216-715c-4357-bb86-a3c40ce0342e",
"name": "nearpay's store",
"name_ar": "متجر نيرباي",
"reference_id": "01112",
"user": {}
}

GET List Merchants

https://sandbox-api.nearpay.io/v1/clients-sdk/merchants

Headers

api-key String Required

Parameters

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
}

GET Find Merchant

https://sandbox-api.nearpay.io/v1/clients-sdk/merchants/{id}

Headers

api-key String Required
{
"id": "c10f260e-1a14-4602-a3b2-f2b5e128d8f6",
"name": "nearpay's store",
"name_ar": "متجر نيرباي",
"reference_id": "01112",
"created_at": "2022-10-20T13:18:04.892Z"
}

Users

You can manage users and assign them to terminals.

POST Assign Terminal

https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal_id}/assign

Headers

api-key String Required

Body raw

{
"name": "nearpay's store",
"mobile": "+966500000000",
"email": "[email protected]"
}
"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
}
}

PUT UnAssign Terminal

https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal_id}/unassign

Headers

api-key String Required
{
"terminal": {
"id": "3011473a-5784-4ea8-983a-d7a1d9a315da",
"tid": "0200010400000104",
"merchant": {
"name": "nearpay's store",
"name_ar": "nearpay's store"
},
"user": null,
"device": null,
"is_connected": false,
"is_assigned_to_user": false
}
}

Terminals

you can manage your terminals throw api you can register new terminal or even list them.

POST Create Terminals

https://sandbox-api.nearpay.io/v1/clients-sdk/terminals

Headers

api-key String Required

Body raw

{
"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"
}
}

GET List Terminals

https://sandbox-api.nearpay.io/v1/clients-sdk/terminals

Headers

api-key String Required

Parameters

Query

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
}
}

GET Find Terminal

https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal id}

Headers

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
}
}

PUT Disconnect Terminal

https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal id}/disconnect

Headers

api-key String Required
{
"message": "Terminal disconnected successfully!"
}

Create Session

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.

POST Create Session

https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal id}/sessions

Headers

api-key String Required

Body raw

{
"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"
}

GET List Sessions

https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal id}/sessions

Headers

api-key String Required

Parameters

Query

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": "921d95d5-9319-423d-8d12-714ad15e913b",
"status": "new",
"type": "purchase",
"client_id": "6d92404e-d5ff-4fcd-8590-548a54657450",
"amount": "9",
"expired_at": "1674384544302",
"reference_id": null,
"created_at": "2023-01-22T10:39:04.301Z",
"updated_at": "2023-01-22T10:39:04.301Z",
"original_transaction": null,
"transaction": null
}
],
"pages": {
"total": 1,
"current": 1
}
}
```

GET Find Sessions

https://sandbox-api.nearpay.io/v1/clients-sdk/terminals/{terminal id}/sessions/{session_id}}

Headers

api-key String Required
{
"session": {
"id": "d375f694-da43-4f5d-4436-15706821bd6d",
"status": "new",
"type": "purchase",
"client_id": "6d92404e-d5ff-4fcd-3987-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",
"transaction": null,
"original_transaction": null
}
}

Transactions

you can view all terminals transactions or just one transactions.

GET List Transactions

https://sandbox-api.nearpay.io/v1/clients-sdk/transactions

Headers

api-key String Required

Parameters

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,
"is_refunded": false,
"is_reversed": false,
"approval_code": {
"value": "446478",
"label": {
"arabic": "رمز الموافقة",
"english": "Approval Code"
}
},
"verification_method": {
"english": "DEVICE OWNER IDENTITY VERIFIED",
"arabic": "تم التحقق من هوية حامل الجهاز "
},
"end_date": "17/10/2022",
"end_time": "17:23:13",
"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": "DAE70C33DF1655BF",
"kernel_id": "03",
"payment_account_reference": "",
"pan_suffix": "1234",
"transaction_uuid": "cd10c49c-ab61-4214-9e5c-022985b73110",
"created_at": "2022-10-19T15:45:20.041Z",
"updated_at": "2022-10-19T15:45:20.041Z",
"qr_code": "https://staging-api.nearpay.io/ui/receipt/cd10c49c-ab61-4214-9e5c-022985b73110"
}
]
},
{
"id": "5b8dd6a3-384a-4f6f-a6bf-864bcbae5573",
"device": {
"id": "f9425dca-cfa4-4dac-811f-fdceb5ff871c",
"status": "new",
"type": "phone"
},
"merchant": {
"id": "01b22f94-f8f3-41c6-aa58-304005acaa44",
"name": "api test",
"name_ar": "api test"
},
"user": null,
"receipts": [
{
"id": "dc15595a-137d-4e9f-8af8-b783a86822d6",
"merchant": {
"id": "000000000000001",
"name": {
"arabic": "123455",
"english": "NearPay-Test Terminal INMA"
},
"address": {
"arabic": "4321",
"english": "KAFD"
},
"category_code": "0763"
},
"type": "purchase",
"start_date": "18/10/2022",
"start_time": "07:08:00",
"card_scheme_sponsor": "INMA",
"tid": "0000000000000019",
"system_trace_audit_number": "000078",
"pos_software_version_number": "1.0.0",
"retrieval_reference_number": "000000000030",
"card_scheme": {
"name": {
"english": "Visa",
"arabic": "فيزا"
},
"id": "VC"
},
"transaction_type": {
"name": {
"arabic": "شراء",
"english": "PURCHASE"
},
"id": "00"
},
"pan": "4829 15** **** 3969",
"card_expiration": "23/12",
"amount_authorized": {
"label": {
"arabic": "مبلغ الشراء",
"english": "PURCHASE AMOUNT"
},
"value": "0.01"
},
"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": "222960",
"label": {
"arabic": "رمز الموافقة",
"english": "Approval Code"
}
},
"verification_method": {
"english": "DEVICE OWNER IDENTITY VERIFIED",
"arabic": "تم التحقق من هوية حامل الجهاز "
},
"end_date": "18/10/2022",
"end_time": "07:08:00",
"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": "78EF8ED388D49CD6",
"kernel_id": "03",
"payment_account_reference": "",
"pan_suffix": "1234",
"transaction_uuid": "5b8dd6a3-384a-4f6f-a6bf-864bcbae5573",
"created_at": "2022-10-19T15:45:20.041Z",
"updated_at": "2022-10-19T15:45:20.041Z",
"qr_code": "https://staging-api.nearpay.io/ui/receipt/5b8dd6a3-384a-4f6f-a6bf-864bcbae5573"
}
]
}
]
}

GET FindTransaction

https://sandbox-api.nearpay.io/v1/clients-sdk/transactions/{UUID}

Headers

api-key String Required
{
"transaction": {
"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": "+96650555555",
"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,
"is_refunded": false,
"is_reversed": false,
"approval_code": {
"value": "446478",
"label": {
"arabic": "رمز الموافقة",
"english": "Approval Code"
}
},
"verification_method": {
"english": "DEVICE OWNER IDENTITY VERIFIED",
"arabic": "تم التحقق من هوية حامل الجهاز "
},
"end_date": "17/10/2022",
"end_time": "17:23:13",