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.
  • Advanced Controls – 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 provides an end-to-end payment solution.

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.

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: '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
  }
});

checkout() Input Parameters

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

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
min	Use to set a minimum payment amount.	1	No
max	Use to set a maximum payment amount.	9999	No
renderTo	The name of the HTML container that you created previously for Simply Connect. (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() method.	onResult: const onResult = function (result) { console.log(result)}	Yes
onReady	Defines a callback function triggered when the checkout() method 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
apmWindowType	This allows you to specify the window type (popup, newTab, redirect (modal window)) for the system to redirect the customer to their APM provider. Alternatively, by specifying customRedirect, the system provides you with the redirectUrl for you to initiate the redirect. Possible values: popup (default): A popup window opens automatically, redirecting the customer to their APM provider's page. newTab: A new tab opens automatically, redirecting the customer to their APM provider's page. redirect: A modal window opens automatically on top of the current payment page, redirecting the customer to their APM provider's page. Note:To use the redirect window type, you must have already provided the urlDetails (e.g. urlDetails.successUrl, etc.) in the /openOrder request, for the system to navigate the customer back to, after leaving the APM provider's page. customRedirect: You (the merchant) must redirect your customer to their APM provider’s page, as follows: The response from the request includes a redirectUrl. Redirect your customer to this redirectUrl using a type of window of your choice, for example, IFrame, popup, a new tab, etc. Your customer submits their APM details and closes the window. Check the transaction status either by sending a /getPaymentStatus request, or by setting up a DMN to receive a direct notification, (at the webhook endpoint on your system, which you provided in the urlDetails.notificationUrl in the original /openOrder request).	checkout({  ...  apmWindowType: 'newTab', // 'popup' (default), 'redirect', 'customRedirect'  ... })	No
onSelectPaymentMethod	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({…   onSelectPaymentMethod:   function(paymentDetails) {     console.log(     "onSelectPaymentMethod",     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: Apple Pay Guide (Simply Connect) Google Pay Guide (Simply Connect)	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	The savePM parameter is used to display the "Save my details for future use" checkbox for each payment method in the Payment Methods list. Possible values: true (default) – Users can save payment details for UPOs. Note: This is needed for the initial request of an APM Recurring Billing transaction. false – Users cannot save payment details for UPOs. always – Instead of the checkbox, an agreement message is displayed and payment details are always saved. In addition, you can include the savePmUrl parameter containing a link to the "Terms and Conditions for saving payment details". Note: savePM must be set to always for the savePmUrl to be displayed in addition to the agreement message.	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	Collects the CVV for a stored card. Possible values: true (default), false	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
disableNuveiAnalytics	When set to true, analytics are disabled to prevent the analytics tool from conflicting with the merchant code. Possible values: false (default), true	false	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: No button is displayed by the checkout() method. You should display a button (outside the checkout() method). When a customer presses this button, it should call the checkout.submitPayment() method, to invoke a payment process outside the checkout() method flow.	amountButton	No
showResponseMessage	Controls the message dialogs for the checkout() method. If false, then message dialogs are hidden, and only callback responses from Simply Connect are 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

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, other the APMs).
• Advanced Controls
  Hook into the payment process in order 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 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, 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"
}