Webhooks (DMNs)

Home    Online Payments    Webhooks (DMNs)

On this page:

Overview

Webhooks are automated server-to-server notifications Nuvei can send when a relevant transaction or event occurs. Nuvei refers to webhooks as Direct Merchant Notifications (DMNs).

DMNs include almost the same data as the HTTPS GET requests Nuvei sends to the customer’s (client-side) browser; for example, the transaction outcome, total amount, and so on. However, Nuvei sends DMNs directly to the merchant’s web server, providing reliable and secure server-to-server communication between the merchant and Nuvei.

Merchants can use DMNs to determine whether an error occurred on the customer’s side because they verify that Nuvei completed the transaction. In some cases, the response coming through the client-side Success or Error page is lost. When this occurs, the customer is not aware of the transaction outcome. Because the merchant receives the DMN directly from Nuvei, it can notify the customer of the transaction status.

The sections below describe how to integrate DMNs and how to handle DMNs.

For information about specific types of Nuvei DMNs, including parameters, see:

Integrating DMNs

When a merchant has integrated Nuvei’s DMNs, the Nuvei server sends an HTTPS GET or POST request that includes the relevant parameters to the merchant web server:

  • HTTPS GET – The URL includes parameter name-value pairs as a query string. The body of the request is empty.
  • HTTPS POST – The name-value pairs of the parameters parameters are in the body of the request.

If a merchant needs to switch between HTTPS GET and HTTPS POST, contact Nuvei’s Integration Team.

To integrate Nuvei’s DMNs, the merchant provides the URL or IP address of the DMN (webhook) listener on the merchant’s web server. The listener is usually a small module or application that constantly waits for incoming HTTPS requests from Nuvei’s server. Nuvei recommends specifying the relevant DMN URL parameter in the relevant request, depending on integration method and flow. For example, when using REST API for a payment flow, Nuvei recommends including urlDetails.notificationUrl in the /payment request.

  • DMNs can exceed 2000 characters, depending on the type of transaction. Ensure that the merchant’s server can handle DMNs this size or longer. Nuvei recommends using HTTPS POST to ensure that the server can handle the DMN. Nonetheless, HTTPS GET is supported.
  • Merchants with pre-deposit DMNs enabled need to specify a pre-deposit DMN URL that is different than the URL for other DMNs, either in the Control Panel Integration Settings or in the payment request.
  • If the merchant needs to change the URL or IP address of the DMN listener, to prevent an interruption of the service, notify Nuvei in advance.
Example DMN Integration

A merchant using HTTPS GET provides the following DMN URL:

https://myserver.com/dmn/receiveNotification

The Nuvei server sends the following HTTPS GET request:

https://myserver.com/dmn/receiveNotification?ppp_status=OK&ppp_TransactionID=547&TransactionId=45402&userid=111&merchant_unique_id=234234unique_id&customData=342dssdee&productId=12345product_id&first_name=John&last_name=Smith&email=john.smith%40email.com&totalAmount=47.25&currency=USD&Status=APPROVED

The request URL includes all the relevant parameters.

Additional Integration Steps

Nuvei can send many DMNs at one time, depending on how many transactions and/or retries of failed attempts are being relayed simultaneously. Some firewalls might recognize these as DDoS attacks and block Nuvei’s servers; for example, Incapsula. Nuvei recommends that the merchant ensures certain IP address ranges are whitelisted with local and web firewalls.

Nuvei sends DMNs from the following IP address ranges (and a DMN listener should be prepared to receive messages from them):

  • 194.247.167.1 – 194.247.167.254
  • 195.28.166.1 – 195.28.167.254
  • 87.120.10.1 – 87.120.10.254
  • 87.120.11.1 – 87.120.11.254
  • 91.220.189.1 – 91.220.189.254
  • 52.16.211.57
  • 52.17.110.204

Also, Nuvei recommends that merchants use merchant_unique_id in the DMN for mapping DMNs to transactions.

Handling DMNs

Except for pre-deposit DMNs, when Nuvei sends a DMN to the merchant’s DMN URL, the Nuvei server expects the merchant’s server to respond with HTTP status code 200 OK. After the DMN is successfully sent, Nuvei records all transactions successfully sent in that notification as Processed/Sent.

If the DMN is not successfully sent, the Nuvei database records the status of the transaction notification as In Retry, and Nuvei attempts to resend the DMN every 15 minutes for 24 hours. If the DMN fails in each retry attempt over a 24-hour period, Nuvei stops attempting to resend the DMN and records the status of the notification as Failed.

Last update iconLast modified October 2024