Vendor API
Warning: As a third party connected to nearpay APIs, upon usage, you agree to uphold the upmost security standards in accessing and using these APIs. These APIs share information that is confidential to you as a third party connected to nearpay. This information must be stored and used in a secure manner.
The Vendor API gives you the same data as the Accounts API, across all clients under your vendor ID.
Requests, responses, and IDs match the Accounts API. A terminal, transaction, or reconciliation ID from one API works in the other.
Every endpoint takes an optional client_id query parameter to limit results to one client.
Authentication
NearPay uses API key as an authentication method. The API key must be included in every request as an api-key header.
Your vendor API key is shared with you by NearPay. Send it in every request as the api-key header. You only get data for terminals under your vendor ID.
Base URL
https://sandbox-api.nearpay.io/v1/api/vendors/
Pagination
Please find the guide here in how to use pagination.
Terminals
List your terminals or view one terminal.
GET/terminals
List Terminals
Request
GET
/terminals{}
Response 200
{
"terminals": [
{
"id": "88d5425e-6b4d-448f-b7da-344e319f6aad",
"tid": "0200127500001275",
"name": "Main Counter",
"user": {
"id": "3a79a541-4c9a-4a93-b0e9-ecd6d05d3e19",
"name": "mohammed",
"mobile": "+9665******",
"email": "for**[email protected]"
},
"is_assigned_to_user": true,
"is_connected": true,
"profile": null,
"created_at": "2023-07-17T09:04:07.428Z",
"updated_at": "2023-08-17T08:19:17.622Z"
},
{
"id": "0c28a13e-ab64-4ad8-99ea-dae802be8080",
"tid": "0200120000001200",
"name": null,
"user": null,
"is_assigned_to_user": false,
"is_connected": false,
"profile": null,
"created_at": "2023-07-09T12:38:58.159Z",
"updated_at": "2023-07-30T15:25:07.693Z"
}
],
"pages": {
"total": 1,
"current": 1
}
}
GET/terminals/{terminal_id}
Find Terminal
Request
GET
/terminals/{terminal_id}{}
{
"terminal": {
"id": "16f4fe15-9d2c-4d32-b73d-630c5983a28d",
"tid": "0209221600092216",
"name": "Main Counter",
"user": {
"id": "676095e8-5a25-4a9c-a8a4-f32337a1329e",
"name": "shaker",
"mobile": "+96656*****",
"email": "a*****@nearpay.io"
},
"is_connected": true,
"connections": [
{
"id": "e44b2a5b-934f-4745-b7e2-45f93db7457a",
"device": {
"id": "760db1cd-77a9-4a1f-ab78-f1b0a71e4d91"
}
}
],
"is_assigned_to_user": true,
"profile": null
}
}
Transactions
List transactions or view one transaction in full.
GET/transactions
List Transactions
Request
GET
/transactions{}
Response 200
{
"transactions": [
{
"id": "f2190ab9-3048-4364-a6f7-ce3ce53a3b16",
"created_at": "2023-09-28T08:54:49.563Z",
"internet": {
"type": "wifi",
"speed": "271"
},
"is_reconcilied": false,
"terminal": {
"tid": "1881001155119328"
},
"device": {
"id": "c3ed2df1-ede2-402d-87d1-f0b59850f537",
"status": "new",
"type": "phone"
},
"user": {
"id": "ae65c798-73de-42be-ac4f-e884dc888000",
"name": "Adel Saeed",
"mobile": "+966508931611",
"email": "[email protected]"
},
"receipts": [
{
"id": "519a01ef-7c01-4a79-9b60-bc69a7cb2158",
"merchant": {
"id": "550100105798 ",
"name": {
"arabic": "شركة تباعد للاتصالات",
"english": "NEARPAY "
},
"address": {
"arabic": "أنس بن مالك",
"english": "Anas Ibn Malik"
},
"category_code": "8999"
},
"type": "purchase",
"start_date": "28/09/2023",
"start_time": "11:54:49",
"card_scheme_sponsor": "BSFB",
"tid": "1881001155119328",
"system_trace_audit_number": "000687",
"pos_software_version_number": "1.0.0",
"retrieval_reference_number": "871752000000",
"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": "0.01"
},
"currency": {
"arabic": "",
"english": "SAR"
},
"status_message": {
"arabic": "مرفوضة",
"english": "ERROR"
},
"is_approved": false,
"is_refunded": false,
"is_reversed": false,
"approval_code": null,
"end_date": "28/09/2023",
"end_time": "11:54:49",
"entry_mode": "CONTACTLESS",
"action_code": "940",
"transaction_uuid": "f2190ab9-3048-4364-a6f7-ce3ce53a3b16",
"created_at": "2023-09-28T08:54:49.647Z",
"updated_at": "2023-09-28T08:54:49.647Z",
"qr_code": "https://api.nearpay.io/ui/receipt/519a01ef-7c01-4a79-9b60-bc69a7cb2158"
// Other receipt fields, same as the Accounts API
}
],
"customer_reference_number": null,
"retrieval_reference_number": "871752000000",
"system_trace_audit_number": "000687",
"reconciliation": null,
"package_name": "io.nearpay.app",
"lat": "24.7136",
"lon": "46.6753"
},
// Other Transactions
],
"pages": {
"current": 1
}
}
GET/transactions/{transaction_id}
Find Transaction
Request
GET
/transactions/{transaction_id}{}
{
"transaction": {
"id": "f2190ab9-3048-4364-a6f7-ce3ce53a3b16",
"device": {
"id": "c3ed2df1-ede2-402d-87d1-f0b59850f537",
"status": "new",
"type": "phone"
},
"user": {
"id": "ae65c798-73de-42be-ac4f-e884dc888000",
"name": "Adel Saeed",
"mobile": "+966508931611",
"email": "[email protected]"
},
"terminal": {
"id": "16f4fe15-9d2c-4d32-b73d-630c5983a28d",
"tid": "1881001155119328"
},
"receipts": [
{
"id": "519a01ef-7c01-4a79-9b60-bc69a7cb2158",
"merchant": {
"id": "550100105798 ",
"name": {
"arabic": "شركة تباعد للاتصالات",
"english": "NEARPAY "
},
"address": {
"arabic": "أنس بن مالك",
"english": "Anas Ibn Malik"
},
"category_code": "8999"
},
"type": "purchase",
"start_date": "28/09/2023",
"start_time": "11:54:49",
"card_scheme_sponsor": "BSFB",
"tid": "1881001155119328",
"system_trace_audit_number": "000687",
"pos_software_version_number": "1.0.0",
"retrieval_reference_number": "871752000000",
"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": "0.01"
},
"currency": {
"arabic": "",
"english": "SAR"
},
"status_message": {
"arabic": "مرفوضة",
"english": "ERROR"
},
"is_approved": false,
"is_refunded": false,
"is_reversed": false,
"approval_code": null,
"end_date": "28/09/2023",
"end_time": "11:54:49",
"entry_mode": "CONTACTLESS",
"action_code": "940",
"transaction_uuid": "f2190ab9-3048-4364-a6f7-ce3ce53a3b16",
"created_at": "2023-09-28T08:54:49.647Z",
"updated_at": "2023-09-28T08:54:49.647Z",
"qr_code": "https://api.nearpay.io/ui/receipt/519a01ef-7c01-4a79-9b60-bc69a7cb2158"
// Other receipt fields, same as the Accounts API
}
],
"created_at": "2023-09-28T08:54:49.563Z",
"is_reconcilied": false,
"customer_reference_number": null,
"retrieval_reference_number": "871752000000",
"system_trace_audit_number": "000687",
"reconciliation": null,
"package_name": "io.nearpay.app",
"internet": {
"type": "wifi",
"speed": "271"
},
"lat": "24.7136",
"lon": "46.6753",
"transaction_type": "00",
"transaction_currency_code": "682",
"is_approved": false,
"is_reversed": false
}
}
Reconciliations
List reconciliations or view one reconciliation with its full receipt.
GET/reconciliations
List Reconciliations
Request
GET
/reconciliations{}
Response 200
{
"reconciliations": [
{
"id": "2fc49db4-7f86-4ad2-a7c3-877b10251ba3",
"created_at": "2023-11-19T08:05:54.550Z",
"terminal": {
"card_acceptor_terminal_id": "0209326800093268"
},
"reconciliation_receipt": {
"id": "2fc49db4-7f86-4ad2-a7c3-877b10251ba3",
"date": "19/11/2023",
"time": "11:05:54",
"start_date": "19/11/2023",
"start_time": "11:05:54",
"card_acceptor_terminal_id": "0209326800093268",
"pos_software_version_number": "1.0.0",
"is_balanced": {
"label": {
"arabic": "مقبولة",
"english": "Approved"
},
"value": true
},
"details": {
"total": {
"label": { "arabic": "المجموع", "english": "Total" },
"total": "0.00",
"count": 0
},
"purchase": {
"label": { "arabic": "الشراء", "english": "Purchase" },
"total": "0.00",
"count": 0
},
"purchase_reversal": {
"label": { "arabic": "الشراء المعكوسة", "english": "Purchase Reversal" },
"total": "0.00",
"count": 0
},
"refund": {
"label": { "arabic": "المستردة", "english": "Refund" },
"total": "0.00",
"count": 0
},
"refund_reversal": {
"label": { "arabic": "المستردة المعكوسة", "english": "Refund Reversal" },
"total": "0.00",
"count": 0
}
},
"schemes": [
{
"name": {
"label": { "english": "mada", "arabic": "مدى" },
"value": "P1"
},
"pos": {
"credit": {
"label": { "arabic": "دائن", "english": "Credit" },
"total": "0.00",
"count": 0
},
"debit": {
"label": { "arabic": "مدين", "english": "Debit" },
"total": "0.00",
"count": 0
},
"total": {
"label": { "arabic": "المجموع", "english": "Total" },
"total": "0.00",
"count": 0
}
},
"host": {
"credit": {
"label": { "arabic": "دائن", "english": "Credit" },
"total": "0.00",
"count": 0
},
"debit": {
"label": { "arabic": "مدين", "english": "Debit" },
"total": "0.00",
"count": 0
},
"total": {
"label": { "arabic": "المجموع", "english": "Total" },
"total": "0.00",
"count": 0
}
},
"is_balanced": true
}
// Other schemes: VC, VD, MC, DM, AX, UP, JC, DC, GN
],
"currency": {
"arabic": "ر.س",
"english": "SAR"
},
"system_trace_audit_number": "000044"
}
},
// Other Reconciliations
],
"pages": {
"total": 12,
"current": 1
}
}
GET/reconciliations/{reconciliation_id}
Find Reconciliation
Request
GET
/reconciliations/{reconciliation_id}{}
{
"reconciliation": {
"id": "2fc49db4-7f86-4ad2-a7c3-877b10251ba3",
"created_at": "2023-11-19T08:05:54.550Z",
"reconciliation_receipt": {
"id": "2fc49db4-7f86-4ad2-a7c3-877b10251ba3",
"date": "19/11/2023",
"time": "11:05:54",
"start_date": "19/11/2023",
"start_time": "11:05:54",
"card_acceptor_terminal_id": "0209326800093268",
"pos_software_version_number": "1.0.0",
"is_balanced": {
"label": {
"arabic": "مقبولة",
"english": "Approved"
},
"value": true
},
"details": {
"total": {
"label": { "arabic": "المجموع", "english": "Total" },
"total": "0.00",
"count": 0
},
"purchase": {
"label": { "arabic": "الشراء", "english": "Purchase" },
"total": "0.00",
"count": 0
},
"purchase_reversal": {
"label": { "arabic": "الشراء المعكوسة", "english": "Purchase Reversal" },
"total": "0.00",
"count": 0
},
"refund": {
"label": { "arabic": "المستردة", "english": "Refund" },
"total": "0.00",
"count": 0
},
"refund_reversal": {
"label": { "arabic": "المستردة المعكوسة", "english": "Refund Reversal" },
"total": "0.00",
"count": 0
}
},
"schemes": [
{
"name": {
"label": { "english": "mada", "arabic": "مدى" },
"value": "P1"
},
"pos": {
"credit": {
"label": { "arabic": "دائن", "english": "Credit" },
"total": "0.00",
"count": 0
},
"debit": {
"label": { "arabic": "مدين", "english": "Debit" },
"total": "0.00",
"count": 0
},
"total": {
"label": { "arabic": "المجموع", "english": "Total" },
"total": "0.00",
"count": 0
}
},
"host": {
"credit": {
"label": { "arabic": "دائن", "english": "Credit" },
"total": "0.00",
"count": 0
},
"debit": {
"label": { "arabic": "مدين", "english": "Debit" },
"total": "0.00",
"count": 0
},
"total": {
"label": { "arabic": "المجموع", "english": "Total" },
"total": "0.00",
"count": 0
}
},
"is_balanced": true
}
// Other schemes: VC, VD, MC, DM, AX, UP, JC, DC, GN
],
"currency": {
"arabic": "ر.س",
"english": "SAR"
},
"system_trace_audit_number": "000044"
}
}
}