Webhook Notifications

Webhook notifications are automated messages sent by Nayax to your back-end to communicate the final status of a transaction, which can be:

Approved
Declined
Pending

This ensures you are always up to date with the latest transaction information.

📘
Webhook URL
You will provide the URL to receive the webhooks during the onboarding phase.

Webhook Request

Below you can see an example of a webhook of an approved transaction:

{
  "Status": {
    "Verdict": "Approved",
    "Code": 0,
    "StatusMessage": "Transaction successfully completed."
  },
  "BasicInfo": {
    "transactionId": 123456789,
    "AuthCode": "AUTH12345",
    "AuthAmount": 15.00,
    "CaptureAmount": 15.00,
    "RRN": "987654321012",
    "AuthDateTime": "2025-08-28T12:00:00Z",
    "Entry Mode": 1,
    "currencyCode": 840,
    "TransactionEcomMID": "ECOMTRX001",
    "Currency": "USD",
    "CardholderEmail": "[email protected]",
    "NayaxToken": "nayax_token_xyz123",
    "IsAproved": true,
    "Card holder Unique identifier": "guid-customer-12345"
  },
  "Products": [
    {
      "Code": 101,
      "Value": 10,
      "quantity": 1
    },
    {
      "Code": 102,
      "Value": 5,
      "quantity": 1
    }
  ],
  "CardData": {
    "CardNumber": "411111xxxxxx1111",
    "Card expiration": 2810
  }
}

{
  "Status": {
    "Verdict": "Declined",
    "Code": 51,
    "StatusMessage": "Declined - Insufficient Funds"
  },
  "BasicInfo": {
    "transactionId": 123456790,
    "AuthCode": null,
    "AuthAmount": 15.00,
    "CaptureAmount": 0.00,
    "RRN": "987654321013",
    "AuthDateTime": "2025-08-28T12:05:00Z",
    "Entry Mode": 3,
    "currencyCode": 840,
    "TransactionEcomMID": "ECOMTRX002",
    "Currency": "USD",
    "CardholderEmail": "[email protected]",
    "NayaxToken": null,
    "IsAproved": false,
    "Card holder Unique identifier": "guid-customer-12345"
  },
  "Products": [
    {
      "Code": 101,
      "Value": 10,
      "quantity": 1
    },
    {
      "Code": 102,
      "Value": 5,
      "quantity": 1
    }
  ],
  "CardData": {
    "CardNumber": "411111xxxxxx1111",
    "Card expiration": 2810
  }
}

{
  "Status": {
    "Verdict": "Pending",
    "Code": 1,
    "StatusMessage": "Transaction is currently being processed."
  },
  "BasicInfo": {
    "transactionId": 123456791,
    "AuthCode": null,
    "AuthAmount": 15.00,
    "CaptureAmount": 0.00,
    "RRN": null,
    "AuthDateTime": "2025-08-28T12:10:00Z",
    "Entry Mode": 1,
    "currencyCode": 840,
    "TransactionEcomMID": "ECOMTRX003",
    "Currency": "USD",
    "CardholderEmail": "[email protected]",
    "NayaxToken": null,
    "IsAproved": false,
    "Card holder Unique identifier": "guid-customer-12345"
  },
  "Products": [
    {
      "Code": 101,
      "Value": 10,
      "quantity": 1
    }
  ],
  "CardData": {
    "CardNumber": "411111xxxxxx1111",
    "Card expiration": 2810
  }
}

The request includes detailed information about the transaction's final status, including the following objects:

Status
BasicInfo
Products
CardData

🚧
Response
We expect to receive a 200 ACK response after every webhook.

Webhook Request Parameters

The following parameters define the structure of the incoming webhook notification:

Field Name	Type	Description
`Status`	Object	Root object containing the transaction verdict.
`Verdict`	String	Mandatory. Const values: `Approved`, `Declined`.
`Code`	Int	Mandatory. Response code. `0` if Approved; otherwise, use relevant decline code (see Part 8).
`StatusMessage`	String	Length: 255. Free text field for status message or additional data.
`BasicInfo`	Object	Core transaction details.
`transactionId`	Int	The Nayax transaction ID.
`AuthCode`	String(40)	Conditional: Required if transaction type: 1 (Auth).
`AuthAmount`	Number	Conditional: Required if transaction type: 1 (Auth).
`CaptureAmount`	Number	Conditional: Required if transaction type: 2 (Capture).
`RRN`	String(12)	Optional. Retrieval Reference Number.
`AuthDateTime`	Datetime	Must be GMT. If missing, the current date/time will be used.
`Entry Mode`	Int	Card entry mode: 1: Manual, 2: Stripe, 3: Chip, 4: Contactless, 5: Contactless Mag, 6: Mobile, 7: QR, 8: COF, 9: NFC, 10: MIFARE, 11: MIFARE Hex, 12: HID, 13: HID Hex, 14: Monyx App.
`currencyCode`	Int	Currency code. Defaults to machine currency if empty.
`TransactionEcomMID`	String	The Ecom Integrator transaction ID.
`Currency`	String	Mandatory. ISO4217 Alpha-3 format (e.g., USD, EUR).
`CardholderEmail`	String	Conditional: Included if sent in the initial request.
`NayaxToken`	String	Conditional: Included if generated/available.
`IsApproved`	Boolean	True if Token exists.
`Card holder Unique identifier`	String	Cardholder's unique identifier sent by the merchant.
`Products`	Array	List of products in the transaction.
`Code`	Int	Product code.
`Value`	Int	Product value (per unit).
`quantity`	Int	Product quantity.
`CardData`	Object	Payment card information.
`CardNumber`	String	If CC: Send last 4 and first 6 digits.
`Card expiration`	Number	If CC: Expiration date in `YYMM` format.

See Also

Initialize Transactions

Nayax Tokens

Updated 5 days ago