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:
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:
- 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¤cy=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¬ify_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
- Run this string through a SHA-256 encryption function.
In this example, the checksum value equals:
fedf7e2f70006c83fa740bfa121cdcac0932a672fc7e12a55621153cb52cddf9
- 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¬ify_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
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 ISO 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. |
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. |
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. |