Overview
After the merchant sends a payment (deposit) transaction request 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 a Direct Merchant Notification (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.
Deposit DMN Information
- 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 responsechecksum
). - Payment Parameters:
The unprotected payment method information provided by the customer on 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 provided by the customer on the Deposit page (first and last name, address, 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 the IP address of the URL of the callback entry point on 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 URL
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¤cy=USD&Status=APPROVED
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 the merchant ensures that the following IP ranges are whitelisted with local and web firewalls.
Nuvei sends DMNs from the following IP addresses (a 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
When using the DMN, Nuvei recommends that merchants use merchant_unique_id
, which 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 DMNs
When the DMN 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, then the merchant must notify Nuvei in advance to prevent an interruption of the service.
APMs and DMNs
After processing an alternative payment method (APM) transaction, the Nuvei system returns a DMN which includes payment_method
(the payment method selected by the customer), and Status
(the result of the transaction).
Status
has four possible values:
- APPROVED: The transaction was processed and approved by the APM processor.
- DECLINED: The transaction was processed by the APM processor and declined.
- PENDING: The transaction is being processed by the APM processor.
- UPDATE: Indicates an update to the transaction’s status.
APM transactions are processed synchronously or asynchronously depending on the APM.
Asynchronous transaction processing often involves time delays ranging from a few seconds to several days. After the final result (APPROVE or DECLINE) is received from the APM processor, Nuvei sends the merchant an additional DMN containing the same transaction data as the previous DMN and the final Status
of the transaction.
Authenticating a DMN Checksum
To help you to authenticate the DMN callback, Nuvei includes a checksum parameter named advanceResponseChecksum
in the DMN, which can be used to verify that the DMN callback was sent by Nuvei. The advanceResponseChecksum
in the DMN is created using SHA-256 or MD5 encryption, depending on the SiteId
configuration.
Re-calculate the checksum
based on the data received in the DMN. (Effectively you are re-creating the same checksum
value that was sent in the original HTTPS request to Nuvei’s server.) Compare this to the advanceResponseChecksum
. If they are the same then the DMN is authentic.
To authenticate a DMN response checksum:
- Concatenate the following parameters in the exact order as follows:
merchantSecretKey
(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.
- Blank spaces are replaced with a “+” (plus) symbol in the DMN. Before calculating the hash, these + symbols should be replaced with blank spaces.
- 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 received in the DMN callback. If they are the same then the DMN is authentic.
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:
AJHFH9349JASFJHADJ9834115USD2020-11-13.13:22:343453459APPROVEDYour Product
Apply SHA-256 encryption to the string, for example:
6501f10efbfc9599d3e79fc0e24a5662e60292b0025834d0e2d09c58945aedbb
Authenticating a Subscription DMN Checksum
Clients using the Nuvei subscription system receive DMN callbacks with types subscription or subscriptionPayment.
These two DMN types are calculated by concatenating all of the parameter values in the callback in the exact order that they are sent in, adding merchantSecretKey
to the end of the string, and then passing the resulting string through SHA-256 or MD5 encryption, depending on the SiteId
configuration.
Example of Subscription DMN Response Checksum
'dmnType' => 'subscription', 'merchant_id' => 111111222222333333, 'merchant_site_id' => 1111111, 'subscriptionId' => '123123', 'subscriptionState' => 'ACTIVE', 'planId' => '12345', 'templateId' => '123456', 'productId' => '12345', 'productName' => 'Rebilling Plan', 'userPaymentOptionId' => '101956858', 'upoRegistrationDate' => '20240111', 'payment_method' => 'cc_card', 'nameOnCard' => 'Cardholder', 'expMonth' => '11', 'expYear' => '25', 'Token' => 'awAxADEARgBkAEYAZABuADAAZABkAGQAagBVADgAagA3AGoASwBHAHoAbwAmAEgAKQBHAGUAcQBNAEgAUQBLAD8AcABRAHgATQArAFQAYQB3AHQAJQBAACsASwB2ADUAUQAsAEoAMwA=', 'cardNumber' => '4****1111', 'cardType' => 'visa', 'uniqueCC' => '4E+K4R18rBmltRfq9OHSG65FHXA=', 'bin' => '476134', 'lastFourDigits' => '1111', 'user_token_id' => 'UserToken', 'email' => 'test@test.com', 'country' => 'United Kingdom', 'responseTimeStamp' => '2024-01-12.08:29:07', 'responsechecksum' => 'e9ea781f100e013f3270848cb9fb64e40da956ba40259ff93967aa1ce6366e7f',
After concatenating the parameter values, the secret key is added:
subscription1111112222223333331111111123123ACTIVE1234512345612345Rebilling Plan10195685820240111cc_cardCardholder1125awAxADEARgBkAEYAZABuADAAZABkAGQAagBVADgAagA3AGoASwBHAHoAbwAmAEgAKQBHAGUAcQBNAEgAUQBLAD8AcABRAHgATQArAFQAYQB3AHQAJQBAACsASwB2ADUAUQAsAEoAMwA=4****1111visa4E+K4R18rBmltRfq9OHSG65FHXA=4761341111UserTokentest@test.comUnited Kingdom2024-01-12.08:29:07[Secret key]
Apply SHA-256 encryption to the string:
69130454aa3345f5d21d145c08e1a7b927574ac3d23f7826bfd8991b8a876d0b
Authenticating an Events API Webhook Checksum
To authenticate a Webhook, Nuvei sends a checksum
field in the header of the webhook, which you can use to verify that the webhook was sent by Nuvei, and that it was not manipulated by external parties.
The checksum
is generated using a SHA-256 encryption, the same as with the checksum
generated when sending the original HTTPS request to Nuvei’s server.
To authenticate an events API Webhook checksum:
- Edit the webhook payload from the JSON to produce a string without new-line characters and unnecessary spaces.
Example Original JSON
{ "ClientId": 151999723, "EventType": "Chargeback", "EventDateUTC": "2022-05-18T08:21:23.3749665Z", "EventCorrelationId": "0bd473cb-093b-4540-971b-6f0773be755b", "Chargeback": { "Date": "09/04/2018 10:37:17", "StatusCategory": "Regular", "Type": "Chargeback", "Status": null, "Amount": 10.25, "Currency": "eur", "ChargebackReason": "10.4 - Other Fraud-Card Absent Environment", "ReasonMessage": "Other Fraud-Card Absent Environment", "DisputeDueDate": null }, "TransactionDetails": { "TransactionId": 382511946222, "TransactionDate": "09/01/2018 10:37:17", "ClientUniqueId": null, "AcquirerName": "Demo Bank", "MaskedCardNumber": "1***********1234", "Arn": "05295314304000000000456" } }
Example Updated JSON
{"ClientId":151999723,"EventType":"Chargeback","EventDateUTC":"2022-05-18T08:21:23.3749665Z","EventCorrelationId":"0bd473cb-093b-4540-971b-6f0773be755b","Chargeback":{"Date":"09/04/2018 10:37:17","StatusCategory":"Regular","Type":"Chargeback","Status":null,"Amount":10.25,"Currency":"eur","ChargebackReason":"10.4 - Other Fraud-Card Absent Environment","ReasonMessage":"Other Fraud-Card Absent Environment","DisputeDueDate":null},"TransactionDetails":{"TransactionId":382511946222,"TransactionDate":"09/01/2018 10:37:17","ClientUniqueId":null,"AcquirerName":"Demo Bank","MaskedCardNumber":"1***********1234","Arn":"05295314304000000000456"}}
Example Merchant Secret Key
DlgOtMNE0DhcJelIQLzc1PN0zcEqugkplNRTeYorjRDgAX0aM4rab7BT9OVF2iuY
- Concatenate the
merchantSecretKey
and the updated JSON into one string (without any characters in the middle):
Example Concatenated String
DlgOtMNE0DhcJelIQLzc1PN0zcEqugkplNRTeYorjRDgAX0aM4rab7BT9OVF2iuY{"ClientId":151999723,"EventType":"Chargeback","EventDateUTC":"2022-05-18T08:21:23.3749665Z","EventCorrelationId":"0bd473cb-093b-4540-971b-6f0773be755b","Chargeback":{"Date":"09/04/2018 10:37:17","StatusCategory":"Regular","Type":"Chargeback","Status":null,"Amount":10.25,"Currency":"eur","ChargebackReason":"10.4 - Other Fraud-Card Absent Environment","ReasonMessage":"Other Fraud-Card Absent Environment","DisputeDueDate":null},"TransactionDetails":{"TransactionId":382511946222,"TransactionDate":"09/01/2018 10:37:17","ClientUniqueId":null,"AcquirerName":"Demo Bank","MaskedCardNumber":"1***********1234","Arn":"05295314304000000000456"}}
- Apply the hashing algorithm to the result string of the concatenation (using the encryption method specified in the merchant configuration).
In this example, the merchant is configured to use SHA-256 encryption, the calculatedchecksum
is:745e3e83f7ef6415a43d541fdae21112ac4241f4a5b681e193f519b6a01ae584
- Compare the calculated result to the
checksum
value in the webhook header.
If they match, the webhook was successfully received.
Pre-deposit DMN
The purpose of the pre-deposit DMN is for the merchant to review the deposit prior to accepting the deposit. The merchant usually checks the amount of the deposit and/or the deposit payment method.
Pre-deposit DMN Information
- 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 responsechecksum
).
Missing parameters: Since no actual financial transaction has been performed, the following parameters are not present in the DMN:ppp_status
along with all financial-related parameters and 3DS parameters. - Payment Parameters:
The unprotected payment method information provided by the customer on 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 provided by the customer on the Deposit page (first and last name, address, 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 a 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 is 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
Parameters | Mandatory | Description |
---|---|---|
ppp_status | Yes | The status of the transaction. OK indicates that the transaction was approved. Pending occurs only for APM transactions in which the final status is not immediately returned. FAIL indicates that the transaction was declined or there was an error. |
ppp_TransactionID | Yes | A unique 64-bit number that identifies the Nuvei payment page transaction. |
totalAmount | Yes | Total amount of all the items of a customer's purchase sent to the payment page. For merchants with the currency conversion feature enabled, the value of this parameter is the original total amount of items before the currency is converted. |
currency | Yes | Currency selected by the customer that was sent to the payment page. For merchants with the currency conversion feature enabled, the value of this parameter is the original currency sent to the payment page. |
convertedCurrency | No | The final currency selected by the customer on the payment page in which the transaction was processed with the acquirer bank. This feature is available only for merchants with currency conversion enabled. |
convertedAmount | No | The final amount of the transaction after the customer converted the currency through the payment page. This is the amount that was processed through the acquirer bank. This feature is available only for merchants with currency conversion enabled. |
responseChecksum | Yes | Deprecated checksum parameter. |
advanceResponseChecksum | Yes | Advanced response checksum that ensures that the DMN callback is authentic. |
TransactionID | No | A unique 64-bit number that identifies the fiscal transaction in the Nuvei payment gateway. If no fiscal transaction actually occurred, ppp_status is FAIL and this parameter is empty. |
transactionType | No | The value of this parameter shows the type of transaction, Sale, Auth, Credit, Void, Chargeback, or Modification. This service is available only upon request. |
Status | No | Status of the Nuvei Payment Gateway fiscal transaction: APPROVED, SUCCESS, DECLINED, ERROR, PENDING, UPDATE. If no fiscal transaction actually occurred, ppp_status is FAIL and this parameter value is DECLINED. |
userPaymentOptionId | No | Each time a customer uses a payment method, Nuvei assigns a unique ID to that payment method. The next time the customer uses a payment method in which Nuvei has already assigned an ID, the ID is returned as the value of this parameter. When a new payment method is used, the value of this parameter is empty. |
externalTransactionId | No | A unique ID generated by Nuvei that represents the APM transaction. |
userid | No | The string that you have passed as the userid parameter initially when making the HTTPS POST request to the payment page. |
customData | No | The ID that you have passed as the customData parameter initially when making the first request to the payment page. |
productId | No | The ID that you have passed as the productId parameter initially when making the first request to the payment page. |
first_name | No | Firstname of the user that processes a transaction, if supplied. |
last_name | No | Lastname of the user that processes a transaction, if supplied. |
No | Email of the user that processes a transaction, if supplied. | |
externalEmail | No | PayPal only. Email address returned from external alternative payment method. This parameter is the email address of the PayPal account. |
cardCompany | No | The name of the credit card company. The possible values are: Visa, Amex, Mastercard, Diners, Diners, Discover, JCB, LaserCard, Maestro, Solo, and Switch. This value is provided for payment_method values such as cc_card, ppp_ApplePay, and ppp_GooglePay. |
customFieldX | No | Fifteen custom fields that you may use by replacing X with 1 to 15. The customFieldX that you have passed as the customFieldX parameter initially when making the first request to the Public Payment Page. |
invoice_id | No | The invoice_id that you have passed as the invoice_id parameter initially when making the first request to the Public Payment Page. |
address1 | No | Address1 of the user that processes a transaction, if supplied. |
address2 | No | Address2 of the user that processes a transaction, if supplied. |
country | No | Country of the user that processes a transaction, if supplied. |
state | No | State of the user that processes a transaction, if supplied. |
city | No | City of the user that processes a transaction, if supplied. |
zip | No | ZIP code of the user that processes a transaction, if supplied. |
phone1 | No | Phone1 of the user that processes a transaction, if supplied. |
phone2 | No | Phone2 of the user that processes a transaction, if supplied. |
phone3 | No | Phone3 of the user that processes a transaction, if supplied. |
nameOnCard | No | Name on the card of the customer that processes a transaction, if supplied. |
cardNumber | No | Masked card number of the user that processes a transaction, if supplied. The parameter becomes mandatory if the payment method is a credit card or debit card. If another payment method is used, then an empty string is returned. |
expMonth | No | Expiration month of the card used for this transaction, if supplied. The parameter becomes mandatory if the payment method is credit card. If another payment method is used an empty string is returned. |
expYear | No | Expiration year of the card used for this transaction, if supplied. The field becomes mandatory if the payment method is credit card. If another payment method is used an empty string is returned. |
Token | No | Tokens are strings of random digits, letters, and symbols characters that represent a single credit card number. When you submit your customers' full credit card number, Nuvei provides you with a token in the response that represents your customers' credit card. The next time a returning customer completes a transaction, you send Nuvei the token instead of the customer's credit card information. Nuvei returns this value in the response as well as the DMN response. |
tokenId | No | Deprecated. ID of the token. Used in combination with the token. |
orderTransactionId | No | This value is generated by PlayTech for transactions processed through PlayTech's Cashier. This value helps to identify individual transactions that are related to the same Order ID. |
3dflow | No | This parameter indicates if the transaction was processed through the 3D-Secure flow or not: 0: Not processed through 3D-Secure. 1: Processed through 3D-Secure. Note: This parameter is currently only returned for 3D-Secure v1. |
promoCode | No | This value is a promotional code you define that you can use to apply discounts to your products or services. Nuvei does not apply any discounts and only returns the value you sent in the HTTPS request. |
ExErrCode | No | When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the specific error. |
ErrCode | No | When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error. |
errApmCode | No | The error code for a transaction processed through an APM returned by the APM. |
errApmDescription | No | The error description for a transaction processed through an APM returned by the APM. |
errScCode | No | The error code for a transaction processed through an APM returned by Nuvei. |
errScDescription | No | The error description for a transaction processed through an APM returned by Nuvei. |
AuthCode | No | An authorization code (up to 35 characters) that is returned for each approved and pending transaction. |
acquirerId | No | Acquiring bank unique ID. The value 0 represents an invalid bank code. |
acquirerBank | No | The name of the acquirer bank or payment processor of the processed transaction. |
bin | No | The first six digits from the credit card number for identifying the processing bank. The rest of the number is not displayed. |
shippingCountry | No | Shipping country of the user that processes a transaction, if supplied. An empty string is returned when the shipping feature is not enabled. |
shippingState | No | Shipping state of the user that processes a transaction, if supplied. An empty string is returned when the shipping feature is not enabled. |
shippingCity | No | Shipping city of the user that processes a transaction, if supplied. An empty string is returned when the shipping feature is not enabled. |
shippingAddress | No | Shipping address of the user that processes a transaction, if supplied. An empty string is returned when the shipping feature is not enabled. |
shippingZip | No | Shipping ZIP code of the user that processes a transaction, if supplied. An empty string is returned when the shipping feature is not enabled. |
shippingFirstName | No | Shipping first name of the user that processes a transaction, if supplied. An empty string is returned when the shipping feature is not enabled. |
shippingLastName | No | Shipping last name of the user that processes a transaction, if supplied. An empty string is returned when the shipping feature is not enabled. |
shippingPhone | No | Shipping phone of the user that processes a transaction, if supplied. An empty string is returned when the shipping feature is not enabled. |
shippingCell | No | Shipping mobile phone of the user that processes a transaction, if supplied. An empty string is returned when the shipping feature is not enabled. |
shippingMail | No | Shipping email of the user that processes a transaction, if supplied. An empty string is returned when the shipping feature is not enabled. |
total_discount | No | The total amount of all the values of the item_discount_X parameter combined. |
total_handling | No | The handling parameter that the merchant passed to Nuvei in the HTTPS POST request. |
total_shipping | No | The shipping parameter that the merchant passed as the shipping parameter initially when making the first request to the payment page. |
total_tax | No | The total tax parameter that you have passed initially when making the first request to the payment page. |
buyButtonProductBundleId | No | Contains the ID of the product bundle when the buy button payment was processed. |
merchant_site_id | Yes | The ID, provided by Nuvei, which uniquely defines a particular merchant customization. |
requestVersion | Yes | The version of the request. The current version is 3.0.0. |
message | Yes | A message from Nuvei about the transaction that has been done. |
merchantLocale | No | The language and country of the user in ISO code in the following format: [language ISO]_[country ISO] The possible values of this parameter are provided below: English (US): en_US English (UK): en_UK German: de_DE Chinese (PRC): zh_CN Hebrew: iw_IL French: fr_FR Dutch (Standard): nl_NL Greek: el_GR Indonesia: in_ID Italian: it_IT Japanese: ja_JP Korean: ko_KR Lithuanian: lt_LT Spanish: es_ES English (Canada): en_CA English (Australia): en_AU Russian: ru_RU Arabic: ar_AA Norwegian: no_No Portuguese: pt_BR Swedish: sv_SE Turkish: tr_TR Slovenian: sl_SI Danish: da_DK Romanian: ro_RO Bulgarian: bg_BG Polish: pl_PL Hungarian: hu_HU Vietnamese: vi_VL |
unknownParameters | No | When an unknown parameter is sent to Nuvei, for example, a misspelled parameter, Nuvei returns this parameter with the value being the parameter that Nuvei did not recognize. This enables you to identify and correct any erroneous parameters. |
payment_method | Yes | The payment method used for this transaction such as cc_card, ppp_ApplePay, and ppp_GooglePay. |
ID | No | Hebrew ID |
merchant_id | Yes | The unique merchant ID supplied by Nuvei. |
responseTimeStamp | Yes | Time set by Nuvei, when the response is received from the Gateway. |
buyButtonProductId | No | Contains the ID of the product when the buy button payment was processed. |
dynamicDescriptor | Yes | Dynamic descriptor passed to the Nuvei Gateway for the current transaction. |
Reason | No | A reason that the Gateway returned if the transaction fails. See Gateway specification. N/A is returned if it is not a regular transaction. |
ReasonCode | No | A reason code that the Gateway returned if the transaction fails. See Gateway specification. N/A is returned if it is not a regular transaction. |
item_name_X | Yes | The item name that you have passed as the item_name_X parameter initially when making the first request to the Public Payment Page. N/A is displayed if it is not a regular transaction. |
item_number_X | No | The item number that you have passed as the item_number_X parameter initially when making the first request to the Public Payment Page. N/A is displayed if it is not a regular transaction. |
item_amount_X | Yes | The item amount that you have passed as the item_amount_X parameter initially when making the first request to the Public Payment Page. N/A is displayed if it is not a regular transaction. |
item_quantity_X | No | The item quantity that you have passed as the item_quantity_X parameter initially when making the first request to the Public Payment Page. N/A is displayed if it is not a regular transaction. |
item_discount_X | No | The item discount that you have passed as the item_discount_X parameter initially when making the first request to the Public Payment Page. N/A is displayed if it is not a regular transaction. |
item_handling_X | No | The item handling that you have passed as the item_handling_X parameter initially when making the first request to the Public Payment Page. N/A is displayed if it is not a regular transaction. |
item_shipping_X | No | The item shipping that you have passed as the item_shipping_X parameter initially when making the first request to the Public Payment Page. N/A is displayed if it is not a regular transaction. |
appliedPromotions | No | Used to indicate that the purchase was done using a promotion (or coupon). This parameter contacts all successfully applied promotion codes. If more than one promotion was used, the promotion names are separated by a # character. |
client_ip | Yes | The IP address from which the client made the purchase. |
uniqueCC | No | A unique value assigned to every credit card number. |
user_token | No | This parameter shows if the payment page required existing customers to register for the specific transaction. When user_token=register, the payment page required the customer to register even if they are already registered in the system. The previously registered payment methods are deleted. When user_token=auto, the payment page checked the Nuvei database to determine if the customer was already registered. |
user_token_id | No | This parameter is a unique identifier for each customer generated by the merchant. |
externalAccountId | No | This parameter is the customer's username or unique identifier provided by the APM. This value is not returned for all APMs. |
APMReferenceID | No | This parameter is Nuvei's reference identifier from Nuvei for each APM. |
webMasterId | No | The webMasterId you passed in the request to the Public Payment Page. |
finalFraudDecision | No | This parameter indicates the final fraud analysis decision made by Nuvei Risk management. Possible values: 1. Accept: The transaction is redirected for processing. 2. Reject: The transaction is rejected according to a Fraud Filter. |
systemId | No | The value of this parameter is a numeric identifier generated by Nuvei for the fraud analysis service/tool. |
systemName | No | The value of this parameter is an internal Nuvei name for the fraud analysis service/tool. |
systemDecision | No | The Risk decision. It may be one of the following predefined string values: 1. None: No decision was rendered. 2. Accept: Transaction is recommended for processing 3. Reject: Transaction is rejected due to a high probability of fraud. 4. Review: Transaction should be manually reviewed before processing. 5. Error: An error occurred during the analysis. No decision is rendered. |
rules | No | This parameter lists all the rules that were activated by the transaction as part of Nuvei's fraud checks. This parameter is only returned when the value of the SystemDecision parameter is Reject or Review.The format of the value of the Rules parameter is URL encoded. For example: rules=ID%3D1000000260%2CDescription%3DCC+is+changing+more+than+1 +Email+Last+24+H+Review+general In the URL encoded response: %2C represents & and separates the multiple rule values. %3D represents '='. |
Cvv2Reply | No | CVV2 (card verification value) response. Possible values: M – CVV2 Match N – CVV2 No Match P – Not Processed U – Issuer is not certified and/or has not provided Visa with the encryption keys. S – CVV2 processor is unavailable. |
AvsCode | No | The AVS (address verification) response. The following values may be returned: A – The street address matches, but the ZIP code does not. W – Whole 9-digit ZIP code matches, but the street address does not. Y – Both the 5-digit ZIP code and the street address match. X – An exact match of both the 9-digit ZIP code and the street address. Z – Only the 5-digit ZIP code matches, the street code does not. U – Issuer Unavailable S – Not Supported R – Retry B – Not Authorized (declined) N – Both street address and ZIP code do not match. |
cardType | No | The type of card used in the transaction. Possible values: credit or debit. |
upoRegistrationDate | No | The date that the UPO was registered in the following format: YYYMMDDHHmmss |
isPartialApproval | No | Indicates if the transaction was requested for partial approval (1) or not (0). |
requestedAmount | No | For a partial approval transaction, represents the amount requested. It can be greater than the amount that was able to be processed (totalAmount). |
partialApprovalStatus | No | For a partial approval transaction, indicates the status of the approval. Possible values: PENDING, APPROVED, CANCELLED, AUTO_VOID |
requestedCurrency | No | For a partial approval transaction, represent the currency of the amount requested. It should be the same as the currency of the amount processed (currency). |
isRebilling | No | Indicates whether this is a regular transaction or a recurring/rebilling transaction. Possible values: false – This is a regular transaction. true – This is a recurring/rebilling transaction. |
autoSettleMode | No | Automatic settle feature available for merchants working in an Auth-Settle mode. It can be configured to be done per “Accept” risk decision, per specific time frame, or per combination of both. Possible values: TIME, RISK, RISK-TIME. |
isExternalMpi | No | Allow the merchant to provide the 3D-Secure authentication result in the request to Nuvei. Possible values: 1 – external MPI is used 0 – external MPI is not used |
cavv | No | The cardholder authentication verification value. Relevant for external MPI. |
eci | No | An Electronic Commerce Indicator (ECI) value is the result of a 3DS authentication request, returned by a Directory Server ("issuer ACS") (namely Visa, Mastercard, JCB, and American Express). Possible ECI values: Visa: 5 – The cardholder was successfully authenticated. 6 – The issuer or cardholder does not participate in a 3D-Secure program. 7 – Payment authentication was not performed. Mastercard: 1 – The issuer or cardholder does not participate in a 3D-Secure program. 2 – The cardholder was successfully authenticated. 6 – Payment authentication was not performed. 7 – The cardholder was successfully authenticated for the initial MIT. |
type | No | The type of notification. Possible values: DEPOSIT WITHDRAWAL KYC DOCUP KYC and DOCUP are only relevant for merchants implementing Nuvei’s KYC solutions. |
3DauthenticationType | No | Presents whether the transaction has been processed via challenge or frictionless authentication flow. The parameter should be calculated based on the combination of acsChallengeMandated/Result parameters in Auth3D response to Cashier by GW. Values: Challenge or Frictionless If the parameter is empty, the parameter is not included in the DMN. This field is relevant only for a 3D-Secure v2 deposit flow. |
3Dauthentication | No | Result: ThreeDSAuthenticator -> result -> authenticationStatus. For frictionless, result value in Auth3d response to Cashier. For a challenge, send the transStatus value from CRes. If the parameter is empty, the parameter is not included in the DMN. This field is relevant only for a 3D-Secure v2 deposit flow. |
3Dreason | No | ThreeDReason: from final GW response to Cashier's Sale TRX. If the parameter is empty, the parameter is not included in the DMN. This field is relevant only for a 3D-Secure v2 deposit flow. |
3DwhiteListStatus | No | whiteListStatus – from final GW response to Cashier's Sale TRX. If the parameter is empty, the parameter is not included in the DMN. This field is relevant only for a 3D-Secure v2 deposit flow. |
clientRequestId | No | Unique request ID in the merchant’s system. Can be used to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. |
relatedTransactionId | No | The ID of the related transaction used, if it was required for processing. |
merchant_unique_id | No | The ID value that was initially passed in the merchant_unique_id parameter when making the original request to the Nuvei Payment Page. |
clientUniqueId | No | If the transaction is sent through a Nuvei API, then this parameter is populated by the ID of the transaction in the merchant’s system. |
externalTokenProvider | No | An external token provider is an entity in the payment industry with its own flow (for example: Visa Checkout, Apple Pay). This indicates which external token provider was used in the current transaction. |
isDecryptService | No | An external token provider is an entity in the payment industry with its own flow (for example: Visa Checkout). This indicates whether the payments gateway decrypted the external token data provided, which was required for processing. |
apmPayerInfo | No | Additional customer information that is received back from an external alternative payment service provider. Note: The content and the format of data returned for this parameter may vary per APM and provider. |
3DReasonId | No | Reason ID for a failed 3D-Secure authorization as received from the issuer. |
threeDReason | No | Reason description for a failed 3D-Secure authorization as received from the issuer. |
challengeCancelReasonId | No | Reason ID for a canceled 3D-Secure authentication as received from the issuer. |
ChallengeCancelReason | No | Reason for a canceled 3D-Secure authentication as received from the issuer. |
isLiabilityOnIssuer | No | Indicates if there is a 3D-Secure liability shift. |
challengePreferenceReason | No | If a challenge is requested, this field provides the reason for it. |
houseNumber | No | Indicates the provided house number. |
amountWithoutFee | No | The transaction amount without the fee. |
feeAmount | No | The amount of the transaction fee. |
manage_3d_mode | No | The value of manage3D mode that was submitted on the call:AUTO ON OFF |
cardIssuerCountry | No | Country the card was issued in. |
merchant_status | No | Status of KYC merchants. Possible values: Approved, Declined, None, Pending, Review. |
customCurrency | No | Custom currency for airline use. |
threeDSVersion | No | The 3D-Secure version. Possible values: 2.1.0 (if 3D-Secure v2 flow is used) or null (if not used). |
PAR | No | A unique identifier associated with a specific cardholder PAN, which can be used in place of sensitive consumer identification fields. If the PaymentAccountReference value is returned in the response (depending on the card scheme decision), then this value is also returned to the Merchant. |
representmentInformation | No | Contains the date of the next collection attempt. This parameter is relevant only for certain North American APMs. |
merchantAdviceCode | No | Guides Mastercard Merchants on how to proceed after an authorization request is declined. Click here for possible values. |