Developers

Overview

The quickest way to integrate with Nuvei and benefit from all our features is via our ‘Checkout Page’ solution. With our Checkout Page, you only need to load the page via IFrame or by full page redirect and all features and functionalities are seamlessly integrated.

Follow these 3 simple steps to integrate with our Checkout Page:

1. Prepare the authentication
2. Submit a request to the Checkout Page
3. Handle the response

You can customize your checkout page using the Theme Builder in the Control Panel.

Step 1: Prepare the Authentication

To prevent errors that may occur while transferring HTTPS requests, and for Nuvei to authenticate HTTPS requests, you must create and include a SHA-256 checksum into your request.

The checksum must be a single string without spaces with the values of the following parameters in the exact order as shown in the example below:

1. Concatenate the secret key with all the values of the request fields. The order has to be the same order as sent in the request.

Example

For the following request:

merchant_id=283475&merchant_site_id=89123755&total_amount=15&currency=USD&user_token_id=test@test.com&item_name_1=item1&item_amount_1=15&item_quantity_1=1&time_stamp=2011-01-056:04:26&version=4.0.0&notify_url=https%3A%2F%2Fnotify.merchant.com

Construct the following string (assuming the secret key value is Secret123):

Secret1232834758912375515USDtest@test.comitem11512011-01-056:04:264.0.0https%3A%2F%2Fnotify.merchant.com

2. Run this string through a SHA-256 encryption function.

In this example, the checksum value equals:

fedf7e2f70006c83fa740bfa121cdcac0932a672fc7e12a55621153cb52cddf9

3. Place the output in the checksum field:

checksum=fedf7e2f70006c83fa740bfa121cdcac0932a672fc7e12a55621153cb52cddf9

Step 2: Submit a Request to the Checkout Page

The HTTPS request includes the URL of the checkout page and transaction parameters such as the amount of the transaction and the currency.

HTTPS requests must be in the GET name/value pair format (can be in POST as well):

https://ppp-test.safecharge.com/ppp/purchase.do?currency=EUR&item_name_1=Test+Product&item_number_1=1&item_quantity_1=1&item_amount_1=50.00&numberofitems=1&encoding=utf-8&merchant_id=640817950595693192&merchant_site_id=148133&time_stamp=2018-05-15.02%3A35%3A21&version=4.0.0&user_token_id=ran100418_scobd%40mailinator.com&user_token=auto&total_amount=50.00&notify_url=https%3A%2F%2Fsandbox.safecharge.com%2Flib%2Fdemo_process_request%2Fresponse.php&theme_id=178113&checksum=66ce9f4ce1e5f47298e7e5e457d0b21ca8d6a668d549240929924054db6d1a21

Minimum Required Parameters

The following table displays the required parameters that your website must send to Nuvei to process a transaction:

This is the short version of the Checkout Page input parameters. We have more options and functionality you can control. Please refer to Checkout Page for the complete guide.

Field	Description
merchant_id	The vendor’s unique identification number provided by Nuvei.
merchant_site_id	The vendor website’s unique identification number provided by Nuvei.
user_token_id	This parameter is a unique identifier for each customer generated by the vendor.
notify_url	URL to which the webhook notification is sent.
total_amount	The total amount of the transaction.
currency	The three-letter ISO currency code for the currency used in the transaction.
item_name_N	The name of the item.
item_amount	The price of the item number.
item_quantity	The amount of items being purchased.
time_stamp	The GMT time that the transaction took place in the following format: YYYY-MM-DD HH:MM:SS
version	The current version of the payment page. Currently, the version is=4.0.0.
checksum	The checksum value.

Step 3: Handle the Response

After Nuvei attempts to process the payment, Nuvei redirects your customer to a Transaction Outcome page on your site based on the result of Nuvei’s attempt:

Field	Description
Success	Nuvei redirects the customer to the Success page when Nuvei successfully processes the transaction.
Pending	Nuvei redirects the customer to a Pending page until a response is received.
Back	Nuvei redirects the customer to a Back page when the customer clicks 'Back’ on the payment page.
DMN	The URL of your DMN listener. For more information, see Handling DMNs.

In addition to redirecting the customer, Nuvei sends you a response through an HTTPS GET request. This request contains details of the transaction such as the outcome and the payment details of the customer.

There are four sets of parameters that are sent as part of the HTTPS GET request:

Parameter Set	Description
Transaction	These parameters include the original parameters that you sent to the payment page and define the outcome of the transaction, including the response checksum.
Payment	These parameters include the unprotected payment method information, as provided by the customer on the payment page, such as name on card, expiration date, and the last four digits of the credit card number.
General	These parameters contain the details of the purchase including the item and amount.
Other	These parameters are any custom fields you defined and any other miscellaneous parameters.

Click here for the full list of the Output parameters and their descriptions.

Response Checksum Parameter

To ensure that the HTTPS GET request from Nuvei is authentic, Nuvei includes the advanceResponsechecksum parameter in the HTTPS GET request. To calculate the checksum, use a SHA-256 process with the following parameters:

• Secret Key
• totalAmount
• Currency
• responseTimeStamp
• PPP_TransactionID
• Status
• productId

Response Checksum Example:

The string, which is made up of the values used in the above example and a sample secret key (AJHFH9349JASFJHADJ9834) and item_quantity_1 (1), would be:

Secret123115USD2007-11-13.13:22:343453459APPROVEDYourProduct

The calculated checksum would then be:

826fb8c4a2451e86f41df511c46f5a9b