Skip to main content
Webhook notifications are automated messages sent by Nayax to your back-end to communicate the final status of a transaction. 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

There are two types of merchant notifications, depending on the RequestType.

​
Type 1 — Sale or Auth (RequestType: 0)

The full notification structure contains card data, 3DS information, retry attempts, and all transaction fields. The following JSON example illustrates a typical successful Sale notification:
JSON
{
    "CardInfo": {
        "IssuerBin": "",
        "Brand": "amex",
        "CardBin": "370000",
        "CardFinalDigits": "0002",
        "ExpiryDate": "03/2030",
        "IssuingCountry": "NL",
        "IsCardCommercial": "unknown",
        "CardHolderName": "PayWithGoogle PlaceHolder",
        "Alias": "B760792471216187",
        "AliasType": "Default"
    },
    "Ecom3DSInfo": {
        "Is3DSOffered": "false",
        "Is3DSOfferedResponse": "N/A",
        "Is3DSAuthenticated": "false",
        "Is3DSAuthenticatedResponse": "N/A",
        "LiabilityShift": "false",
        "CardEnrolled": "false",
        "Eci": "N/A",
        "Xid": "N/A"
    },
    "RetryAttempts": [
        {
            "Acquirer": "TestPmmAcquirer",
            "AcquirerAccount": "TestPmmAcquirerAccount",
            "ResponseCode": "Approved"
        }
    ],
    "NayaxSession": "20000069048",
    "ExternalTransactionStatus": 13,
    "AuthCode": "007539",
    "PaymentAccountReference": "Ck0v20P40EoneUnZG18SNNNYpw7l6",
    "ShopperCountry": "IL",
    "ShopperLocale": "en-US",
    "ShopperIp": "46.120.69.156",
    "PaymentMethod": "amex",
    "PaymentMethodVariant": "amex_googlepay",
    "Currency": "USD",
    "Amount": "1.97",
    "Cavv": "N/A",
    "CavvAlgorithm": "N/A",
    "CvcResult": "6 No CVC/CVV provided",
    "NayaxTransactionId": "20000121692",
    "MerchantRequestId": "5fbeb1ba-263f-4fe6-a109-642b562020c9",
    "MachineId": "1001316721",
    "FollowUpRequestOptions": [2, 4],
    "RequestType": 0,
    "RequestDate": "2026-03-05T11:09:01.000",
    "IsApproved": true,
    "Hmac": "uET4OAwxvSN6lwVEwzQ1qRWbMkxo4KR9JbUIcG0qqo0="
}

​
Type 2 — All other request types (RequestType: 1, 2, 3…)

This is a minimal notification containing only core fields. Field presence varies by request type. Refer to the sample below for the payload structure:
JSON
{
  "NayaxTransactionId": "...",
  "MerchantRequestId": "e84e9e10-6223-4e45-8da1-243d2d55b25e",
  "MachineId": "1000968111",
  "RequestType": 1,
  "RequestDate": "2026-03-05T10:47:56.000",
  "IsApproved": true,
  "AdditionalInfo": {},
  "FollowUpRequestOptions": [],
  "Hmac": "D4Ni+IqJev32uHlNPzz6oW8AFiGyZq7kQ8xh3QyLy8g="
}

​
Webhook Request Parameters

The following parameters define the structure of the incoming webhook notification:
Field NameTypeDescription
NayaxTransactionIdStringUnique transaction ID generated by Nayax.
MerchantRequestIdStringThe actor’s transaction reference ID.
MachineIdStringThe unique ID of the virtual terminal/machine.
RequestTypeIntegerThe transaction type identifier (e.g., 0 for Sale, 1 for Auth). Note: When calculating the HMAC, use the corresponding Enum Name (e.g., “Sale” or “Auth”) instead of the integer.
IsApprovedBooleanIndicates if the transaction was approved.
CardInfoObjectRoot object containing payment card details.
IsCardCommercialStringValues: “true”, “false”, “unknown”. Note: additional values may exist.
PaymentMethodVariantStringPayment method variant (e.g. “amex_googlepay”).
RetryAttemptsArrayList of objects containing Acquirer, AcquirerAccount, and ResponseCode.
FollowUpRequestOptionsArray[Int]Available follow-up request types (e.g. [2, 4] means Settlement and Refund are available).
HmacStringOptional. HMAC-SHA256 signature for validating authenticity. See HMAC Validation.

​
Conditional Fields

The following fields are conditional and are not always present:
  • NayaxToken: Present when the actor uses Charge Token.
  • AdditionalInfo: Present if the actor includes it in the original request. Appears in both MerchantNotification and MerchantTransactionNotification.
  • EReceiptUrl: Present when the eReceipt feature is enabled.

​
Webhook Delivery & Retries

Nayax sends webhook notifications to the URL you provided during onboarding. The system reacts to your server’s HTTP response codes as follows:
Response CodeBehavior
200 OKNotification received successfully. Nayax stops.
500Server-side error. Nayax will retry up to 3 times at varying intervals.
Any other(e.g., 401, 404) Nayax stops; no retries.
If HMAC validation fails on your end, do not return 500. A broken HMAC implementation will not be fixed by retrying. Fix the implementation and test with the examples on the HMAC Validation page.

​
See Also

Initialize Transactions

Nayax Tokens