Getting Started with Simply Connect 2.0

Home    Online Payments    Simply Connect 2.0 (Beta Release)    Getting Started with Simply Connect 2.0

On this page:

Overview

Simply Connect 2.0 (simplyConnect() method) is a single end-to-end solution for accepting payments. Simply Connect 2.0 integrates into a payment flow, with a customizable user-interface that is embedded into a payment page. This guide provides information and procedures for integration of the Simply Connect 2.0 simplyConnect() method into a payment page.

Getting Started

This section provides details about the following steps for integration of the simplyConnect() method into your payment page.

    1. Send a POST/orders server-to-server Rest API 2.0 request to open a unique temporary session.
    2. Create an HTML placeholder as the location for the import of the simplyConnect.js JavaScript library.
    3. Instantiate the Simply Connect 2.0 method.
    4. Verify transaction response (mandatory).

A. Send a POST/orders server-to-server Rest API 2.0 request to open a unique temporary session

Perform the following mandatory procedure to load the check-out call-to-action button for the site using Simply Connect 2.0.

    1. (prerequisite) Make sure to have the processingEntityId and xAPIKEY, which are provided by the Nuvei Integration Team and are available in the Nuvei Control Panel. The POST /orders API call authenticates the merchant using the credentials processingEntityId and xAPIKEY.
    2. Initiate a session by sending a POST/orders API call that must include the provided by Nuvei:
      – processingEntityId within the body of the payload
      – xAPIKEY in the header of the POST /orders request
    3. In the Nuvei system, call the authentication POST /orders request using the URL https://api.nuvei.com/sdk-api/orders.
      A sessionId is returned.

The sessionId is referenced later in the process by the simplyConnect()method to initialize the payment page.

Example of POST /orders request with header – POST /orders HTTPS/1.1
Host: api.nuvei.com 
Content Type: application/json
xAPIKEY: <your API key>
{ 
“processingEntityId”: <your processingEntityId value> 
“amount”: 10, 
“currency”: “USD”, 
}, 
"permittedOperations": [ 
"operations", 
}
Example of POST /orders response
{
“sessionId": "sid_2ade498fd0f6425e91a9b62909c6ab98”,
"result":{
"status": "success"
 }
}

B. Create an HTML placeholder as the location for the import of the simplyConnect.js JavaScript library

This section provides details about placing the Simply Connect 2.0 payment user-interface on the front-end, which allows the customer to select from different payment methods and to enter card and account details. Scripts are added to create an HTML placeholder on a web page. The scripts do the following:

  • Import the simplyconnect.js JavaScript library which is used for building payment flows.

    The JavaScript library enables Nuvei to collect sensitive customer data and to create representative tokens. The tokens are used to safely send sensitive data to your servers in a ‘PCI-descoped’ way and to process card details.

  • Create an HTML placeholder element on the payment page.
    If the simplyconnect() method is called, the content of the Simply Connect payment form is rendered into a container.
Example HTML to render Simply Connect Payment Form
<head>  
  <title>Simply Connect</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk//simplyConnect_v2.js"></script>
</head>

<body>
  <br /><br />
  <div id="simplyConnect" style="width:400px;height:600px;border: 1px solid #d3dce6;" 
  ="><br /><br />The page is displayed here.</div>
</body>

To customize the Simply Connect payment user-interface 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 user-interface component. For details, see UI Customization.

C. Instantiate the Simply Connect 2.0 method

This section provides information about performing a simplyConnect() payment.

To perform a simplyConnect() payment:

  1. Call the simplyConnect() method.
    1. Include any relevant Simply Connect input parameters. See Example of simplyConnect() request.
    2. Customize the user-interface and user-experience processing, for enhancement beyond the basic features. See Example of simplyConnect() response.

The simplyConnect() Output Parameters include Status and other details.

simplyConnect() Input Parameters

For a list of request details, in Simply Connect 2.0 Methods, see the Input Parameters tables.

Example of simplyConnect() request
window.simplyConnect
(
  env: env, 
  renderTo: "#root",
  sessionId: sessionId, // The session ID value is a result of the POST/orders request 
  eventCallbacks: {
  onResult: function(result) {
    console.log(result)}, {
   },
},
uiConfig: {
countryCode: "US",
},
} }
}


 A


Nuvei JSFiddle example


is provided to help you get started with building your own simplyConnect() request.

simplyConnect() Output Parameters

After Simply Connect has handled payments for you and your customers, a status is returned from the onResult callback event. For this reason, the function must be included during initialization. See example of a simplyConnect() initialization.

Returned output parameters include:

• status– Possible values: Approved, Declined, Pending, or Error.

• code and reason: In the case of an error, the value contains the decline error code and the error reason.

For complete request details, see the ‘Output Parameters’ table for simplyConnect() method.

Example of simplyConnect() response
"paymentId": "97736efe02234107a32c4f0e269abb86",
"transactionId": "8110000000006536113",
"amount": 10,
"currency": "USD",
"transactionType": "Sale",
"result": {
"status": "declined",
"errors": {
"code": "1400.1000",
"reason": "Decline"
}
 "paymentOption": {
  "card": {
   "cardHolderName": "CL-BRW1",
   "maskedCardNumber": "5****1111",
   "bin": "555544",
   "last4Digits": "1111",
   "expirationMonth": "12",
   "expirationYear": "45",
   "acquirerId": "19",
   "cardBrand": "MASTERCARD",
   "threeD": {}
  }
 }
}

D. Verify transaction response (mandatory)

Verification of the response is mandatory following the checkout process. The response from the simplyConnect() method is returned from the client side, therefore the response is vulnerable to manipulation by the end user. It is mandatory to verify the payment response received on the server side before storing the complete payment information in the system.

To verify the response, use one of the following methods:

  • Webhooks – Enable and configure REST API 2.0 Webhooks, which Nuvei sends to an endpoint on the system.

Webhooks

Use of Webhooks is recommended because Simply Connect supports Asynch APM transactions which may return a response only after several hours. With Webhooks, Nuvei sends a DMN with a verified response as soon as Nuvei receives the response.

Example of Webhooks – 3DSv2 payment DMN (Frictionless and Challenge)
{
"authorizingEntityId": "6d5af337-cdac-4da5-ad04-0e9d7470af36",
"processingEntityId": "6d5af337-cdac-4da5-ad04-0e9d7470af36",
"transactionId": "8110000000001701454",
"version": "2.0",
"amount": 60,
"currency": "USD",
"transactionType": "Sale",
"result": {b
  "status": "APPROVED"
},
"authCode": "111133",
"timeStamp": "2024-09-13T06:37:15.708542936Z",
"partialApproval": {
  "requestedAmount": 60,
  "requestedCurrency": "USD"
},
"paymentOption": {
"card": {
  "cardHolderName": "FL-BRW1",
  "maskedCardNumber": "5****0008",
  "bin": "554506",
  "last4Digits": "0008",
  "expirationMonth": "12",
  "expirationYear": "25",
  "acquirerId": "19",
  "cardType": "Credit",
  "cardBrand": "MASTERCARD"
  }
}
}
{
  "authorizingEntityId": "6d5af337-cdac-4da5-ad04-0e9d7470af36",
  "processingEntityId": "6d5af337-cdac-4da5-ad04-0e9d7470af36",
  "transactionId": "8110000000001701518",
  "version": "2.0",
  "amount": 60,
  "currency": "USD",
  "transactionType": "Sale",
  "result": {
  "status": "APPROVED"
  },
  "authCode": "111750",
  "timeStamp": "2024-09-13T06:39:57.903467664Z",
  "partialApproval": {
  "requestedAmount": 60,
  "requestedCurrency": "USD"
  },
  "paymentOption":{
  "card":{
  "cardHolderName": "CL-BRW1",
  "maskedCardNumber": "5****0008",
  "bin": "554506",
  "last4Digits": "0008",
  "expirationMonth": "12",
  "expirationYear": "25",
  "acquireerId":"19",
  "cardType": "Credit",
  "cardBrand": "MASTERCARD"
  }
 }
}

Send a GET /entities/{processing-entity-id}/transactions/{transaction-id} Request

Send a server-side GET /entities/{processing-entity-id}/transactions/{transaction-id} REST 2.0 API request using the sessionId from the POST /orders response (also used to initialize the Simply Connect 2.0 using the simplyConnect() method).

You can only send a GET /entities/{processing-entity-id}/transactions/{transaction-id} request:

  • Before the session in which the payment was performed expires. After the session expires, the response is session expired. (A session usually expires after fifteen minutes unless there is a different configuration on the Nuvei system as per a merchant request).
  • After the submitPayment()process ends. To detect the end of the process, monitor the JavaScript events for the onResult event.
Last update iconLast modified August 2025