Cashier

On this page:

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 clicks 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 Sample PHP Script.

(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 Handling Direct Merchant Notifications.

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.

Parameter Description
server_URL The URL of the server and the command to accept incoming parameters. (The server_URL is followed by parameter-value pairs.)
Possible values:
  • https://secure.safecharge.com/ppp/purchase.do
    Runs transactions in a live production environment.
  • https://ppp-test.safecharge.com/ppp/purchase.do
    Runs transactions in a test environment.
    Note: This URL is only for testing purposes.
    Live transactions sent to this address will fail.
Parameter The name of the parameter.
Value The value of the parameter.
The ampersand (&) symbol separates parameter-value pairs.

Minimum Required Parameters

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

Parameter Description
merchant_id The merchant’s unique identification number provided by Nuvei.
merchant_site_id The merchant web site’s unique identification number provided by Nuvei.
total_amount The total amount of the transaction.
currency The currency used in the transaction. For a list of currencies and their ISO codes, see Currency Codes.
user_token_id This parameter is a unique identifier for each customer generated by the merchant.
Nuvei recommends that you use token IDs on the merchant level and not per brand. This enables Nuvei to identify customers independent of the site or brand they arrived from.
Note: Tokens expire after 1 year if they are not used. You can generate a new token by sending the token to Nuvei in your HTTPS request.
item_name_N The name of the item.
item_amount_N The price of the item number.
item_quantity_N The amount of items being purchased.
time_stamp The GMT time when the transaction took place in the following format: YYYY-MM-DD.HH:MM:SS.
version The version of the payment page. Possible values:
3.0.0: This parameter requires that only the minimum parameters described in the section Checksums are calculated as part of the HTTPS request.
4.0.0: This value requires that all values of the HTTPS request are calculated as part of the checksum.
checksum For example:
Checksum=SHA-256 {merchantKey + merchantGwId + currency + totalAmount + item_name_1+item_amount_1+ item_quantity_1+ item_open_amount_1 +item_min_amount_1+ item_max_amount_1 +timestamp}

Calculating Checksums for Version 4.0.0

The checksum value is calculated by taking the SHA256 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.

Your Secret Key is never sent as a parameter in the HTTPS request.

When using Version 4.0.0, you determine the order of the parameters sent in the HTTPS request. However, the order of the parameter values used to calculate the checksum must match the order of the parameters sent in the HTTPS request.

Mandatory Request Fields

To build a request, using the Mandatory fields for your account and the fields required by the type of integration (in this case Cashier).

These are the most common mandatory fields:

  • email
  • country
  • version (of the request)
  • merchant_id
  • merchant_site_id
  • total_amount
  • currency
  • item_name_1
  • item_amount_1
  • item_quantity_1
  • time_stamp
  • user_token_id
  • userid
  • checksum

Never include your Secret Key in an HTTP request as a parameter field, which could compromise your security and open your business to outside web attacks. Instead, it is sent in an encrypted format as part of the checksum.

Calculating 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. Secret Key (must be the first field value)
    2. Merchant Id
    3. Site Id
    4. User token
    5. User token Id
    6. Item name
    7. Item amount
    8. Item quantity
    9. Item discount
    10. Number of items
    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 address
    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
Creating the HTTPS Request

When generating the request to the payment page, the parameters in the STRING and in the Request must follow the same order (except in the Request you must not pass secret key).

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://safecharge.com&time_stamp=2020-03-07.11:41:15&checksum=77b02ddea36fd0176e8f7c70a346a124491bd00feac37de0f755b57703480a98&

Passing notify_url in a request with version 3.0.0 does not work. If attempted, the DMN is sent to the Static DMN URL.

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 data, the last four digits of the 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

Please refer to Alternative Payment Methods.

 

Parameter Description