Webhooks
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.
Webhook is a construct used by an application to notify other applications that an event occurred. More precisely, webhook is a user-defined HTTP callback.
Available events
By default Nearpay webhooks can be triggered by the following events:
Event Name | Description |
|---|---|
Triggered when a device disconnected from a terminal | |
Triggered when a terminal got reconciled | |
When an admin got revoked from the dashboard | |
Triggered when a device connected to a terminal | |
When a new admin is added in the dashboard | |
Triggered when a user got unassigned from a terminal | |
Triggered when a transaction got rejected | |
Triggered when the terminal updated | |
Triggered when a Public key got regerated from the dashboard | |
Triggered when a new supported sdk added | |
Triggered when a new app added from the dashboard | |
Triggered when a new transaction got approved | |
Triggered when a new admin assigned to a merchant | |
Triggered when a merchent admin get revoked | |
Triggered when your api key updated | |
Triggered when a user assigned to a terminal | |
Triggered when a new merchant created | |
When a supported SDK removed | |
Triggered when a transaction got reversed | |
Triggered when new terminal registered | |
when a new releasee upgraded from the dashboard |
Payloads
App Created
{
"id": "6bf053eb-603e-4449-9aa1-d4a434e799d8",
"name": "demo.app.com",
"client": {
"id": "d9b724b5-b958-4716-b39f-ef9376c5269a"
},
"app_name": "Demo app",
"created_at": "2023-02-19T12:44:19.007Z",
"updated_at": "2023-02-19T12:44:19.007Z"
}
App Supported Sdk Added
{
"id": "6bf053eb-603e-4449-9aa1-d4a434e799d8",
"name": "demo.app.com",
"app_name": "Demo App",
"added_sdk": {
"id": "1dfd17cf-4afb-43de-a725-60229b52e322",
"name": "sdk version",
"version": 22,
"created_at": "2022-12-27T16:02:18.481Z",
"updated_at": "2022-12-27T16:02:18.481Z"
},
"created_at": "2023-02-19T12:44:19.007Z",
"updated_at": "2023-02-19T12:44:19.007Z"
}
App Supported Sdk Removed
{
"id": "6bf053eb-603e-4449-9aa1-d4a434e799d8",
"name": "demo.app.com",
"app_name": "Demo App",
"created_at": "2023-02-19T12:44:19.007Z",
"updated_at": "2023-02-19T12:44:19.007Z",
"removed_sdk": {
"id": "1dfd17cf-4afb-43de-a725-60229b52e322",
"name": "sdk version",
"version": 22,
"created_at": "2022-12-27T16:02:18.481Z",
"updated_at": "2022-12-27T16:02:18.481Z"
}
}
App Supported Sdk Release Upgraded
{
"id": "6bf053eb-603e-4449-9aa1-d4a434e799d8",
"name": "demo.app.com",
"sdk_id": "1d2f9026-1c6b-4319-a282-2bd5405c2ae0",
"app_name": "Demo App",
"created_at": "2023-02-19T12:44:19.007Z",
"release_id": "53bca7a8-7930-4d22-948a-ffbd694537f7",
"updated_at": "2023-02-19T12:44:19.007Z"
}
Merchant Created
{
"id": "5dad318e-9b5a-43ee-af36-622502b13241",
"name": "example merchant",
"client": {
"id": "6d92404e-d5ff-4fcd-8590-548a54657450"
},
"status": "active",
"created_at": "2023-02-19T13:31:54.501Z",
"updated_at": "2023-02-19T13:31:54.501Z",
"reference_id": null
}
Merchant Assigned Admin
{
"id": "b1c04795-2826-4c3b-92a3-534ab9806aaa",
"name": "John Doe",
"email": "[email protected]",
"mobile": "+966512345678",
"is_active": true,
"created_at": "2022-10-26T11:51:25.374Z",
"updated_at": "2022-10-26T11:51:25.374Z",
"is_email_verified": true,
"is_mobile_verified": true
}
Merchant Revoked Admin
{
"id": "b1c04795-2826-4c3b-92a3-534ab9806aaa",
"name": "John Doe",
"email": "[email protected]",
"mobile": "+966512345678"
}
Terminal Device Connected
{
"id": "0502b3f0-d00d-49c5-8feb-73a986687521",
"tid": "0100001000000010",
"name": null,
"user": {
"id": "1470cc83-e803-40df-9ccb-fb33496b040d"
},
"client": {
"id": "6d92404e-d5ff-4fcd-8590-548a54657450"
},
"device": {
"id": "1fa8ab88-b776-48d3-b2ce-0bda359b99b5"
},
"merchant": {
"id": "a33d09d3-3a8e-4680-86c2-bc91713b7b79"
},
"created_at": "2023-02-15T09:46:30.700Z",
"updated_at": "2023-02-19T13:18:41.344Z"
}
Terminal Device Disconnected
{
"id": "0502b3f0-d00d-49c5-8feb-73a986687521",
"tid": "0100001000000010",
"name": null,
"user": {
"id": "1470cc83-e803-40df-9ccb-fb33496b040d"
},
"client": {
"id": "6d92404e-d5ff-4fcd-8590-548a54657450"
},
"device": {
"id": "1fa8ab88-b776-48d3-b2ce-0bda359b99b5"
},
"merchant": {
"id": "a33d09d3-3a8e-4680-86c2-bc91713b7b79"
},
"created_at": "2023-02-15T09:46:30.700Z",
"updated_at": "2023-02-19T13:18:41.344Z"
}
Terminal Reconciled
{
"id": "2d04c490-99dc-46c9-939e-5a0f30663910",
"date": "19/02/2023",
"time": "16:28:21",
"details": {
"total": {
"count": 3,
"label": {
"arabic": "المجموع",
"english": "Total"
},
"total": "0.05"
},
"refund": {
"count": 0,
"label": {
"arabic": "المستردة",
"english": "Refund"
},
"total": "0.00"
},
"purchase": {
"count": 2,
"label": {
"arabic": "الشراء",
"english": "Purchase"
},
"total": "0.09"
},
"refund_reversal": {
"count": 0,
"label": {
"arabic": "المستردة المعكوسة",
"english": "Refund Reversal"
},
"total": "0.00"
},
"purchase_reversal": {
"count": 1,
"label": {
"arabic": "الشراء المعكوسة",
"english": "Purchase Reversal"
},
"total": "0.04"
}
},
"qr_code": "https://staging.nearpay.io/ui/reconciliation_receipt/2d04c490-99dc-46c9-939e-5a0f30663910",
"schemes": [
{
"pos": {
"debit": {
"count": 2,
"label": {
"arabic": "مدين",
"english": "Debit"
},
"total": "0.09"
},
"total": {
"count": 3,
"label": {
"arabic": "المجموع",
"english": "Total"
},
"total": "0.05"
},
"credit": {
"count": 1,
"label": {
"arabic": "دائن",
"english": "Credit"
},
"total": "0.04"
}
},
"host": {
"debit": {
"count": 2,
"label": {
"arabic": "مدين",
"english": "Debit"
},
"total": "0.09"
},
"total": {
"count": 3,
"label": {
"arabic": "المجموع",
"english": "Total"
},
"total": "0.05"
},
"credit": {
"count": 1,
"label": {
"arabic": "دائن",
"english": "Credit"
},
"total": "0.04"
}
},
"name": {
"label": {
"arabic": "مدى",
"english": "mada"
},
"value": "P1"
},
"is_balanced": true
},
{
"pos": {
"debit": {
"count": 0,
"label": {
"arabic": "مدين",
"english": "Debit"
},
"total": "0.00"
},
"total": {
"count": 0,
"label": {
"arabic": "المجموع",
"english": "Total"
},
"total": "0.00"
},
"credit": {
"count": 0,
"label": {
"arabic": "دائن",
"english": "Credit"
},
"total": "0.00"
}
},
"host": {
"debit": {
"count": 0,
"label": {
"arabic": "مدين",
"english": "Debit"
},
"total": "0.00"
},
"total": {
"count": 0,
"label": {
"arabic": "المجموع",
"english": "Total"
},
"total": "0.00"
},
"credit": {
"count": 0,
"label": {
"arabic": "دائن",
"english": "Credit"
},
"total": "0.00"
}
},
"name": {
"label": {
"arabic": "فيزا",
"english": "Visa"
},
"value": "VC"
},
"is_balanced": true
},
{
"pos": {
"debit": {
"count": 0,
"label": {
"arabic": "مدين",
"english": "Debit"
},
"total": "0.00"
},
"total": {
"count": 0,
"label": {
"arabic": "المجموع",
"english": "Total"
},
"total": "0.00"
},
"credit": {
"count": 0,
"label": {
"arabic": "دائن",
"english": "Credit"
},
"total": "0.00"
}
},
"host": {
"debit": {
"count": 0,
"label": {
"arabic": "مدين",
"english": "Debit"
},
"total": "0.00"
},
"total": {
"count": 0,
"label": {
"arabic": "المجموع",
"english": "Total"
},
"total": "0.00"
},
"credit": {
"count": 0,
"label": {
"arabic": "دائن",
"english": "Credit"
},
"total": "0.00"
}
},
"name": {
"label": {
"arabic": "ماستر كارد",
"english": "MasterCard"
},
"value": "MC"
},
"is_balanced": true
},
{
"pos": {
"debit": {
"count": 0,
"label": {
"arabic": "مدين",
"english": "Debit"
},
"total": "0.00"
},
"total": {
"count": 0,
"label": {
"arabic": "المجموع",
"english": "Total"
},
"total": "0.00"
},
"credit": {
"count": 0,
"label": {
"arabic": "دائن",
"english": "Credit"
},
"total": "0.00"
}
},
"host": {
"debit": {
"count": 0,
"label": {
"arabic": "مدين",
"english": "Debit"
},
"total": "0.00"
},
"total": {
"count": 0,
"label": {
"arabic": "المجموع",
"english": "Total"
},
"total": "0.00"
},
"credit": {
"count": 0,
"label": {
"arabic": "دائن",
"english": "Credit"
},
"total": "0.00"
}
},
"name": {
"label": {
"arabic": "امريكان اكسبرس",
"english": "American Express"
},
"value": "AX"
},
"is_balanced": true
},
{
"pos": {
"debit": {
"count": 0,
"label": {
"arabic": "مدين",
"english": "Debit"
},
"total": "0.00"
},
"total": {
"count": 0,
"label": {
"arabic": "المجموع",
"english": "Total"
},
"total": "0.00"
},
"credit": {
"count": 0,
"label": {
"arabic": "دائن",
"english": "Credit"
},
"total": "0.00"
}
},
"host": {
"debit": {
"count": 0,
"label": {
"arabic": "مدين",
"english": "Debit"
},
"total": "0.00"
},
"total": {
"count": 0,
"label": {
"arabic": "المجموع",
"english": "Total"
},
"total": "0.00"
},
"credit": {
"count": 0,
"label": {
"arabic": "دائن",
"english": "Credit"
},
"total": "0.00"
}
},
"name": {
"label": {
"arabic": "الشبكة الخليجية",
"english": "GCCNET"
},
"value": "GN"
},
"is_balanced": true
}
],
"user_id": "a33d09d3-3a8e-4680-86c2-bc91713b7b79",
"currency": {
"arabic": "ر.س",
"english": "SAR"
},
"end_date": "19/02/2023",
"end_time": "16:28:21",
"merchant": {
"id": "100000000000001",
"name": {
"arabic": "123455",
"english": "NearPay-Test Terminal INMA"
},
"address": {
"arabic": "4321",
"english": "KAFD"
},
"category_code": "0763"
},
"terminal": {
"id": "54dc65b5-0c94-4889-b85b-1eee5e746925"
},
"client_id": "6d92404e-d5ff-4fcd-8590-548a54657450",
"device_id": "1fa8ab88-b776-48d3-b2ce-0bda359b99b5",
"created_at": "2023-02-19T13:28:21.715Z",
"start_date": "19/02/2023",
"start_time": "16:28:21",
"updated_at": "2023-02-19T13:28:21.715Z",
"is_balanced": {
"label": {
"arabic": "الموازنة إكتملت",
"english": "RECONCILIATION COMPLETED"
},
"value": true
},
"merchant_id": "a33d09d3-3a8e-4680-86c2-bc91713b7b79",
"reconciliation": {
"id": "2d04c490-99dc-46c9-939e-5a0f30663910"
},
"card_scheme_sponsor_id": "",
"card_acceptor_terminal_id": "0100001000000010",
"system_trace_audit_number": "000043",
"pos_software_version_number": "1.0.0"
}
Client Admin Created
{
"id": "4a8142f1-33d7-4bef-991b-1abf8fdebf4d",
"name": "John Doe",
"email": "[email protected]",
"mobile": "+966512345678"
}
Client Admin Revoked
{
"id": "4a8142f1-33d7-4bef-991b-1abf8fdebf4d",
"name": "John Doe",
"email": "[email protected]",
"mobile": "+966512345678"
}
Client Public-key Regenerated
{
"id": "d9b724b5-b958-4716-b39f-ef9376c5269a",
}
Client Api-key Regenerated
{
"id": "d9b724b5-b958-4716-b39f-ef9376c5269a"
}
Terminal Registered
[
{
"id": "fcb46b39-16f4-4869-a3d4-7ee3db593082",
"tid": "0100002000000020",
"name": null,
"client": {
"id": "6d92404e-d5ff-4fcd-8590-548a54657450"
},
"merchant": {
"id": "a33d09d3-3a8e-4680-86c2-bc91713b7b79"
},
"created_at": "2023-02-19T13:27:46.745Z",
"updated_at": "2023-02-19T13:27:46.745Z"
},
{
"id": "e896d8df-154f-4770-bfeb-dac677f20b44",
"tid": "0100002100000021",
"name": null,
"client": {
"id": "6d92404e-d5ff-4fcd-8590-548a54657450"
},
"merchant": {
"id": "a33d09d3-3a8e-4680-86c2-bc91713b7b79"
},
"created_at": "2023-02-19T13:27:46.820Z",
"updated_at": "2023-02-19T13:27:46.820Z"
}
]
Terminal User Assigned
{
"id": "0502b3f0-d00d-49c5-8feb-73a986687521",
"tid": "0100001000000010",
"name": null,
"user": {
"id": "1470cc83-e803-40df-9ccb-fb33496b040d"
},
"client": {
"id": "6d92404e-d5ff-4fcd-8590-548a54657450"
},
"device": {},
"merchant": {
"id": "a33d09d3-3a8e-4680-86c2-bc91713b7b79"
},
"created_at": "2023-02-15T09:46:30.700Z",
"updated_at": "2023-02-19T13:16:26.884Z"
}
Terminal User Unassigned
{
"id": "0502b3f0-d00d-49c5-8feb-73a986687521",
"tid": "0100001000000010",
"name": null,
"user": {
"id": "1470cc83-e803-40df-9ccb-fb33496b040d"
},
"client": {
"id": "6d92404e-d5ff-4fcd-8590-548a54657450"
},
"device": {},
"merchant": {
"id": "a33d09d3-3a8e-4680-86c2-bc91713b7b79"
},
"created_at": "2023-02-15T09:46:30.700Z",
"updated_at": "2023-02-19T13:16:26.884Z"
}
Terminal Updated Configurations
{
"id": "fcb46b39-16f4-4869-a3d4-7ee3db593082",
"is_completed": true
}
Transaction Approved
{
"id": "c98b2091-27fc-5642-b3ac-91f1d2eb07d3",
"pan": "5069 68** **** 5760",
"tid": "0200066700000667",
"qr_code": "https://sandbox-api.nearpay.io/ui/receipt/c43b2091-6742-27fc-b3ac-91f1d2eb07d3",
"currency": {
"arabic": "ر.س",
"english": "SAR"
},
"end_date": "20/06/2023",
"end_time": "11:56:03",
"merchant": {
"id": "100000000000001",
"name": {
"arabic": "NearPay Merchant Arabic",
"english": "NearPay Merchant"
},
"address": {
"arabic": "4321",
"english": "KAFD"
},
"category_code": "0763"
},
"kernel_id": "02",
"entry_mode": "CONTACTLESS",
"pan_suffix": "",
"start_date": "20/06/2023",
"start_time": "11:56:03",
"action_code": "000",
"card_scheme": {
"id": "P1",
"name": {
"arabic": "مدى",
"english": "mada"
}
},
"is_approved": true,
"is_refunded": false,
"is_reversed": false,
"transaction": {
"id": "59835"
},
"amount_other": {
"label": {
"arabic": "مبلغ النقد",
"english": "NAQD AMOUNT"
},
"value": "0.00"
},
"approval_code": {
"label": {
"arabic": "رمز الموافقة",
"english": "Approval Code"
},
"value": "790200"
},
"status_message": {
"arabic": "مقبولة",
"english": "Approved"
},
"thanks_message": {
"arabic": "شكرا لاستخدامكم مدى",
"english": "Thank you for using mada"
},
"card_expiration": "24/09",
"receipt_line_one": {
"arabic": "",
"english": ""
},
"receipt_line_two": {
"arabic": "",
"english": ""
},
"transaction_type": {
"id": "00",
"name": {
"arabic": "شراء",
"english": "PURCHASE"
}
},
"transaction_uuid": "c43b6431-23a7-4a54-96ff-e23bb0d1015e",
"amount_authorized": {
"label": {
"arabic": "مبلغ الشراء",
"english": "PURCHASE AMOUNT"
},
"value": "5.00"
},
"card_scheme_sponsor": "INMA",
"verification_method": {
"arabic": "لا يتطلب التحقق",
"english": "NO VERIFICATION REQUIRED"
},
"save_receipt_message": {
"arabic": "يرجى الاحتفاظ بالفاتورة",
"english": "please retain receipt"
},
"application_cryptogram": "3DCFAEE023EC843D",
"application_identifier": "A0000004321912",
"customer_reference_number": null,
"payment_account_reference": "34R0380DORHB43PPOD0NL7SY71VK6",
"system_trace_audit_number": "000180",
"retrieval_reference_number": "000000034523",
"cryptogram_information_data": "80",
"pos_software_version_number": "1.0.0",
"terminal_verification_result": "8020000001",
"transaction_state_information": "0000",
"cardholader_verfication_result": "1F0256"
}
Transaction Rejected
{
"id": "6d92404e-d5ff-4fcd-8590-29d18410522d",
"pan": "5069 68** **** 6618",
"tid": "0200111100001111",
"qr_code": "https://sandbox-api.nearpay.io/ui/receipt/95cd551c-66e5-8590-4fcd-29d18410522d",
"currency": {
"arabic": "ر.س",
"english": "SAR"
},
"end_date": "20/06/2023",
"end_time": "12:35:14",
"merchant": {
"id": "100000000000001",
"name": {
"arabic": "NearPay Merchant Arabic",
"english": "NearPay Merchant"
},
"address": {
"arabic": "4321",
"english": "KAFD"
},
"category_code": "0763"
},
"kernel_id": "02",
"entry_mode": "CONTACTLESS",
"pan_suffix": "",
"start_date": "20/06/2023",
"start_time": "12:35:14",
"action_code": "112",
"card_scheme": {
"id": "P1",
"name": {
"arabic": "مدى",
"english": "mada"
}
},
"is_approved": false,
"is_refunded": false,
"is_reversed": false,
"transaction": {
"id": "59848"
},
"amount_other": {
"label": {
"arabic": "مبلغ النقد",
"english": "NAQD AMOUNT"
},
"value": "0.00"
},
"approval_code": {
"label": {
"arabic": "رمز الموافقة",
"english": "Approval Code"
},
"value": "674531"
},
"status_message": {
"arabic": "مرفوضة",
"english": "DECLINED"
},
"thanks_message": {
"arabic": "شكرا لاستخدامكم مدى",
"english": "Thank you for using mada"
},
"card_expiration": "24/03",
"receipt_line_one": {
"arabic": "",
"english": ""
},
"receipt_line_two": {
"arabic": "",
"english": ""
},
"transaction_type": {
"id": "00",
"name": {
"arabic": "شراء",
"english": "PURCHASE"
}
},
"transaction_uuid": "95cd551c-4faf-454f-9302-4faf12a3e8b",
"amount_authorized": {
"label": {
"arabic": "مبلغ الشراء",
"english": "PURCHASE AMOUNT"
},
"value": "51.12"
},
"card_scheme_sponsor": "INMA",
"verification_method": {
"arabic": "لا يتطلب التحقق",
"english": "NO VERIFICATION REQUIRED"
},
"save_receipt_message": {
"arabic": "يرجى الاحتفاظ بالفاتورة",
"english": "please retain receipt"
},
"application_cryptogram": "6AEB48ED4A792610",
"application_identifier": "A0000002281010",
"customer_reference_number": null,
"payment_account_reference": "45R0305RGQWHBIB3ASVQRTCIZG45G",
"system_trace_audit_number": "000042",
"retrieval_reference_number": "000000059848",
"cryptogram_information_data": "80",
"pos_software_version_number": "1.0.0",
"terminal_verification_result": "8020008001",
"transaction_state_information": "0000",
"cardholader_verfication_result": "1F0302"
}
Transaction Reversed
{
"id": "1dfd17cf-2f69-40e2-65c6-f2fa866b46ce",
"pan": "5069 68** **** 5760",
"tid": "0200034200000444",
"qr_code": "https://sandbox-api.nearpay.io/ui/receipt/b33c6f94-2f34-40e2-64c6-f4fa332b46ce",
"currency": {
"arabic": "ر.س",
"english": "SAR"
},
"end_date": "20/06/2023",
"end_time": "11:56:10",
"merchant": {
"id": "100000000000001",
"name": {
"arabic": "NearPay Merchant Arabic",
"english": "NearPay Merchant"
},
"address": {
"arabic": "4321",
"english": "KAFD"
},
"category_code": "0763"
},
"kernel_id": "02",
"entry_mode": "CONTACTLESS",
"pan_suffix": "",
"start_date": "20/06/2023",
"start_time": "11:56:10",
"action_code": "400",
"card_scheme": {
"id": "P1",
"name": {
"arabic": "مدى",
"english": "mada"
}
},
"is_approved": true,
"is_refunded": false,
"is_reversed": true,
"transaction": {
"id": "59835"
},
"amount_other": {
"label": {
"arabic": "مبلغ النقد",
"english": "NAQD AMOUNT"
},
"value": "0.00"
},
"approval_code": null,
"status_message": {
"arabic": "قبلت",
"english": "ACCEPTED"
},
"thanks_message": {
"arabic": "شكرا لاستخدامكم مدى",
"english": "Thank you for using mada"
},
"card_expiration": "24/09",
"receipt_line_one": {
"arabic": "",
"english": ""
},
"receipt_line_two": {
"arabic": "",
"english": ""
},
"transaction_type": {
"id": "00",
"name": {
"arabic": "عملية معكوسة",
"english": "REVERSAL"
}
},
"transaction_uuid": "456740aa-71a7-4f04-86bc-e25aa0d1015e",
"amount_authorized": {
"label": {
"arabic": "المبلغ الملغي",
"english": "REVERSED AMOUNT"
},
"value": "5.00"
},
"card_scheme_sponsor": "INMA",
"verification_method": {
"arabic": "لا يتطلب التحقق",
"english": "NO VERIFICATION REQUIRED"
},
"save_receipt_message": {
"arabic": "يرجى الاحتفاظ بالفاتورة",
"english": "please retain receipt"
},
"application_cryptogram": "2DCFAEE023EC713D",
"application_identifier": "A0000002281010",
"customer_reference_number": null,
"payment_account_reference": "45R4380DORHB43PPOD0NL4SY46VK3",
"system_trace_audit_number": "000181",
"retrieval_reference_number": "000000059835",
"cryptogram_information_data": "80",
"pos_software_version_number": "1.0.0",
"terminal_verification_result": "8040000002",
"transaction_state_information": "0000",
"cardholader_verfication_result": "1A0302"
}