Overview

The Simply Connect 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.

This guide steps you through the Simply Connect integration process.

Benefits of Using Simply Connect

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.
• Customizing UI / UX / Processing:
  • General Customization – Control text and local options as well as the general look and feel.
  • Payment Customization – Control the payment flow and payment methods displayed for particular users or use cases. Control payment method processing behavior for the various cards, PayPal, Google Pay, Apple Pay, other the APMs.
  • Event Callbacks – Hooking into the payment process events to access event notifications, affect and react to events in the payment process, and improve the user experience.
    Full customization, locale customization, controlling the payment flow and the payment methods.

Visit our Simply Connect Demo Site

Press this button to visit our Simply Connect Demo Site!

Getting Started

Follow these simple steps described in the topics below to integrate the checkout() method into your payment page.

1. Initiate a Session

The customer begins the payment process as usual by pressing 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 use Postman to simulate the /openOrder workflow using the “Web SDK API calls” postman collection in the Nuvei sandbox environment.
  To install Postman and the relevant simulation collection, follow the steps in the Testing APIs with Postman topic.

  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).

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",
    "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',
]);
?>

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, 
APIConstants.Environment.INTEGRATION_HOST.getUrl(), 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";

Safecharge safecharge = new Safecharge();
SafechargeResponse response = safecharge.openOrder(userTokenId, clientRequestId,
clientUniqueId, null, null, null, null, currency, amount, null, null, null, null, 
null, null, null, null, null, null, null, null, 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>",
);

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'
}, 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

Follow these steps to place a Simply Connect payment UI on your frontend, to allow your customers to select their payment methods, and to enter their cardholder details.

Create the HTML placeholder by adding the following scripts on your payment page.

The scripts do the following:

1. Imports the checkout.js JavaScript library which is used for building payment flows.
   It allows you to collect sensitive data from your customers and create representative tokens. These can then be used to safely send sensitive data to your servers in a “PCI descoped way”, and also used to process card details.
2. Creates an HTML placeholder element on your payment page.
   The example shown below creates an HTML container named checkout. When calling the checkout() method, the content of the Simply Connect payment form is rendered into this container.

   Example HTML that Renders a Simply Connect 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 Simply Connect payment UI by customizing the CSS styles to match the styles in your own payment page, or anchor the component location, or override the default CSS styles of the Simply Connect payment UI component.
   For details, see the Payment Form Styling topic.

3. Perform a checkout() Payment

The 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, which embeds seamlessly into your payment page.

Call the checkout() method and include any relevant input parameters and customizations:

• checkout() Input Parameters
  Include any relevant input parameters.
• Customizing UI / UX / Processing
  These customizations allow you to provide much more than just the basic features.

The checkout() Output Parameters include transactionStatus and other details.

checkout() Input Parameters

For complete request details, see the Input Parameters tables under checkout().

The example below shows the simplest Simply Connect invocation, which provides the customer with a full payment experience.

Example Simple checkout() Request

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: '[email protected]',
  billingAddress: {
    email: "[email protected]",
    country: "US"
  },
  renderTo: '#checkout',
  onResult: function(result) {
    console.log("Result", result) // this is where you get notified after per payment result
  }
});

Customizing UI/UX/Processing

Simply Connect provides comprehensive sets of customization controls for the UI/UX and payment process, as described in these topics:

• UI Customization
  Control text and local options as well as the general look and feel.
• Payment Customization
  Control the payment flow and payment methods displayed for particular users or use cases. Control payment method processing behavior for the various cards, PayPal, Google Pay, Apple Pay, and other APMs.
• Event Callbacks
  Hook into the payment process to get event notifications, affect the payment process, and improve the user experience.

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 request details, see the Output Parameters table under checkout().

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, as described in the next step.

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.

Verify the response using one of these methods:

DMN

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.

Example DMN

...'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',

/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.)

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.nuvei.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"
}