Overview

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

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

To use the Payment 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 Payment Page.

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 are sent in the request.

Prepare the input parameters:

1. Calculate a total_amount for the transaction. For details, see the Total Amount Calculation topic.
2. Create a transaction input parameters string containing the input parameters this format: [field1]=[value1]&[field]2=[value2]&[field3]=[value3]…
   These are the minimum (required) input parameters needed to process a transaction:
   There are many other input parameters that you can include.
   See the full set of Payment Page Input Parameters for more options and functionality.

   Minimum (Required) Input Parameters

   Parameter	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.
   total_amount	The total amount of the transaction.
   currency	The three-letter ISO currency code for the currency used in the transaction.
   user_token_id	This parameter is a unique identifier for each customer generated by the vendor.
   item_name_N	The name of the item.
   item_amount_N	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
   notify_url	URL to which the webhook notification is sent.
   checksum	The calculated checksum value.

   Example Transaction Input String

   merchant_id=283475&merchant_site_id=89123755&total_amount=15&currency=USD&[email protected]&item_name_1=item1&item_amount_1=15&item_quantity_1=1&time_stamp=2011-01-05.06:04:26&version=4.0.0&notify_url=https://notify.merchant.com

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 are 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.
      For example, assuming a secret key value of:  Secret123

      Secret123[email protected]:04:264.0.0https://notify.merchant.com

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

   027402ea5d3e62179bfd82ec70eae2ad16efe7802880d452214d685169ce9300

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

   checksum=fedf7e2f70006c83fa740bfa121cdcac0932a672fc7e12a55621153cb52cddf9

3. Submit a Request to the Payment Page

Send an HTTPS request to the Payment 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 payment 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%20Product&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.nuvei.com%2Flib%2Fdemo_process_request%2Fresponse.php&theme_id=178113&checksum=3f907ff30d33239880c853ad5bdf0a0aaf3a351de7220d6e2379f8804b58097f

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 presses 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 Webhooks (DMNs).

Nuvei also sends you a response via an HTTPS GET, which contains 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 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.

Appendix – Calculations

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 or MD5 encoded checksum, of a string of the concatenated values, of the following parameters:

• merchantSecretKey
• 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:

4cf3573877655c9b84ae8040beb586d9bc69d09d33ee4f4b451027579aa3f586

Total Amount Calculation

Calculate the transaction total amount as follows:

1. Calculate the transaction sub-total:
   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 total for each item and then sum all the per-item totals to get a transaction sub-total.
   • Calculate the entire transaction total to get a transaction sub-total.
2. Calculate the transaction tax:
   The transaction tax is calculated as a percentage of the transaction sub-total.
3. Add the transaction tax to the transaction sub-total to get the transaction total amount.

The parameters that can be used in the calculation include:

• Item level parameters:
  • 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

Example of a Total Amount Calculation

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_N + 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 (with values)

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_N + 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.