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 which 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 UK Gaming 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 This is the URL of the server and the command to accept incoming parameters. It is followed by a list of parameters and their values. There are two possible values for the server URL:
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 testing purposes. Live transactions sent to this address will fail.
    Parameter This is the name of the parameter.
    Value This is the value of the parameter. The ampersand (&) symbol separates sets of parameters and values.

    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. There are two 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.
    Click here for more information.
    checksum For more information about standard Checksum calculations, click here.
    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

    When calculating the checksum, you can determine the order of the parameters except for the Secret Key parameter. This parameter must be calculated first, and then you can determine the order of the remaining parameters.

    You can determine the order of your parameter for Version 4.0.0; however, the order of the checksum calculation must match the order of the HTTPS request, or the request will fail.

    To build a request, you need to pass the Mandatory fields for your account and those that are required by the type of integration (in this case Cashier).

    Usually the mandatory fields you should pass are as follows:

    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 insert your secret key in an HTTP request. Instead, it should be used as a component in the checksum’s calculation. Sending it in the HTTP request may compromise your security, opening your business to outside web attacks.

    First, you need to construct the String before running it through a SHA-256 hashing algorithm):

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

    The above String is generated by putting the following fields together one after another:

    1. Secret Key
    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

    Once you run the string via the hashing algorithm (in this case SHA-256), you will receive the checksum:

    77b02ddea36fd0176e8f7c70a346a124491bd00feac37de0f755b57703480a98

    When generating the request to the checkout 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), which would lead up to this:

    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=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%3A12%3A35&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.