Overview

After the merchant sends a payment (deposit) request to Nuvei, Nuvei communicates with the customer’s bank or other funding source to transfer the funds from the customer’s account to the merchant’s account. When Nuvei receives a response from the bank or other funding source, Nuvei notifies the merchant of the result of the payment via a Direct Merchant Notification (DMN), also known as a webhook.

A payment DMN consists of the following types of parameters:

• Transaction Parameters:
  The parameters of the transaction sent to Nuvei and the parameters of the outcome (including  advanceResponseChecksum).
• Payment Parameters:
  The unprotected payment method information provided by the customer (name on card, expiration data, the last four digits of the credit card number, token, and so on).
• Customer Details:
  The customer’s personal information provided by the customer (first and last name, address, contact details, and so on). By default, the payment DMN includes these parameters. However, during merchant onboarding, you can instruct Nuvei to remove them from these DMNs.
• Other Parameters:
  Merchant custom fields and other miscellaneous parameters.

Pre-deposit DMNs

Pre-deposit DMNs allow the merchant to review the deposit prior to accepting it. The merchant usually checks the deposit amount and/or the payment method.

A pre-deposit DMN consists of the same types of parameters as other payment DMNs. However, because an actual financial transaction has not occurred, a pre-deposit DMN does not include certain parameters that appear in other payment DMNs: ppp_status, along with all financial-related parameters and 3D-Secure parameters.

Handling Pre-deposit DMNs

For merchants with pre-deposit DMNs enabled, when a customer attempts a deposit, Nuvei sends a DMN to the merchant’s pre-deposit DMN URL. Nuvei expects to receive a response from the merchant. Possible response values are:

• action=APPROVE – Nuvei processes the deposit.
• action=DECLINE – Nuvei does not process the deposit.

If Nuvei does not receive a response from the merchant, the transaction attempt is declined. Nuvei does not attempt to re-send pre-deposit DMNs.

If a merchant using the Payment Page integration method declines the attempt and has enabled the User Trap feature, the customer remains on the payment page and can retry the deposit with different payment information. If the merchant declines the attempt and User Trap is not enabled, the customer is redirected to the merchant’s failure URL, specified in the Control Panel Integration Settings or in the payment request.

Also, when a merchant using the Payment Page integration method declines the attempt, Nuvei can display a pop-up message providing information to the customer.

Example Pre-deposit DMN Response

action=DECLINE, message='Your attempt has been declined'

Authenticating the DMN

Payment and pre-deposit DMNs include advanceResponseChecksum that merchants can use to verify Nuvei sent the DMN and that it was not manipulated by any external parties. Re-calculate the checksum using values in the DMN and then compare it to the advanceResponseChecksum in the DMN. If they are the same, then the DMN is authentic.

To authenticate a payment or pre-deposit DMN, follow these steps:

1. Concatenate into a string the values of the following DMN parameters in this exact order:
   • totalAmount
   • currency
   • responseTimeStamp (in GMT)
   • ppp_TransactionID
   • Status
   • productId
     In the DMN, blank spaces appear as + (plus) symbols. Replace these + symbols with blank spaces.
2. Add merchantSecretKey to the beginning of that string.
3. Encrypt the entire string with SHA-256 or MD5 encryption, depending on the SiteId configuration.
   Use encoding passed from the merchant site to create the encryption. The default encoding is UTF-8 (unless the encoding input parameter specifies otherwise).
4. Compare the result to the advanceResponseChecksum in the DMN. If they match, Nuvei sent the DMN.

Example Values for Payment or Pre-deposit Checksum

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

With these values, the string before encryption is:

AJHFH9349JASFJHADJ9834115USD2020-11-13.13:22:343453459APPROVEDYour Product

After SHA-256 encryption, the advanceResponseChecksum should be:

6501f10efbfc9599d3e79fc0e24a5662e60292b0025834d0e2d09c58945aedbb

DMNs for APM Transactions

For APM transactions, the possible Status values are:

• APPROVED: The APM provider processed and approved the transaction.
• DECLINED: The APM provider processed and declined the transaction.
• PENDING: The APM provider is processing the transaction.
• UPDATE: Indicates an update to the transaction’s status. Relevant only for certain APMs that handle North American bank transfers. For details, see the relevant APM guide.

Depending on the APM, transactions can be processed synchronously or asynchronously. Asynchronous processing can involve time delays ranging from a few seconds to several days. After Nuvei receives the final result (APPROVED or DECLINED) from the APM provider, Nuvei sends the merchant an additional DMN containing the same transaction data as the previous DMN and the final Status of the transaction.

Example Payment DMN with Status=PENDING

...'ppp_status=PENDING&PPP_TransactionId=257354778&userid=&merchant_unique_id=5CXS9TWCNFJP&customData=&productId=&first_name=Test&last_name=Test&email=test%40test.com&currency=EUR&clientUniqueId=5CXS9TWCNFJP&Status=PENDING&customField1=merchantName&customField2=merchantName&customField3=merchantName&customField4=merchantName&customField5=&customField6=&customField7=&customField8=&customField9=merchantName&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=billing_address1&address2=&country=Germany&state=&city=billing_city&zip=9999&phone1=123456&phone2=&phone3=&client_ip=192.168.5.1&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&ExErrCode=0&ErrCode=0&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=197846&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=&unknownParameters=&payment_method=apmgw_expresscheckout&Id=&merchant_id=4960497427404081578&responseTimeStamp=2020-03-21.15:42:48&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=ralphv5%40safecharge.com&cardCompany=&eci=&user_token_id=testPaypal&userPaymentOptionId=47865938&TransactionId=1110000000004579353&ExternalaccountId=3ZPD52JF4XY4S&externalAccountDescription=account_id:3ZPD52JF4XY4S%7Cemail:ralphv5%40safecharge.com&externalTransactionId=40T14511AV6745111&APMReferenceID=B586E22F7608F7416E201A9EBC58AF69&orderTransactionId=1044765948&totalAmount=20.00&dynamicDescriptor=%3F&Reason=&ReasonCode=0&item_name_1=NA&item_number_1=&item_amount_1=20.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20200321&type=DEPOSIT&clientRequestId=20200321174049&relatedTransactionId=&apmPayerInfo=Address:Confirmed%3BPayer:verified%3BCountry:GB%3BFirstName:Ralph%3BLastName:Van+Coevorden&responsechecksum=0606f157a5075d1d4dc11db7279deb9afd2b933575845bd71e5db99747db30d3&advanceResponseChecksum=1b85115ce2647e02461a4ad93d5a04873cb049470ec1e82b6d66d205ef9e4cfe',

Example Payment DMN with Status=APPROVED

...'ppp_status=OK&PPP_TransactionId=257354778&userid=&merchant_unique_id=5CXS9TWCNFJP&customData=&productId=&first_name=Test&last_name=Test&email=test%40test.com&currency=EUR&clientUniqueId=5CXS9TWCNFJP&Status=APPROVED&customField1=merchantName&customField2=merchantName&customField3=merchantName&customField4=merchantName&customField5=&customField6=&customField7=&customField8=&customField9=merchantName&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=billing_address1&address2=&country=Germany&state=&city=billing_city&zip=9999&phone1=123456&phone2=&phone3=&client_ip=192.168.5.1&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&ExErrCode=0&ErrCode=0&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=197846&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_expresscheckout&Id=&merchant_id=4960497427404081578&responseTimeStamp=2020-03-21.15:42:49&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=ralphv5%40safecharge.com&cardCompany=&eci=&user_token_id=testPaypal&userPaymentOptionId=47865938&TransactionId=1110000000004579353&ExternalaccountId=3ZPD52JF4XY4S&externalAccountDescription=account_id:3ZPD52JF4XY4S%7Cemail:ralphv5%40safecharge.com&externalTransactionId=40T14511AV6745111&APMReferenceID=B586E22F7608F7416E201A9EBC58AF69&orderTransactionId=1044765948&totalAmount=20.00&dynamicDescriptor=%3F&Reason=&ReasonCode=0&item_name_1=NA&item_number_1=&item_amount_1=20.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20200321&type=DEPOSIT&clientRequestId=20200321174049&relatedTransactionId=&apmPayerInfo=Address:Confirmed%3BPayer:verified%3BCountry:GB%3BFirstName:Ralph%3BLastName:Van+Coevorden&responsechecksum=7721cf5aea6773ac011df0f2224481041ecfff2ebc08bd265ec5b10c3f5ea4d5&advanceResponseChecksum=2164dc8cd5d93a4529dd6894f20563639ac22b953b06cdd0c5c4f1fb4e2cd3d3',

Payment and Pre-deposit DMN Parameters