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
Transaction Approved	Triggered when a new transaction got approved from the bank that issued the customer's payment card
Transaction Rejected	Triggered when a transaction got rejected from the bank that issued the customer's payment card. Can happen due to insuffecient funds, frozen account status, expiration date, etc
Transaction Reversed	Triggered when a transaction got reversed from the bank that issued the customer's payment card or from the SDK by applying reverse function
Terminal Reconciled	Triggered when a terminal got reconciled from the SDK, the API, manually from dashboard, or from reconciliations policies
Terminal Device Disconnected	Triggered when a device disconnected from a terminal. Disconnecting a device from a terminal happens when a user logs out, or manually from dashboard
Terminal Device Connected	Triggered when a device connected to a terminal. Connecting a device to a terminal happens when a user successfully logs in to the SDK by phone number or email, or the JWT authentication method used to log in to the SDK succeeds
Terminal User Unassigned	Triggered when a user got unassigned from a terminal by revoking his access manually from dashboard, or through the APIs
Terminal Updated Configurations	Triggered when the terminal got updated by changing the payment providers, features, loyalty program manually from dashboard
Terminal User Assigned	Triggered when a user assigned to a terminal manually from the dashboard
Terminal Registered	Triggered when new terminal got registered in the dashboard
Client Admin Revoked	When an admin got revoked manually from the dashboard
Client Admin Created	When a new admin user is added in the dashboard
Client Public-key Regenerated	Triggered when a Public key got regenerated from the dashboard
Client Api-key Regenerated	Triggered when your api key got regenerated from the dashboard
Merchant Assigned Admin	Triggered when a new admin got created and assinged to a merchant
Merchant Revoked Admin	Triggered when a merchent admin got revoked
Merchant Created	Triggered when a new merchant got created in the client account
App Created	Triggered when a new app added manually from the dashboard
App Supported Sdk Added	Triggered when a new supported sdk got added
App Supported Sdk Removed	triggered when a supported SDK got removed
App Supported Sdk Release Upgraded	triggered when a new releasee got upgraded manually from the dashboard

Payloads

Transaction Approved

Please note the following:

If "is_approved": true, and "is_refunded": false that means the transaction is an approved purchase transaction
If "is_approved": true, and "is_refunded": true that means the transaction is an approved refund transaction
"is_reversed": will always be false here

{
  "payload": {
    "id": "571b4013-695e-4d03-a244-545628484688",
    "rrn": "181354154032",
    "tid": "NRP998989851",
    "stan": "000022",
    "amount": "2.00",
    "status": "approved",
    "receipt": {
      "id": "c278cd04-1635-4ede-a326-d86a762a6d13",
      "data": {
        "id": "0e02d4aa-2162-4f50-9aca-2306f1f68e74",
        "pan": "5274 **** **** 7996",
        "tid": "WC9WJ76Q",
        "date": "18/06/2026",
        "time": "13:54",
        "type": "BKM",
        "currency": {
          "english": "TL",
          "turkish": "TL"
        },
        "merchant": {
          "id": "914200000000035",
          "name": "INTERTECH BILGI ISLEM PAZARLAMA",
          "address": "Nispetiye Evren FA93D0F1 74257"
        },
        "card_type": "Kredi",
        "acquirer_id": "0134",
        "action_code": "00",
        "card_domain": "Yurt İçi",
        "card_scheme": "MASTERCARD",
        "is_approved": true,
        "batch_number": "000112",
        "acquirer_name": "Denizbank",
        "approval_code": "055144",
        "reply_message": null,
        "serial_number": "NRP998989851 NRP/NSP",
        "bank_reference": "1813541536590000",
        "device_details": "NRP998989851    NRPNSP000100010134      ",
        "status_message": {
          "english": "Transaction Approved",
          "turkish": "İşlem Onaylandı"
        },
        "card_expiration": "29/05",
        "transaction_code": "L11",
        "transaction_type": {
          "id": "00",
          "name": {
            "english": "PURCHASE AMOUNT",
            "turkish": "Satış"
          }
        },
        "transaction_uuid": "571b4013-695e-4d03-a244-545628484688",
        "amount_authorized": {
          "label": {
            "english": "PURCHASE AMOUNT",
            "turkish": "Satış"
          },
          "value": "2.00"
        },
        "installment_amount": null,
        "installments_count": null,
        "transaction_number": "000134",
        "action_code_message": {
          "english": "APPROVED",
          "turkish": "ONAYLANDI"
        },
        "transaction_details": {
          "english": "I HAVE RECEIVED GOOD OR SERVICE AGAINST THE AMOUNT",
          "turkish": "TUTAR KARŞILIĞI MAL VEYA HİZMET ALDIM"
        },
        "application_cryptogram": "6A83BD8D6345AF44",
        "application_identifier": "A0000000041010",
        "installment_calculation": null,
        "reply_message_explanation": null,
        "system_trace_audit_number": "000022",
        "retrieval_reference_number": "181354154032",
        "pos_software_version_number": "1.0.0"
      },
      "standard": "BKM"
    },
    "auth_code": "055144",
    "receipt_id": "bc3a0a78-99d6-4b98-8da4-5f63d47626c9",
    "action_code": "00",
    "merchant_id": "d6d3c1be-65ea-446a-a969-69623b4ca5e9",
    "require_pin": false,
    "decline_reason": null,
    "customer_reference_number": "customerReferenceNumber"
  }
}

Transaction Rejected

Please note the following:

If "is_approved": false, and "is_refunded": false that means the transaction is a declined purchase transaction
If "is_approved": false, and "is_refunded": true that means the transaction is a declined refund transaction
"is_reversed": will always be false here

{
  "payload": {
    "id": "69c3bb68-1fe9-42b7-b74e-3cd253e72749",
    "rrn": "616905088956",
    "tid": "PLSPS0000001",
    "stan": "001011",
    "amount": "2.00",
    "status": "declined",
    "receipt": {
      "id": "f8ec3e89-ccc0-4e3d-a55d-3d844dc673e2",
      "data": {
        "id": "4f9e6861-cc69-4de0-8922-5d085112175d",
        "pan": "5274 **** **** 7996",
        "tid": "TP103352",
        "date": "18/06/2026",
        "time": "14:10",
        "type": "BKM",
        "currency": {
          "english": "TL",
          "turkish": "TL"
        },
        "merchant": {
          "id": "000000000000002",
          "name": "Pluspay paycell",
          "address": "ataşehir"
        },
        "card_type": "unknown",
        "acquirer_id": "0001",
        "action_code": "01",
        "card_domain": "unknown",
        "card_scheme": "MASTERCARD",
        "is_approved": false,
        "batch_number": "000004",
        "acquirer_name": "Test Bankası",
        "approval_code": "254884",
        "reply_message": "BANKANIZI ARAYIN",
        "serial_number": "PLSPS0000001 NRP/NSP",
        "bank_reference": "",
        "device_details": "PLSPS0000001    NRPNSP000100010001      ",
        "status_message": {
          "english": "Call the Bank Issued the Card",
          "turkish": "Kartı Veren Bankayı Arayınız"
        },
        "card_expiration": "29/05",
        "transaction_code": "L11",
        "transaction_type": {
          "id": "00",
          "name": {
            "english": "PURCHASE AMOUNT",
            "turkish": "Satış"
          }
        },
        "transaction_uuid": "69c3bb68-1fe9-42b7-b74e-3cd253e72749",
        "amount_authorized": {
          "label": {
            "english": "PURCHASE AMOUNT",
            "turkish": "Satış"
          },
          "value": "2.00"
        },
        "installment_amount": null,
        "installments_count": null,
        "transaction_number": "001010",
        "action_code_message": {
          "english": "REJECTED: 01",
          "turkish": "RED: 01"
        },
        "transaction_details": {
          "english": "",
          "turkish": ""
        },
        "application_cryptogram": "085322D0532883A4",
        "application_identifier": "A0000000041010",
        "installment_calculation": null,
        "reply_message_explanation": "HATALI KART NO",
        "system_trace_audit_number": "001011",
        "retrieval_reference_number": "616905088956",
        "pos_software_version_number": "1.0.0"
      },
      "standard": "BKM"
    },
    "auth_code": "254884",
    "receipt_id": "774d7aa5-11ee-4c96-aa17-76e4b74276ae",
    "action_code": "01",
    "merchant_id": "3e0dcaa3-999a-4c1c-bf5c-7d5b1ff37cc3",
    "require_pin": false,
    "decline_reason": "system_decline",
    "customer_reference_number": "customerReferenceNumber"
  }
}

Transaction Reversed

Please note the following:

If "is_approved": true, and "is_refunded": false that means the transaction is a reversed purchase transaction
If "is_approved": true, and "is_refunded": true that means the transaction is a reversed refund transaction
"is_reversed": will always be true here

{
  "payload": {
    "id": "0948b847-25a1-45fb-bc5d-d48c63170c76",
    "rrn": "181535346141",
    "tid": "NRP998989851",
    "stan": "000030",
    "amount": "2.00",
    "status": "approved",
    "receipt": {
      "id": "80be6624-87a1-408b-97b2-6797cf11c48d",
      "data": {},
      "standard": "BKM"
    },
    "auth_code": "",
    "receipt_id": "ca11772e-8d54-4304-a882-ebff51e2cc9a",
    "action_code": "00",
    "require_pin": false,
    "decline_reason": null
  }
}

Terminal Reconciled

{
  "payload": {
    "id": "209c5eb7-a570-40d2-aad9-a8ef3250ed50",
    "status": "approved",
    "receipt": {
      "id": "06b048a4-8efa-479d-aac4-4e315a4a2ace",
      "data": {
        "date": "15/12/2025",
        "hour": "09:38",
        "bank_name": "Denizbank",
        "grand_total": "100",
        "document_ref": "000002",
        "business_name": "INTERTECH BILGI ISLEM PAZARLAMA",
        "serial_number": "NRP000001164",
        "business_number": "914200000000035",
        "terminal_number": "6SAVG828",
        "end_of_day_summary": [
          {
            "type": "purchase",
            "count": "1",
            "amount": "100"
          },
          {
            "type": "refund",
            "count": "0",
            "amount": "0"
          },
          {
            "type": "refund_void",
            "count": "0",
            "amount": "0"
          },
          {
            "type": "purchase_void",
            "count": "0",
            "amount": "0"
          }
        ],
        "business_address_and_telephone": "İstiklal Evren 3AAF770F 73662 2125691255"
      },
      "standard": "BKM"
    },
    "auth_code": "694240",
    "action_code": "00",
    "is_balanced": true,
    "total_count": 1,
    "total_value": 100,
    "reconciliation_totals": [
      {
        "total_count": 1,
        "refund_count": 0,
        "total_amount": 100,
        "refund_amount": 0,
        "purchase_count": 1,
        "schema_sponsor": "0134",
        "purchase_amount": 100,
        "schema_acquirer": "MC",
        "cash_back_amount": 0,
        "authorization_count": 0,
        "cash_advance_amount": 0,
        "authorization_amount": 0,
        "refund_reversal_count": 0,
        "refund_reversal_amount": 0,
        "purchase_reversal_count": 0,
        "purchase_reversal_amount": 0
      },
      {
        "total_count": 1,
        "refund_count": 0,
        "total_amount": 100,
        "refund_amount": 0,
        "purchase_count": 1,
        "schema_sponsor": "0134",
        "purchase_amount": 100,
        "schema_acquirer": "ALL",
        "cash_back_amount": 0,
        "authorization_count": 0,
        "cash_advance_amount": 0,
        "authorization_amount": 0,
        "refund_reversal_count": 0,
        "refund_reversal_amount": 0,
        "purchase_reversal_count": 0,
        "purchase_reversal_amount": 0
      }
    ]
  }
}

Terminal Device Disconnected

{
  "payload": {
    "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 Connected

{
  "payload": {
    "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 User Unassigned

{
  "payload": {
    "id": "0502b3f0-d00d-49c5-8feb-73a986687521",
    "tid": "NRP000101001",
    "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

{
  "payload": {
    "id": "fcb46b39-16f4-4869-a3d4-7ee3db593082",
    "is_completed": true
  }
}

Terminal User Assigned

{
  "payload": {
    "id": "04d7cecd-12f5-479f-9825-7694c5d165d1",
    "tid": "NRP000001021",
    "name": null,
    "user": {
      "id": "21b90934-e98c-4380-b64b-5895df67a3c3",
      "name": "Osama Darabeh",
      "email": "[email protected]",
      "mobile": "+905398252651"
    },
    "client": {
      "id": "38e55add-32ac-428f-8019-6a14d7ad16b8"
    },
    "device": {},
    "merchant": {
      "id": "736cbd85-6226-4def-99a3-3eca7a475149"
    },
    "updated_at": "2025-12-18T10:57:51.769Z"
  }
}

Terminal Registered

{
  "payload": {
    "reference_terminal_id": "4e95a808-4a98-4272-9d11-5c50b196bf37",
    "tid": "NRP000001021",
    "acquirer_institution_identification_code": "0000",
    "client": {
      "id": "38e55add-32ac-428f-8019-6a14d7ad16b8"
    },
    "merchant": {
      "id": "736cbd85-6226-4def-99a3-3eca7a475149"
    },
    "terminal_profile_id": null,
    "name": null,
    "pulled_out_at": null,
    "id": "04d7cecd-12f5-479f-9825-7694c5d165d1",
    "os_type": "android",
    "auto_reconcile": false,
    "device_limit": 1,
    "has_policy": false,
    "is_locked": false,
    "is_pulled_out": false,
    "rate_limit_excluded": false,
    "created_at": "2025-12-18T10:53:12.570Z",
    "updated_at": "2025-12-18T10:53:12.570Z",
    "mode": "pos",
    "is_radar_integrated": false,
    "client_id": "38e55add-32ac-428f-8019-6a14d7ad16b8",
    "merchant_id": "736cbd85-6226-4def-99a3-3eca7a475149"
  }
}

Client Admin Revoked

{
  "payload": {
    "id": "4a8142f1-33d7-4bef-991b-1abf8fdebf4d",
    "name": "John Doe",
    "email": "[email protected]",
    "mobile": "+966512345678"
  }
}

Client Admin Created

{
  "payload": {
    "id": "4a8142f1-33d7-4bef-991b-1abf8fdebf4d",
    "name": "John Doe",
    "email": "[email protected]",
    "mobile": "+966512345678"
  }
}

Client Public-key Regenerated

{
  "payload": {
    "id": "d9b724b5-b958-4716-b39f-ef9376c5269a",
  }
}

Client Api-key Regenerated

{
  "payload": {
    "id": "d9b724b5-b958-4716-b39f-ef9376c5269a"
  }
}

Merchant Assigned Admin

{
  "payload": {
    "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

{
    "payload": {
    "id": "b1c04795-2826-4c3b-92a3-534ab9806aaa",
    "name": "John Doe",
    "email": "[email protected]",
    "mobile": "+966512345678"
  }
}

Merchant Created

{
  "payload": {
    "cr": null,
    "id": "a5d131be-a099-456d-b760-c4ca7b4921af",
    "fid": null,
    "pid": null,
    "logo": null,
    "name": "New Merchant",
    "apikey": null,
    "client": {
      "id": "38e55add-32ac-428f-8019-6a14d7ad16b8"
    },
    "is_nsp": false,
    "mobile": null,
    "status": "active",
    "name_ar": "",
    "publicKey": null,
    "created_at": "2025-12-18T12:33:33.259Z",
    "deleted_at": null,
    "has_policy": false,
    "updated_at": "2025-12-18T12:33:33.259Z",
    "logo_layout": "circular",
    "reference_id": "",
    "configuration": {
      "invoice_mode": false
    },
    "reversal_phone": null,
    "tax_percentage": 0,
    "export_data_type": "nearpay",
    "manual_reconcile": false,
    "surcharge_amount": 0,
    "virtual_terminal": false,
    "name_search_vector": "'bho':11C 'ebh':12C 'est':13C 'f':5C 'fo':8C 'for':2A,14C 'hoo':15C 'ok':16C 'ook':17C 'or':18C 'st':19C 't':6C 'te':9C 'tes':20C 'test':1A 'w':7C 'we':10C 'web':21C 'webhook':3A 'اسامة':4B"
  }
}

App Created

{
  "payload": {
    "clientPackage": {
      "id": "6bf053eb-603e-4449-9aa1-d4a434e799d8",
      "name": "demo.app.com",
      "client": {
        "id": "d9b724b5-b958-4716-b39f-ef9376c5269a"
      },
      "app_name": "Demo app",
      "type": "sdk",
      "created_at": "2023-02-19T12:44:19.007Z",
      "updated_at": "2023-02-19T12:44:19.007Z"
    }
  }
}

App Supported Sdk Added

{
  "payload": {
    "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

{
  "payload": {
    "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

{
  "payload": {
    "id": "6bf053eb-603e-4449-9aa1-d4a434e799d8",
    "app_name": "Demo App",
    "name": "demo.app.com",
    "type": "sdk",
    "created_at": "2022-12-27T16:02:18.481Z",
    "updated_at": "2022-12-27T16:02:18.481Z"
    "sdk": {
      "id": "1dfd17cf-4afb-43de-a725-60229b52e322"
    },
    "release": {
      "id": "e7822e4c-a70f-425d-9e25-6bff79bd3859"
    }
  }
}