Banks 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.
Authentication
NearPay uses API key as an authentication method. The API key must be included in every request as an api-key header.
Your bank API key can be retrieved from your NearPay dashboard. The api-key is required in all requests as a header. Please follow this path to get your API key: NearPay Dashboard -> Credentials -> Copy the api key.
Base URL
https://sandbox-api.nearpay.io/v1/banks-sdk/
Pagination
Please find the guide here in how to use pagination.
SDK Terminals
Terminals registered via the NearPay mobile SDK.
GET/banks-sdk/terminals
List Terminals
Request
GET
/banks-sdk/terminals{}
Response 200
{
"terminals": [
{
"id": "a1b2c3d4-0001-4000-8000-000000000001",
"system_trace_audit_number": "000123",
"card_acceptor_terminal_id": "10000001",
"card_acceptor_id_code": "550100105798",
"acquirer_institution_identification_code": "588888",
"trsm": "FF1BCA",
"client_id": "f5b80833-d1a6-414a-be4c-9f5ae3a9eaca",
"created_at": "2024-01-15T10:00:00.000Z",
"is_pulled_out": false,
"pulled_out_at": null,
"app_version": "3.5.0",
"sdk_version": "2.1.0",
"store": null
}
],
"pages": {
"total": 1,
"current": 1
},
"total": 10
}
GET/banks-sdk/terminals/{id}
Find Terminal
Request
GET
/banks-sdk/terminals/{id}{}
{
"terminal": {
"id": "a1b2c3d4-0001-4000-8000-000000000001",
"system_trace_audit_number": "000123",
"card_acceptor_terminal_id": "10000001",
"card_acceptor_id_code": "550100105798",
"trsm": "FF1BCA",
"is_pulled_out": false,
"pulled_out_at": null,
"package_name": "io.nearpay.app",
"app_version": "3.5.0",
"sdk_version": "2.1.0",
"created_at": "2024-01-15T10:00:00.000Z",
"updated_at": "2024-01-15T10:00:00.000Z"
}
}
SDK Transactions
Transactions performed through the NearPay mobile SDK.
GET/banks-sdk/transactions
List Transactions
Request
GET
/banks-sdk/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"
},
"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"
},
"amount_other": {
"label": {
"arabic": "مبلغ النقد",
"english": "NAQD AMOUNT"
},
"value": "0.00"
},
"currency": {
"arabic": "",
"english": "SAR"
},
"status_message": {
"arabic": "مرفوضة",
"english": "ERROR"
},
"is_approved": false,
"is_refunded": false,
"is_reversed": false,
"approval_code": null,
"verification_method": {
"english": "NO VERIFICATION REQUIRED",
"arabic": "لا يتطلب التحقق"
},
"end_date": "28/09/2023",
"end_time": "11:54:49",
"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": "940",
"application_identifier": "A0000002281010",
"terminal_verification_result": "0080008000",
"transaction_state_information": "0000",
"cardholader_verfication_result": "3F0000",
"cryptogram_information_data": "80",
"application_cryptogram": "36F7E3EA6847D4DD",
"kernel_id": "2d",
"payment_account_reference": "",
"pan_suffix": "",
"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"
}
],
"customer_reference_number": null,
"retrieval_reference_number": "871752000000",
"reconciliation": null,
"package_name": "io.nearpay.softpos",
"lat": "24.803824",
"lon": "46.6051649"
}
],
"pages": {
"total": 5,
"current": 1
}
}
GET/banks-sdk/transactions/{id}
Find Transaction
Request
GET
/banks-sdk/transactions/{id}{}
{
"transaction": {
"id": "f2190ab9-3048-4364-a6f7-ce3ce53a3b16",
"device": {
"id": "c3ed2df1-ede2-402d-87d1-f0b59850f537",
"status": "new",
"type": "phone"
},
"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"
},
"amount_other": {
"label": {
"arabic": "مبلغ النقد",
"english": "NAQD AMOUNT"
},
"value": "0.00"
},
"currency": {
"arabic": "",
"english": "SAR"
},
"status_message": {
"arabic": "مرفوضة",
"english": "ERROR"
},
"is_approved": false,
"is_refunded": false,
"is_reversed": false,
"approval_code": null,
"verification_method": {
"english": "NO VERIFICATION REQUIRED",
"arabic": "لا يتطلب التحقق"
},
"end_date": "28/09/2023",
"end_time": "11:54:49",
"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": "940",
"application_identifier": "A0000002281010",
"terminal_verification_result": "0080008000",
"transaction_state_information": "0000",
"cardholader_verfication_result": "3F0000",
"cryptogram_information_data": "80",
"application_cryptogram": "36F7E3EA6847D4DD",
"kernel_id": "2d",
"payment_account_reference": "",
"pan_suffix": "",
"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"
}
],
"created_at": "2023-09-28T08:54:49.563Z",
"is_reconcilied": false,
"customer_reference_number": null,
"reconciliation": null,
"package_name": "io.nearpay.softpos",
"internet": {
"type": "wifi",
"speed": "271"
},
"lat": "24.803824",
"lon": "46.6051649"
}
}
SDK Reconciliations
Reconciliations for mobile SDK terminals.
GET/banks-sdk/reconciliations
List Reconciliations
Request
GET
/banks-sdk/reconciliations{}
Response 200
{
"reconciliations": [
{
"id": "b3c4d5e6-0002-4000-8000-000000000002",
"stan": "000456",
"total": 5,
"currency": "682",
"terminal_id": "a1b2c3d4-0001-4000-8000-000000000001",
"total_value": "10.50",
"time": "14:30:00",
"is_balanced": true,
"terminal": {
"id": "a1b2c3d4-0001-4000-8000-000000000001",
"tid": "1881001155119328",
"name": "Terminal 01"
},
"created_at": "2024-01-15T14:30:00.000Z"
}
],
"pages": {
"total": 2,
"current": 1
},
"total": 15
}
GET/banks-sdk/reconciliations/{id}
Find Reconciliation
Request
GET
/banks-sdk/reconciliations/{id}{}
{
"reconciliation": {
"id": "b3c4d5e6-0002-4000-8000-000000000002",
"date": "15/01/2024",
"time": "14:30:00",
"start_date": "15/01/2024",
"start_time": "08:00:00",
"end_date": "15/01/2024",
"end_time": "14:30:00",
"card_acceptor_terminal_id": "10000001",
"pos_software_version_number": "3.5.0",
"card_scheme_sponsor_id": "BSFB",
"is_balanced": true,
"details": [],
"schemes": [
{
"id": "P1",
"name": {
"english": "mada",
"arabic": "مدى"
},
"count": 5,
"total": "10.50"
}
],
"currency": "682",
"system_trace_audit_number": "000456",
"created_at": "2024-01-15T14:30:00.000Z",
"updated_at": "2024-01-15T14:30:00.000Z",
"qr_code": "https://api.nearpay.io/ui/reconciliation/b3c4d5e6-0002-4000-8000-000000000002",
"device": null,
"terminal": {
"id": "a1b2c3d4-0001-4000-8000-000000000001",
"os_type": "android",
"reference_terminal_id": "REF001",
"tid": "1881001155119328",
"name": "Terminal 01",
"auto_reconcile": false,
"pulled_out_at": null,
"created_at": "2024-01-15T10:00:00.000Z",
"updated_at": "2024-01-15T10:00:00.000Z",
"mode": "live",
"trsm": "FF1BCA",
"is_assigned": true,
"is_connected": true
}
}
}
POS Terminals
Hardware POS terminals communicating via the NSP protocol.
GET/banks-sdk/pos/terminals
List POS Terminals
Request
GET
/banks-sdk/pos/terminals{}
Response 200
{
"terminals": [
{
"id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
"card_acceptor_terminal_id": "10000001",
"card_acceptor_id": "111111111111",
"trsm": "FF1BCA",
"acquirer_institution_identification_code": "588888",
"created_at": "2024-01-15T10:00:00.000Z",
"updated_at": "2024-01-15T10:00:00.000Z"
}
],
"pages": {
"current": 1
}
}
GET/banks-sdk/pos/terminals/{uuid}
Find POS Terminal
Request
GET
/banks-sdk/pos/terminals/{uuid}{}
{
"terminal": {
"id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
"card_acceptor_terminal_id": "10000001",
"card_acceptor_id": "111111111111",
"trsm": "FF1BCA",
"acquirer_institution_identification_code": "588888",
"created_at": "2024-01-15T10:00:00.000Z",
"updated_at": "2024-01-15T10:00:00.000Z",
"device": {
"id": "c3ed2df1-ede2-402d-87d1-f0b59850f537",
"vendor_id": "02",
"serial_number": "SN000001"
}
}
}
POS Transactions
Transactions performed through hardware POS terminals.
GET/banks-sdk/pos/transactions
List POS Transactions
Request
GET
/banks-sdk/pos/transactions{}
Response 200
{
"transactions": [
{
"id": "dfe2ca83-3e7e-4221-a7cf-723cd1dabcdb",
"amount_authorized": "800",
"amount_other": "0",
"local_date_time": "250925170940",
"transaction_type": "00",
"currency_code": "682",
"processing_code": "000000",
"acquirer_institution_identification_code": "588845",
"system_trace_audit_number": "000789",
"retrival_reference_number": "527309006786",
"merchant_catagory_code": "5812",
"pan": "448844******1001",
"card_scheme": "P1",
"action_code": "000",
"approval_code": "474747",
"cardholder_verification_method": null,
"entry_mode": "7",
"is_approved": true,
"is_reversed": false,
"is_reversal_approved": false,
"is_settled": false,
"is_reconciled": false,
"performance": [
{ "type": "api_start", "time_stamp": 1758809381815 },
{ "type": "server_start", "time_stamp": 1758809381815 },
{ "type": "transaction_start", "time_stamp": 1758809381815 },
{ "type": "network_start", "time_stamp": 1758809381815 },
{ "type": "send", "time_stamp": 1758809381816 },
{ "type": "received", "time_stamp": 1758809381977 },
{ "type": "network_end", "time_stamp": 1758809381978 },
{ "type": "transaction_end", "time_stamp": 1758809381978 },
{ "type": "api_end", "time_stamp": 1758809381978 },
{ "type": "server_end", "time_stamp": 1758809381978 }
],
"decline_reason": null,
"ip": null,
"created_at": "2025-09-25T14:09:41.815Z",
"updated_at": "2025-09-25T14:09:42.023Z",
"region": "jed",
"lat": "21.479444444444443",
"lon": "39.33222222222223",
"tunnel": {
"id": "5c10f000-39eb-4bed-90ec-5d2245e0d3f5",
"name": "Default",
"type": "iso-8583",
"is_whitelist": false,
"allow_only_known_vendors": false,
"settings": {
"terminal": {
"registration": {
"auto": false
}
}
},
"created_at": "2025-01-29T14:03:29.507Z",
"updated_at": "2025-01-29T14:03:29.507Z"
},
"terminal": {
"id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
"card_acceptor_terminal_id": "1990010800000201"
},
"messages": [
{
"id": "9f4d1c2e-1a2b-4c3d-8e9f-000000000001",
"system_trace_audit_number": "000789",
"action_code": "000",
"mti": "1210",
"card_acceptor_terminal_id": "1990010800000201",
"retrival_reference_number": "527309006786"
},
{
"id": "9f4d1c2e-1a2b-4c3d-8e9f-000000000002",
"system_trace_audit_number": "000789",
"action_code": null,
"mti": "1200",
"card_acceptor_terminal_id": "1990010800000201",
"retrival_reference_number": "527309006786"
}
]
}
],
"pages": {
"current": 1
}
}
GET/banks-sdk/pos/transactions/{uuid}
Find POS Transaction
Request
GET
/banks-sdk/pos/transactions/{uuid}{}
{
"transaction": {
"id": "dfe2ca83-3e7e-4221-a7cf-723cd1dabcdb",
"amount_authorized": "800",
"amount_other": "0",
"local_date_time": "250925170940",
"transaction_type": "00",
"currency_code": "682",
"processing_code": "000000",
"acquirer_institution_identification_code": "588845",
"system_trace_audit_number": "000789",
"retrival_reference_number": "527309006786",
"merchant_catagory_code": "5812",
"pan": "448844******1001",
"card_scheme": "P1",
"action_code": "000",
"approval_code": "474747",
"cardholder_verification_method": null,
"entry_mode": "7",
"is_approved": true,
"is_reversed": false,
"is_reversal_approved": false,
"performance": [
{ "type": "api_start", "time_stamp": 1758809381815 },
{ "type": "server_start", "time_stamp": 1758809381815 },
{ "type": "transaction_start", "time_stamp": 1758809381815 },
{ "type": "network_start", "time_stamp": 1758809381815 },
{ "type": "send", "time_stamp": 1758809381816 },
{ "type": "received", "time_stamp": 1758809381977 },
{ "type": "network_end", "time_stamp": 1758809381978 },
{ "type": "transaction_end", "time_stamp": 1758809381978 },
{ "type": "api_end", "time_stamp": 1758809381978 },
{ "type": "server_end", "time_stamp": 1758809381978 }
],
"decline_reason": null,
"ip": null,
"created_at": "2025-09-25T14:09:41.815Z",
"updated_at": "2025-09-25T14:09:42.023Z",
"region": "jed",
"lat": "21.479444444444443",
"lon": "39.33222222222223",
"terminal": {
"id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
"trsm": "FF1BCA",
"card_acceptor_id": "111111111111",
"card_acceptor_terminal_id": "1990010800000201",
"acquirer_institution_identification_code": "588845",
"vendor": {
"id": "e098adba-c31a-448f-8335-e6f34f68c2d4",
"vendor_id": "02",
"name": "Nearpay"
}
},
"messages": [
{
"id": "9f4d1c2e-1a2b-4c3d-8e9f-000000000001",
"system_trace_audit_number": "000789",
"action_code": "000",
"mti": "1210",
"card_acceptor_terminal_id": "1990010800000201",
"retrival_reference_number": "527309006786",
"created_at": "2025-09-25T14:09:41.978Z"
},
{
"id": "9f4d1c2e-1a2b-4c3d-8e9f-000000000002",
"system_trace_audit_number": "000789",
"action_code": null,
"mti": "1200",
"card_acceptor_terminal_id": "1990010800000201",
"retrival_reference_number": "527309006786",
"created_at": "2025-09-25T14:09:41.815Z"
}
],
"receipts": [
{
"id": "48861c15-ac34-4f13-992f-e91b825d8d77",
"data": {
"id": "48861c15-ac34-4f13-992f-e91b825d8d77",
"lat": "21.479444444444443",
"lon": "39.33222222222223",
"pan": "4488 44** **** 1001",
"tid": "1990010800000201",
"type": "purchase",
"qr_code": "https://api.nearpay.io/pos/ui/receipt/48861c15-ac34-4f13-992f-e91b825d8d77",
"currency": {
"arabic": "",
"english": "SAR"
},
"end_date": "25/09/2025",
"end_time": "17:09:41",
"merchant": {
"id": "111111111111",
"name": {
"arabic": "نيرباي",
"english": "Nearpay"
},
"address": {
"arabic": "الملقا",
"english": "Almalqa"
},
"category_code": "5812"
},
"entry_mode": "CONTACTLESS",
"pan_suffix": "",
"start_date": "25/09/2025",
"start_time": "17:09:41",
"action_code": "000",
"card_scheme": {
"id": "P1",
"name": {
"key": "mada",
"arabic": "مدى",
"english": "mada"
}
},
"is_approved": true,
"is_refunded": false,
"is_reversed": false,
"amount_other": {
"label": {
"arabic": "مبلغ النقد",
"english": "NAQD AMOUNT"
},
"value": "0.00"
},
"approval_code": {
"label": {
"arabic": "رمز الموافقة",
"english": "Approval Code"
},
"value": "474747"
},
"terminal_type": "pos",
"status_message": {
"arabic": "مقبولة",
"english": "Approved"
},
"thanks_message": {
"arabic": "شكرا لاستخدامكم مدى",
"english": "Thank you for using mada"
},
"card_expiration": "29/04",
"receipt_line_one": {
"arabic": "",
"english": ""
},
"receipt_line_two": {
"arabic": "",
"english": ""
},
"transaction_type": {
"id": "00",
"name": {
"arabic": "شراء",
"english": "PURCHASE"
}
},
"transaction_uuid": "dfe2ca83-3e7e-4221-a7cf-723cd1dabcdb",
"amount_authorized": {
"label": {
"arabic": "مبلغ الشراء",
"english": "PURCHASE AMOUNT"
},
"value": "8.00"
},
"card_scheme_sponsor": "ANBB",
"verification_method": {
"arabic": "تم التحقق من هوية حامل الجهاز ",
"english": "DEVICE OWNER IDENTITY VERIFIED"
},
"save_receipt_message": {
"arabic": "يرجى الاحتفاظ بالفاتورة",
"english": "please retain receipt"
},
"application_cryptogram": "11111111111111",
"application_identifier": "A0000002281010",
"payment_account_reference": "",
"system_trace_audit_number": "000789",
"retrieval_reference_number": "527309006786",
"cryptogram_information_data": "00",
"pos_software_version_number": "1.0.0",
"terminal_verification_result": "0000000000",
"transaction_state_information": "0000",
"cardholader_verfication_result": "000000"
}
}
],
"settlement_records": [],
"reconciliation": {
"id": "7c1f3a2e-9b4d-4e8f-a1c2-000000000001",
"system_trace_audit_number": "000012",
"action_code": "000",
"is_balanced": true,
"created_at": "2025-09-25T20:00:00.000Z"
}
},
"isTerminalExcluded": false
}
POS Reconciliations
Reconciliations for hardware POS terminals.
GET/banks-sdk/pos/reconciliations
List POS Reconciliations
Request
GET
/banks-sdk/pos/reconciliations{}
Response 200
{
"reconciliations": [
{
"id": "c5d6e7f8-0004-4000-8000-000000000004",
"pos_totals": {
"purchase": { "count": 5, "amount": "500" },
"refund": { "count": 0, "amount": "0" }
},
"host_totals": {
"purchase": { "count": 5, "amount": "500" },
"refund": { "count": 0, "amount": "0" }
},
"terminal": {
"id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
"card_acceptor_terminal_id": "10000001",
"card_acceptor_id": "111111111111"
},
"created_at": "2024-01-15T14:30:00.000Z",
"updated_at": "2024-01-15T14:30:00.000Z"
}
],
"pages": {
"current": 1
}
}
GET/banks-sdk/pos/reconciliations/{uuid}
Find POS Reconciliation
Request
GET
/banks-sdk/pos/reconciliations/{uuid}{}
{
"reconciliation": {
"id": "c5d6e7f8-0004-4000-8000-000000000004",
"pos_totals": {
"purchase": { "count": 5, "amount": "500" },
"refund": { "count": 0, "amount": "0" }
},
"host_totals": {
"purchase": { "count": 5, "amount": "500" },
"refund": { "count": 0, "amount": "0" }
},
"terminal": {
"id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
"card_acceptor_terminal_id": "10000001",
"card_acceptor_id": "111111111111",
"trsm": "FF1BCA",
"acquirer_institution_identification_code": "588888"
},
"receipt": {
"id": "519a01ef-7c01-4a79-9b60-bc69a7cb2158",
"qr_code": "https://api.nearpay.io/ui/reconciliation/c5d6e7f8-0004-4000-8000-000000000004"
},
"created_at": "2024-01-15T14:30:00.000Z",
"updated_at": "2024-01-15T14:30:00.000Z"
}
}