Overview

Checkout Page is the quickest way to integrate with Nuvei and enjoy the benefits of this feature-rich payment solution.

Simply loading Checkout Page via an IFrame or a full page redirect, is all it takes to seamlessly integrate Checkout Page’s features and functionality into your site.

To use the Checkout Page solution, create an HTTPS request with all the relevant transaction input encoded as a query string, and use it to redirect your customer to our page (or IFrame).

Follow the steps below to integrate and use Checkout Page.

Step 1: Prepare the Transaction Input Parameters

The transaction input parameters string is a list of all the input parameters and their values, in the exact order that they will be sent in the request.

Prepare the input parameters:

1. Calculate a total_amount for the transaction, which will be included in the checksum. For details, see the Total Amount Calculation section.
2. Create a transaction input parameters string, in this format: field1=value1&field2=value2&field3=value3…
   These are the minimum (required) input parameters needed to process a transaction:
   Note, there are many other input parameters that you can include.
   See the full set of Checkout Page Input Parameters, for more options and functionality.

   Minimum (Required) Input Parameters

   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.

   
   Example transaction input string:

   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

Step 2: Prepare the Authentication Request

Include a SHA-256 encrypted checksum in your HTTPS request to help Nuvei authenticate the request and avoid communication errors.
Follow these steps to create the checksum:

1. Create a string of the values of all the input parameters (without spaces), in the exact order that they will be sent in the request, as follows:
   1. Copy the transaction input parameters string, and delete everything except the values of all the input parameters (without spaces).
   2. Concatenate the value of your Secret key to the front of the string.
      Example (assuming you Secret key value is Secret123):

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

2. Generate an encrypted checksum by running the string through a SHA-256 encryption function.
   Example of an encrypted checksum (based on the example string above):

   fedf7e2f70006c83fa740bfa121cdcac0932a672fc7e12a55621153cb52cddf9

3. Use the encrypted checksum value the checksum field in the request:

   checksum=fedf7e2f70006c83fa740bfa121cdcac0932a672fc7e12a55621153cb52cddf9

Step 3: Submit a Request to the Checkout Page

Send an HTTPS request to the Checkout Page either in the GET name/value pair format, or as a POST.

Create an HTTPS query string by concatenating the endpoint URL of your checkout page and the transaction input parameters string:

• Select the relevant Endpoint URL:
  • Live: https://secure.safecharge.com/ppp/purchase.do
  • Test: https://ppp-test.safecharge.com/ppp/purchase.do
• Use the transaction input parameters string, that you created in the previous steps.

Example of transaction input encoded as a query string

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

Step 4: Handle the Response

After Nuvei attempts to process the payment, your customer is redirected to a relevant Transaction Outcome page on your site, depending on the results:

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

Nuvei also sends you a response via an HTTPS GET, containing transaction details such as the outcome and customer payment details.

Four sets of parameters that are sent as part of the HTTPS GET:

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. See the full set of Output Transaction Parameters.
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. See the full set of Output Payment Parameters.
General	These parameters contain the details of the purchase including the item and amount. See the full set of Output General Parameters.
Other	These parameters are any custom fields you defined and any other miscellaneous parameters. See the full set of Output Other Parameters.

Response Checksum Parameter

To ensure that the HTTPS GET from Nuvei is authentic, an advanceResponsechecksum parameter is included in the HTTPS GET.

Calculate the SHA-256 encoded checksum, of a string of the concatenated values, of the following parameters:

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

Example Response Checksum

The concatenated string is made up of the values of the above parameters (assuming the secret key value is Secret123 and an item_quantity_1 (1):

Secret123115USD2007-11-13.13:22:343453459APPROVEDYourProduct

The calculated checksum would then be:

826fb8c4a2451e86f41df511c46f5a9b

Total Amount Calculation

Calculating the transaction total amount is done in two steps: first calculate the transaction sub-total, then calculate the transaction tax and add it the transaction sub-total:

1. The transaction sub-total is the sum of all the item amounts, including their shipping, handling, discounts, etc.
   Calculate the transaction sub-total in either of these ways:
   • Calculate the per-item totals, and then sum all the per-item totals, to get a transaction sub-total.
   • Or, calculate the entire transaction total, to get a transaction sub-total.
2. The transaction tax is calculated as a percentage of the transaction sub-total. The transaction tax is then added to the transaction sub-total, to get the transaction total amount.

The parameters that can be used in the calculation include:

• Item level fields:
  • item_amount_N
  • item_discount_N
  • item_shipping_N
  • item_handling_N
  • item_quantity_N
• shipping
• handling
• discount
• total_tax (this is the tax percentage to be applied to the transaction)
• version

Calculate the transaction total amount as follows:

1. Either:
   • Calculate the per-item totals:
     Transaction sub-total = sum((item_amount_N – item_discount_N + item_shipping_N + item_handling_N) * item_quantity_N)
   • Or, calculate the entire transaction total:
     Transaction sub-total = item_amount + shipping + handling – discount
2. The tax is then added to calculate the total:
   calculatedTotalAmount =  transaction sub-total + transaction sub-total * (total_tax / 100)

Example of a Total Amount Calculation

Input values:

• Item amount = 350
• Shipping = 10
• Discount = -20
• Total tax = 23% (0.23)
• Total amount = 418.20

1. Either:
   • Calculate the per-item totals:
     Transaction sub-total = sum((item_amount_N – item_discount_N + item_shipping_N + item_handling_N) * item_quantity_N)
     340 = 350 + 10 – 20
   • Or, calculate the entire transaction total (which includes shipping & handling costs, and discounts):
     Transaction sub-total = item_amount + shipping + handling – discount
     340 = 350 + 10 – 20
2. The tax is then added to calculate the total:
   calculatedTotalAmount =  transaction sub-total + transaction sub-total * (total_tax / 100)
   418.20 = 340 + ( 0.23 * 340)
   
   If the total amount has more than two digits after the decimal, you must round the amount to the nearest hundredth.