Developers

Handling Direct Merchant Notifications

After the merchant sends a transaction to Nuvei, Nuvei communicates with the customer’s bank to transfer the deposit from the customer’s account to the merchant’s account. When Nuvei receives a response from the bank, Nuvei notifies the merchant of the result of the deposit via DMN.

DMNs are useful for determining when an error occurred on the customer’s side by verifying that the Nuvei server completed the transaction. There might be cases when the response coming through the Success or Error page is lost. When this occurs, the customer is not aware of the transaction outcome. As the merchant receives the DMN directly from Nuvei, the merchant can contact the customer to notify them of the status of the transaction.

Information Included in the Deposit DMN

• Transaction Parameters: The parameters of the transaction originally sent to the Cashier and the parameters of the outcome of the PPP’s work (including the response checksum).
• Payment Parameters: The unprotected payment method information, as updated by the customer in the Deposit page (name on card, expiration data, the last four digits of the credit card number, token, etc.).
• Customer Details: The customer’s personal information, as updated by the customer in the Deposit page (first and last name, the address, the contact details, etc.). By default, these parameters are returned, however, during your configuration you can instruct Nuvei to remove them from the response.
• Other Parameters: Merchant custom fields and other miscellaneous parameters.

Integrating DMNs

When the merchant integrates with Nuvei’s DMN, the Nuvei server executes an HTTPS request directly to the merchant web server without passing through the customer’s browser.

To integrate with the DMN, the merchant must provide to Nuvei the IP address of the URL that leads to the callback entry point to your server. This is usually a small module/application, which constantly listens and waits for incoming HTTPS requests from Nuvei’s server.

When the Nuvei server sends data via the DMN, Nuvei executes an HTTPS GET/POST request to the merchant’s server that includes the relevant parameters in the HTTPS GET/POST request.

Example:

The merchant provides the following DMN URL:

https://myserver.com/SafeCharge/dmn/receiveNotification

The Nuvei server calls back by using the HTTPS GET/POST request to the provided DMN URL. The request includes all the relevant data for the HTTPS GET/POST parameters.

For example, the Nuvei server executes the following HTTPS GET/POST request to the merchant’s server to send the response via DMN:

https://myserver.com/SafeCharge/dmn/receiveNotification?ppp_status=OK&PPP_TransactionID=547&TransactionID=45402&userid=111&merchant_unique_id=234234unique_id&customData=342dssdee&productId=12345product_id&first_name=Diyan&last_name=Yordanov&email=dido%40domain.com&totalAmount=47.25&currency=USD&Status=APPROVED

Notes:

• If using HTTP GET – the body of the request remains empty.
• If using HTTP POST – the parameters are sent in the body of the request.
• If you need to switch the merchant configuration between HTTPS GET and HTTPS POST, then you need to contact Nuvei’s Integration Team.

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, such as Incapsula, may recognize these as DDoS attacks and block Nuvei. It is recommended that merchant ensure that the following IP ranges are whitelisted with local and web firewalls.

Nuvei sends DMNs from the following IP addresses:

Test: IP DMN server range is: 91.220.189.12–91.220.189.16 / 52.16.211.57, 52.17.110.204

Live: Nuvei has several IP addresses for live DMN servers. A listener should be prepared to receive messages from the following IP addresses: 194.247.167.32 / 87.120.10.184 – 87.120.10.187

When using the DMN, Nuvei recommends that merchants use the merchant_unique_id parameter.

The merchant_unique_id parameter enables mapping between responses coming from DMN data.

To integrate DMNs, provide Nuvei with the IP and URL of the DMN listener in use.

Receiving DMN Notifications

When the DMN notification is sent to the merchant’s DMN URL, the Nuvei server expects the merchant’s server to respond with Status code 200 – OK. After the DMN is successfully sent, all the transactions that were successfully sent in that notification are recorded in the Nuvei database as Processed/Sent.

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

If the IP address of your DMN listener has to be changed, the merchant must notify Nuvei in advance to prevent an interruption of the service.

Alternative Payment Methods (APMs) and DMN Notifications

After processing transactions through an APM, Nuvei returns a DMN that includes the result of the transaction in  status and in payment_method, which identifies the payment method that the customer selected.

There are three possible values of status:

• Approved: The transaction was processed and approved by the APM processer.
• Declined: The transaction was processed by the APM processer and declined.
• Pending: The transaction is being processed by the APM processer.

Transactions are processed synchronously and asynchronously depending on the APM. When an APM processes the transaction asynchronously, the length of time that passes before the transaction is processed can be several seconds to several days. After the final result (Approve or Decline) is received from the APM processor, Nuvei sends the merchant an additional DMN call with the same transaction data as the previous DMN call, with the exception of status, which contains the final status of the transaction.

Authenticating a DMN Response Checksum

To authenticate a DMN callback, Nuvei includes a checksum among the HTTPS parameters in the DMN. This checksum should be used to verify that the DMN callback was sent by Nuvei. The checksum uses SHA-256 encryption same as the checksum generated when sending HTTPS requests to Nuvei’s server.

The HTTPS parameter containing the DMN checksum is named advanceResponseChecksum.

To authenticate a DMN response checksum:

1. Concatenate the following parameters in the exact order as follows:
   The merchant secret key followed by the parameters received from the DMN callback:
   totalAmount, currency, responseTimeStamp (in GMT), PPP_TransactionID, Status, productId.
   (If this parameter was not sent to Nuvei, then concatenate all item names instead. For example, Testproduct1 and Testproduct.)
2. Use SHA-256 encryption on the result string of the concatenation. Use encoding passed from the merchant site to create the encryption. The default encoding is UTF-8 (unless the encoding input parameter specifies otherwise).
   Once the DMN response is received from Nuvei, compare the SHA-256 result to the advanceResponseChecksum parameter in the DMN callback.

Example of DMN Response Checksum:

Merchant Secret Key: AJHFH9349JASFJHADJ9834
totalAmount: 115
currency: USD
responseTimeStamp: 2020-03-14.16:22:34
PPP_TransactionID: 3453459
Status: APPROVED
productId: Your Product

After concatenation you have the following string:

AJHFH9349JASFJHADJ9834115USD2016-11-13.13:22:343453459APPROVEDYour Product

The calculated checksum is after using SHA-256 encryption:

6501f10efbfc9599d3e79fc0e24a5662e60292b0025834d0e2d09c58945aedbb

Pre-deposit DMN

The purpose of the pre-deposit DMN is the merchant to review the deposit prior accepting the deposit. The merchant usually checks the amount of the deposit and/or the deposit payment method.

Information Included in the Pre-deposit DMN

• Transaction Parameters: The parameters of the transaction originally sent to the Cashier and the parameters of the outcome of the PPP’s work (including the response checksum).
  Missing parameters: Since no actual fiscal transaction has been performed the following parameters are not present in the DMN: ppp_status, along with all fiscal related parameters and threeD parameters
• Payment Parameters: The unprotected payment method information, as updated by the customer in the Deposit page (name on card, expiration data, the last four digits of the credit card number, token, etc.).
• Customer Details: The customer’s personal information, as updated by the customer in the Deposit page (first and last name, the address, the contact details, etc.). By default, these parameters are returned, however, during your configuration you can instruct Nuvei to remove them from the response.
• Other Parameters: Merchant custom fields and other miscellaneous parameters.

Handling Pre-deposit DMNs

After the customer attempts a deposit, Nuvei sends notification to the merchant’s pre-deposit DMN URL. Nuvei expects to receive from the merchant a DMN message response. Possible response values are as follows:

• Action: Approve – The deposit will be processed
• Action: Decline – The deposit is declined.

If the pre-deposit DMN is not successfully sent, the transaction attempt is declined. The pre-deposit DMN does not attempt to resend the notification.

DMN Parameters

All parameters are case sensitive.