Overview

Nuvei’s Web Cashier is an online solution that enables merchants selling products and services over the web to process online customer deposits and withdrawals through the Cashier Deposit and Withdrawal pages. These pages can be customized per request for web and mobile pages that provide an easy-to-use interface for depositing and withdrawing funds.

Nuvei’s Cashier uniquely identifies each customer and presents their preferred language, currency, and previous payment methods. This creates an individual deposit and withdrawal experience for each customer increasing conversion. Connected to the Nuvei Gateway, Cashier securely processes cards and dozens of alternative/local deposit methods.

Definitions, Acronyms, and Abbreviations

Approve: The request is approved and the funds are withdrawn and sent to the customer’s chosen payment method.

Chargeback: A process in which, due to an illegitimate use of a credit card or an erroneous payment process, the bank involved in the transaction processes the refund to the cardholder, transferring the original transaction’s funds back from the merchant to the customer’s issuing bank.

Checksum: A string of characters, letters, and numbers, which is the encoded reflection of valid data.

Customer: The individual purchasing a product or requesting funds from the merchant through the Cashier pages.

Decline: The request is declined and no funds are withdrawn.

Gateway: Nuvei’s web server that processes credit card transactions. The Gateway authenticates the merchant and processes the transaction with an issuer bank. After receiving a response from the issuer bank, such as an authorization, the Gateway returns a response to the merchant regarding the status of the transaction.

Merchant: A client of Nuvei that uses Cashier as its payment page for processing transactions.

Merchant’s Website: The web site accessed by the customer when purchasing a product or service.

Payment Process: The process where the Nuvei server arranges for the payment to transfer from the customer’s credit card/account to the merchant’s account.

Split: The request to return funds is split between several payment methods.

Transaction: The request made to Nuvei via HTTPS requests when a product or service is exchanged between a customer and a merchant.

Withdrawal Order: A withdrawal order is part of a withdrawal request. An order includes the transaction and withdrawal details for funds to be withdrawn and sent to a single payment method.

Withdrawal Request: A customer’s request to withdraw funds from their account to be sent to their chosen payment method. Withdrawal requests can contain several withdrawal orders each to a different payment method.

Integrating the Cashier Deposit Page

The Cashier processes your online customers’ deposits through the Deposit page according to parameters you send in HTTPS requests, which contain details about the deposit such as the customer’s details, the amount of the deposit, and the deposit’s currency. Based on the results of the deposit attempt, the Cashier directs the customer to a Success page when the deposit is successful or Cashier presents the customer with alternative payment options for making the deposit when a deposit fails.

To integrate the Cashier Deposit page into your site’s payment flow, the merchant should develop the processes for redirecting your customers to the Deposit page and handling the response following the transaction.

Deposit Flow

The following flow describes the deposit flow for the customer and the steps you must take to integrate with the Cashier:

The customer enters their personal details on your site or application.

You redirect the customer to the Deposit page in the customer’s browser through an HTTPS request. You must create the HTTPS request that redirects the customer to the Deposit page. The customer presses Continue on the Deposit page, and Cashier forwards the details of the customer and the transaction to Nuvei to be processed.

Nuvei contacts the bank to deposit the funds to your account.

The bank responds to Nuvei’s request.

Nuvei redirects the customer back to your site. When the transaction is successful, Nuvei redirects the customer to a Success page on your site. Within the Redirect URL to your site, Nuvei returns a response that indicates the result of the transaction. For more information, see Handling the Cashier Response.

(Optional) Nuvei sends you a Direct Merchant Notification (DMN) notifying you of the status of the deposit. You must provide Nuvei with the URL of the server that receives the DMN. For more information, see Payment Transaction Requests.

Regulations

The United Kingdom Commission requires merchants to ask the end user for confirmation when making a deposit (of any method – credit card or APM) for the first time.

The following confirmation opens:

Redirecting Customers to the Deposit Page

After a customer decides to make a deposit and enters their details, your website redirects the customer to the Deposit page through an HTTPS request via the HTTP POST method. The HTTPS request defines the location of the Deposit page and contains parameters that specify the details of the deposit such as the amount and the currency of the deposit. In addition, Cashier can identify returning customers to display their most recent payment methods based on the parameter user_token_id and enable the customer to modify their deposit within a predefined range according to the item_open_amount_1 parameter.

Creating HTTPS Requests

Cashier uses HTTPS requests in an automated mode to enable you to send transaction data to Nuvei.

Construct the HTTPS request string by concatenating the field and value pairs as shown in this example in the same order that they appeared in the checksum calculation:

https://ppp-test.safecharge.com/ppp/purchase.do?merchant_id=4960497427404081578&merchant_site_id=197846&user_token=auto&user_token_id=UserId_7931506112&userid=UserId_7931506112&item_name_1=Cashier%20Test%20product&item_amount_1=10&item_quantity_1=1&item_discount_1=0&numberofitems=1&total_tax=0&discount=0&total_amount=10.00&currency=USD&version=4.0.0&encoding=UTF-8&first_name=test&last_name=test&address1=test&city=test&zip=123456&country=GB&phone1=123456&email=2521524853%40gmail.com&payment_method=cc_card&notify_url=https%3A%2F%2Fsafecharge.com&time_stamp=2020-03-07.11%3A41%3A15&checksum=a9f3a9254909583dc0d925de581fd8e08e363cf96bb8750bc65bde8bb1b6a7df

Minimum Mandatory Parameters

HTTPS requests to Cashier must contain certain parameters to be valid. The following list displays the mandatory parameters that the merchant’s website must send to Cashier to process a transaction:

Calculating Checksums for Version 4.0.0

The checksum value is calculated by taking the SHA-256 hash of the string of concatenated values of your secret key (which must be the first value) followed by the values of the parameters that appear in the request in the same order they appear in the request with no spaces and no separators between the values.

Constructing the Checksum

1. Construct the String by concatenating the values of the fields that appear in the request in the same order that they appear in the request.
   The following example concatenates the “values” of these mandatory and non-mandatory fields in the order they appear in the request:
   1. merchantSecretKey (must be the first field value)
   2. merchant_id
   3. merchant_site_id
   4. userToken
   5. userTokenId
   6. item_name_1
   7. item_amount_1
   8. item_quantity_1
   9. item_discount
   10. numberofitems
   11. total_tax
   12. discount
   13. total_amount
   14. currency
   15. version
   16. encoding
   17. first_name
   18. last_name
   19. address
   20. city
   21. zip
   22. country
   23. phone
   24. email
   25. payment_method
   26. notify_url (DMN)
   27. time_stamp
2. Run this String through a SHA-256 hashing algorithm.
   

   Example String:

   SJt3fr2PqOrcv2s4lHLJmVZP1IEIZ55Sor0AYZmO08p5pKFiFBCVtevRM2wtF7YD4960497427404081578197846autoUserId_7931506112UserId_7931506112Cashier Test product101010010.00USD4.0.0UTF-8testtesttesttest123456GB1234562521524853@gmail.comcc_cardhttps://safecharge.com2020-03-07.11:41:15

   This returns the checksum value.

   Example Checksum Value:

   77b02ddea36fd0176e8f7c70a346a124491bd00feac37de0f755b57703480a98

Sending the HTTPS Request

Nuvei recommends that you test an HTTP request string by sending it through a web browser. You can test HTTPS requests manually with an HTTP GET request. However, to send an HTTPS request to Cashier in a full production environment, your website must use an HTTP POST call. To test the HTTP GET request in a web browser, open a web browser and copy the HTTP request created in the previous section into the address bar and press Enter to send the request. A valid HTTP GET request opens the Deposit page.

Handling the Cashier Response

During the redirection back to your site, Nuvei uses HTTP GET to return a set of parameters that define the transaction and its result.

Cashier Response Example

https://www.safechargemerchant.com/safecharge/SafechargeDeposit.htm?ppp_status=OK&cardCompany=MasterCard&nameOnCard=John+Smith&first_name=John&last_name=Smith&address1=1%Main%St%&city=Columbus%&country=US&email=johnsmith%40hotmail.com&zip=43050&phone1=7409999999&currency=USD&merchant_unique_id=4444444&merchant_site_id=111111&merchant_id=53454563653&merchantLocale=en_US&requestVersion=3.0.0&PPP_TransactionId=&productId=DEPOSIT+444444&userid=3534205&&payment_method=cc_card&responseTimeStamp=2015-12-12.22:12:35&message=Success&Error=Success&Status=APPROVED&ClientUniqueId=4444444&ExErrCode=0&ErrCode=0&AuthCode=039958&ReasonCode=0&Token=adffgBAzAA%3D%3D&tokenId=841397792&responsechecksum=c16c7452342220b613ee0c63422342e&advanceResponseChecksum=aa2f762dacf853562gfb5d1b7ef48&totalAmount=200.00&TransactionId=8675309123458675309&uniqueCC=eUwnsFSqRLtRmrWoiWYGoCvoLsE%3D&item_amount_1=200.00&item_quantity_1=1

There are four sets of output parameters returned in the response:

• 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 response checksum).
• Payment Parameters: The unprotected payment method information as updated by the customer in the Deposit page (name on card, expiration date, credit card number, token, etc.).
• Customer Details: The customer’s personal information as updated by the customer in the Deposit page (first and last name, the address, the contact details, etc.). By default, these parameters are returned. However, during your configuration you can instruct Nuvei to remove them from the response.

Personal details can be removed by request.

• Other Parameters: Merchant custom fields and other miscellaneous parameters.

Integrating APMs

For integration details, see the APM Cashier Integration topic.