Quick Start

On this page:

The Checkout product and checkout() method should not be confused with the Payment Page product, which is an entirely different Nuvei solution.

Overview

The Checkout product (checkout() method), is a single end-to-end solution for accepting payments. It integrates easily into your payment flow, and has its own customizable UI that embeds seamlessly into your payment page.

Benefits of Using Checkout

Using the checkout() method allows you to keep control over your functionality, UI/UX, design, and payment flow, while enjoying a range of benefits, which include:

  • Simple implementation.
  • Full 3D-Secure and PCI compliance with minimum effort.
  • End-to-end payment process in one call.
  • Use of Checkout Advanced Controls: Full customization, locale customization, controlling the payment flow and the payment methods, and hooking into the payment flow using our events. See the What else you can do with Checkout or the relevant chapter from the Checkout menu.

Follow the simple steps described below to integrate Checkout’scheckout() method into your payment page.

1. Initiate a Session

The customer begins the checkout process as usual, by clicking a “Checkout” (or “Go to Payment” or a similar button).

Initiate a session by sending an /openOrder API call, which has two main functions:

  • Authenticates you as our merchant using your given credentials. You can find your credentials here.
  • Sets up the authenticated order in the Nuvei system and returns a sessionToken, which is referenced later by the checkout() method.

  • This call must be performed on your backend server, never on the frontend, because it requires your secret key, which should NOT be exposed on the client-side to prevent front-end user manipulation.

  • Before using the Server SDK, make sure to initialize the SDK before any request by including the relevant SDK initialization.

    You can simulate the Open Order functionality using a Postman script (follow our guide on using this here). Then use this Postman script to run and test the /openOrder method.

    POST is used for all Nuvei REST API methods that involve a transfer of data from client to server.

Send an /openOrder API request (which must include the checksum parameter).

  • Calculate the checksum value as follows:

    1. Concatenate the following fields in this order, with no spaces, and no separators between the fields:
      merchantId, merchantSiteId,clientRequestId, amount, currency, timeStamp, {your secret key}
    2. Calculate the SHA256 hash of the concatenated fields.
    • Example /openOrder Request 
    • {  
    "merchantId":"<your merchantId goes here>",
    "merchantSiteId":"<your merchantSiteId goes here>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "currency":"USD",
    "amount":"200",
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
      <?php
$safecharge = new \SafeCharge\Api\RestClient([
'environment' => \SafeCharge\Api\Environment::INT,
'merchantId' => '<your merchantId>',
'merchantSiteId' => '<your merchantSiteId>',
'merchantSecretKey' => '<your merchantSecretKey>',
]);

$openOrderRequest = $SafeCharge->getPaymentService()->openOrder([
    'clientUniqueId'    => '<unique transaction ID in merchant system>',
    'clientRequestId'   => '<unique request ID in merchant system>',
    'currency'          => 'USD',
    'amount'            => '200',
    'billingAddress' => [
        'country'   => "US",
        "email"     => "john.smith@email.com",
    ],
]);
?>
      public static void main(String[] args) {
// for initialization 
String merchantId = "<your merchantId>";
String merchantSiteId = "<your merchantSiteId>";
String merchantKey = "<your merchantKey>";
safecharge.initialize(merchantId, merchantSiteId, merchantKey, Constants.HashAlgorithm.SHA256);

//for openOrder
String clientUniqueId = "<unique transaction ID in merchant system>";
String clientRequestId = "<unique request ID in merchant system>";
String currency = "USD";
String amount = "200";

UserAddress billingAddress = new UserAddress();
billingAddress.setEmail("john.smith@email.com");
billingAddress.setCountry("US");

Safecharge safecharge = new Safecharge();
SafechargeResponse response = safecharge.openOrder(clientRequestId,
clientUniqueId, null, null, null, null, currency, amount,
null, null, null, null, billingAddress, null, null, null,
null, null, null, null, null, null, null);
}
      var safecharge = new Safecharge(
"<your merchantKey>",
"<your merchantId>",
"<your merchantSiteId>",
"<your server host value>",
HashAlgorithmType.SHA256
);
var response = safecharge.OpenOrder(
 "USD",
 "200",
 clientUniqueId: "<unique transaction ID in merchant system>",
 clientRequestId: "<unique request ID in merchant system>",
 billingAddress: new UserAddress
 {
     Email = "john.smith@email.com",
     Country = "US",
 }
);
      const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
safecharge.paymentService.openOrder({
    'clientUniqueId'   : '<unique transaction ID in merchant system>',
    'clientRequestId'  : '<unique request ID in merchant system>',
    'currency'         : 'USD',
    'amount'           : '200'
    'billingAddress': {
        'email': "john.smith@email.com",
        'country': "US"
    },
}, function (err, result) {
    console.log(err, result)
});
    Example /openOrder Response 
    • {
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId": "39272",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version": "1.0"
}

2. Create an HTML Placeholder

The following steps are frontend changes. To see editable Checkout examples in the JSFiddle environment, refer to the Checkout Examples topic.
You can view, modify, and run these examples to test your code.

Present a Checkout Payment UI to the customer so that they can select a payment method, or enter their cardholder details.
The example below has the following steps:

  1. Import the checkout.js JavaScript library.
    The checkout.js JavaScript library is used for building payment flows. It allows you to collect sensitive data from the user and create representative Tokens, for safely sending that data to your servers. This allows a PCI descoped way to collect and process card details.
  2. Create an HTML placeholder element on your payment page.
    The example below creates an HTML container named "checkout", into which you can render the Checkout Payment Form when calling the checkout() method.
    Example HTML that Renders a Checkout Payment Form 
    <head>
  <title>Checkout</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <script src="https://cdn.safecharge.com/safecharge_resources/v1/checkout/checkout.js"></script>
</head>

<body>
  <br /><br />
  <div id="checkout" style="width:400px;height:600px;border: 1px solid #d3dce6;" 
  ="><br /><br />The checkout is displayed here.</div>
</body>
  3. You can customize the Checkout Payment UI by customizing the CSS styles to match the styles in your own payment page, anchor the component location, or override the default CSS styles of the Checkout Payment UI component.
    For details, see the Payment Form Styling section.

3. Perform a Checkout Payment

Perform an end-to-end checkout payment by calling the checkout() method and include the relevant parameters in the request.

Example Simple checkout() Request 
function main() function main() function main() function main() {
    document.getElementById('checkout').innerHTML = "";
    checkout({
        sessionToken: document.getElementById('session').value,
        env: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted)
        merchantSiteId: '',
        merchantId: '',
        country: 'US', //optimizes the payment method accordingly
        locale: 'en_US', // de it fr pt
        currency: 'USD',
        amount: 135,
        fullName: document.getElementById('cardHolderName').value,
        email: 'john.smith@email.com',
        "billingAddress": {
            "email": "john.smith@email.com",
            "country": "US"
        },
        renderTo: '#checkout', //
        onResult: function(result) {
            console.log("Result", result) // this is where you get notified after per payment result
        },

    });
}

Use our JSFiddle example to help you get started building your checkout request.

What Else You Can Do with Checkout

The above code sample is the simplest Checkout invocation. It gives a full payment experience, but with the basic features and without any customization you may want to apply.

Checkout provides a comprehensive set of customization controls over the UI/UX and checkout process, which you can utilize to be more involved in the whole experience:

General Customization – See this chapter to view your customization options, how to set to your preferred look and feel, control the text and local and more.

Payment Customization – Control your payment flow and the payment methods you would like to invoke or disable for a particular user or use case. Control the behavior of card processing and other payment methods (paypal, google pay, apple pay and the rest of our APMs).

Advanced Controls – Explains how you can hook into the payment process, get notified about any important event and affect the payment process and user experience.

checkout() Input Parameters

The following table presents the input parameters for the checkout() method.

DCC settings are controlled with the useDCC and strictDcc parameters, as described below.

Parameter Description Example Mandatory
sessionToken Provided by the previous openOrder server side call. '410e50bb-b153-421b-833c-42be20031939' Yes
env Nuvei payment environment.
Possible values:
  • prod (default) – production
  • int – integration
 'int' No
merchantId The merchant ID provided by Nuvei. '479748173730597238' Yes
merchantSiteId The merchantSiteId provided by Nuvei. '180083' Yes
country Used as a filter when retrieving payment methods. This can be sent either here or in the /openOrder request. 'CA' Yes
currency Used for visualization in PM (button, Apple Pay overlay), as well as for filtering supported payment methods. 'EUR' Yes
amount Used for visualization purposes similar to currency. 135 Yes
renderTo The name of the HTML container that you created previously for Checkout. (In the example below the value is "#checkout".) '#checkout' Yes
onResult Defines the callback function to handle the result from the user action in the checkout. onResult: const onResult =
function (result) { console.log(result)}		 Yes
onReady Defines a callback function for when the checkout is fully loaded. const onReady = function(result) {
console.log(result)}		 Yes
prePayment Defines a callback function that allows the merchant to be notified just before a payment is finalized, receive all the payment details, and take an action if desired.
Possible values:
  • resolve() – To continue with the payment
  • reject() – To stop the payment
  • reject() – To stop the payment with a message
 prePayment: function(paymentDetails) {
  return new
  Promise((resolve, reject) => {
  console.log(paymentDetails);
  resolve();
  or reject();
  // Reject payment with message
  or reject('Message');
}); },		 Yes
pmSelected This callback function is called when a user selects a payment method from the gallery, either an existing UPO or a new one.
For an existing UPO, the merchant receives all the information about the UPO.
For a new payment option, only the method name is received.		 checkout({…
  selectPaymentMethod:
  function(paymentDetails) {
    console.log(
    "selectPaymentMethod",
    paymentDetails);
}, …});		 No
upoDeleted This callback is called when a user selects and removes a UPO from the gallery.
Note that the event is called after the user actually confirms that the UPO should be deleted.		 checkout({…
  upoDeleted:
  function(paymentDetails) {
  console.log("upoDeleted",
  paymentDetails);
}, …});		 No
userTokenId Unique identifier of the customer in your system. Mandatory only if you are using UPOs (user payment option). 'userId' Conditional
apmConfig The apmConfig block is used to store unique setup parameters for some APMs.
For details see: 		apmConfig: {
 googlePay: {
  buttonColor: 'black',
    // black (default), white
  buttonType: 'checkout'
    // buy (default), book,
    // checkout, order, pay,
    // plain, subscribe
} },		 Conditional
useDCC The "Use currency conversion" checkbox allows the customer to convert the amount into another (their home) currency. Possible values:
  • enable: Enables the checkbox.
  • disable (default): Disables the checkbox.
  • force: Enables and selects the checkbox. (The customer is still able to unselect the checkbox.)
 'disable' No
strictDcc
  • true – Customers are only allowed to use DCC for cards that have the status of "DCC Allowed" (set by the issuing bank).
  • false (default) – Customers are allowed to use DCC even for cards that do not have the status of "DCC Allowed" (set by the issuing bank).
 false No
savePM When set to true then the Save my details for future use checkbox is displayed for each payment method in the Payment Methods list.
Note: This is required in the initial request of an APM Recurring Billing transaction.		 true No
subMethod This optional parameter is used for advanced APMs flows.
For the Customer Registration via APM feature, this parameter should contain an array of APM providers who support this feature.		 ["PayNPlay", "QuickRegistration"], No
pmWhitelist Only the specified APMs are displayed to the customer in the Payment Methods list.
Note: pmWhiteList and pmBlacklist cannot be included in the same request.		 ["apmgw_QIWI", "apmgw_MoneyBookers"] No
pmBlacklist The specified APMs are not displayed to the customer in the Payment Methods list, even if they are returned by an API.
Note: pmWhiteList and pmBlacklist cannot be included in the same request.		 ["ppp_ApplePay", "apmgw_QIWI"] No
blockCards Specified sets of cards can be blocked from appearing in Payment Methods lists. To block cards, include the blockCards parameter and specify a blocking list. See full details in the Blocking Cards topic.
The example shown here blocks Visa corporate credit cards, and also blocks British Amex cards.		 [["visa","credit","corporate"],["amex","GB"]] No
alwaysCollectCvv Default is true. true No
maskCvv Determines if the CVV digits in the CVV text box are masked (true) or visible (false)(default). false No
cardAuthMode Use this field to perform an MPI Only request, which means that a payment request is initiated for the 3DS validation, but an actual payment is not made.
Possible values:
  • paymentForAll (default) – Performs a 3DS validation and proceeds to payment automatically
  • 3dAuthOnly – Always performs only the 3DS validation (no payment).
  • 3dAuthForNewCardsOnly
    • – Performs only 3DS validation, but only for the first-time processing (not including UPOs).
paymentForAll No
fullName Used to prefill cardholder name (at least initially). 'John Smith' No
email Used to prefill email field for some PMs. This can be sent either here or in the /openOrder request. 'john.smith@email.com' Conditional
payButton Controls the text shown on the pay button. Possible values:
  • amountButton (default): Shows the amount on pay button, (example: "Pay $135")
  • textButton: Shows "Pay with [name of the payment method]".
  • noButton: The button can be displayed outside the checkout.
    When the user selects the button, it calls the submitPayment() method to invoke the payment externally from Checkout.
 amountButton No
showResponseMessage Controls the modals for checkout. If false, then modal messages are hidden, and only callback responses from Checkout will be displayed.
Default is true.		 true No
locale Default is en. 'de' No
textDirection Sets the text direction.
Possible values:
  • ltr (left-to-right) (default):
  • rtl (right-to-left)
 'ltr' No
autoOpenPM Controls whether PMs are always open in the presence of UPMs. true No
logLevel Console log-data detail level.
Default is 0 – "no logging".		 0 No
i18n You can replace existing messages with your own i18n messages (internationalization).
For examples see the i18n Styling topic.		 i18n : { my_methods : "Meine Zahlungsmethoden*" } No
clientUniqueId The ID of the transaction in your system. No
billingAddress class country,
firstName,
lastName,
address,
address2,
phone,
zip,
city,
state,
email,
county		 country and email
shippingAddress class firstName,
lastName,
address,
phone,
zip,
city,
country,
state,
email,
shippingCounty		 No
userDetails class firstName,
lastName,
address,
phone,
zip,
city,
country,
state,
email,
county,
language,
dateOfBirth,
identification		 No
checkout() Output Parameters

The output parameters returned include:

  • transactionStatus: Possible values: APPROVED, DECLINED, or ERROR (in case of any error).
  • errCode and errorDescription: In the case of an error, these contain the decline reason and error description.

For complete response details, see the Output Parameters table under the checkout() method.

Example checkout() Response 
{
  "result": "APPROVED",
  "errCode": "0",
  "errorDescription": "",
  "userPaymentOptionId": "14958143",
  "ccCardNumber": "5****5761",
  "bin": "511142",
  "last4Digits": "5761",
  "ccExpMonth": "09",
  "ccExpYear": "21",
  "transactionId": "1110000000004146935",
  "threeDReason": "",
  "threeDReasonId": "",
  "challengeCancelReasonId": "",
  "challengeCancelReason": "",
  "isLiabilityOnIssuer": "1",
  "challengePreferenceReason": "12",
  "cancelled": false
}

When the checkout process ends, you need to notify your server-side.

4. Response Verification

You should verify the payment response that you received on your server-side, before storing the complete payment information in your system.

Since the response from the checkout() method is returned from the client-side, it is vulnerable to manipulation by the end user; therefore, you need to verify the response on your server-side.

Verify the response using one of these methods:

  • Use DMN Notification

    You can use our Direct Merchant Notification (DMN) system to verify the response. In this case, you receive a direct notification to the webhook endpoint on your system. Details for the payment are received, as shown in the following example.

    Using DMNs is always recommended because Checkout also supports “Async APM” transactions, which may only return a response several hours later. Nuvei sends you a DMN with a verified response as soon as we have it.

    Example DMN Notification 
    https://myserver.com/SafeCharge/dmn/receiveNotification?ppp_status=OK&PPP_TransactionId=547&TransactionId=1110000000004146935&userid=111&merchant_unique_id=234234unique_id&customData=342dssdee&productId=12345product_id&first_name=Diyan&last_name=Yordanov&email=dido%40domain.com&totalAmount=200&currency=USD&Status=APPROVED

  • Send a /getPaymentStatus Request

    Alternatively, you can call the /getPaymentStatus API method from your server-side, using the sessionToken (returned from the /openOrder, and used in the checkout() method.)

    Using the sessionToken retrieves the complete and verified payment response, including some additional information about the payment and card used for the transaction.

    /getPaymentStatus can only be called while the session in which the payment was performed is still open. Once the session expires, you receive a “session expired” response.

    The /getPaymentStatus method can only be called at the end of payment processing for that payment.
    (You can detect the end of payment processing, by monitoring the JavaScript events for the final transaction event.)
    /getPaymentStatus is not intended for repeated status polling during the payment processing. Doing so may result in your IP address being blocked.

    Example /getPaymentStatus Request 
    {
  "sessionToken": "274ff0d9-c859-42f5-ae57-997641f93471"
}
    <?php
$getPaymentStatusRequest = $SafeCharge->getPaymentService()->getPaymentStatus([
    'sessionToken'  =>  '274ff0d9-c859-42f5-ae57-997641f93471',
]);
?>
    public class ExampleGetPaymentStatus {

    public static void main(String[] args) {
            GetPaymentStatusResponse response = safecharge.getPaymentStatus();
    }
}
    //Start by initializing the SDK. For more details, see the Nuvei .NET SDK at https://docs.safecharge.com/?p=48413.

// preceded by payment request
var response = safecharge.GetPaymentStatus();
    Example /getPaymentStatus Response

    For a full description of responses, refer to /getPaymentStatus.

    {
    "transactionStatus": "APPROVED",
    "gwExtendedErrorCode": 0,
    "errorCode": 0,
    "reason": "",
    "authCode": "075449",
    "clientRequestId": "9WD9JCZW9",
    "internalRequestId": 13004281,
    "version": "1.0",
    "transactionId": "2110000000001496240",
    "amount": "10",
    "currency": "USD",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "transactionType": "Sale",
    "clientUniqueId": "695701003",
    "errCode": 0,
    "paymentOption": {
        "userPaymentOptionId": "7072706",
        "card": {
            "uniqueCC": "NuBcbNkc7kBwNExS5j/wgIS8sNk="
        }
    }
    "sessionToken": "64fe6953-69d1-440f-8e21-878c85701f09",
    "userTokenId": '<some userTokenId>',
    "status": "SUCCESS"
}