> ## Documentation Index
> Fetch the complete documentation index at: https://devzone.nayax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Notifications

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.

<Note>
  **Webhook URL**:
  You will provide the URL to receive the webhooks during the onboarding phase.
</Note>

## 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 JSON  theme={null}
{
    "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 JSON  theme={null}
{
  "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 Name               | Type        | Description                                                                                                                                                                           |
| :----------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NayaxTransactionId`     | String      | Unique transaction ID generated by Nayax.                                                                                                                                             |
| `MerchantRequestId`      | String      | The actor's transaction reference ID.                                                                                                                                                 |
| `MachineId`              | String      | The unique ID of the virtual terminal/machine.                                                                                                                                        |
| `RequestType`            | Integer     | The 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. |
| `IsApproved`             | Boolean     | Indicates if the transaction was approved.                                                                                                                                            |
| `CardInfo`               | Object      | Root object containing payment card details.                                                                                                                                          |
| `IsCardCommercial`       | String      | Values: "true", "false", "unknown". Note: additional values may exist.                                                                                                                |
| `PaymentMethodVariant`   | String      | Payment method variant (e.g. "amex\_googlepay").                                                                                                                                      |
| `RetryAttempts`          | Array       | List of objects containing `Acquirer`, `AcquirerAccount`, and `ResponseCode`.                                                                                                         |
| `FollowUpRequestOptions` | Array\[Int] | Available follow-up request types (e.g. \[2, 4] means Settlement and Refund are available).                                                                                           |
| `Hmac`                   | String      | Optional. 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 Code | Behavior                                                                |
| :------------ | :---------------------------------------------------------------------- |
| **200 OK**    | Notification received successfully. Nayax stops.                        |
| **500**       | Server-side error. Nayax will retry up to 3 times at varying intervals. |
| **Any other** | (e.g., 401, 404) Nayax stops; no retries.                               |

<Note>
  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](/docs/hmac-validation) page.
</Note>

## See Also

<Card icon="link" title="Nayax Tokens" href="/docs/ecom-sdk/back-end-integration/nayax-ecom-tokens" />