Web SDK

The Web SDK helps to reduce your PCI compliance burden when handling sensitive credit card information, while providing the freedom to control your checkout page’s styling. The Web SDK fully supports the Strong Customer Authentication (3DSecure 2).

What you can do with the Web SDK

Create Payment
Create SCA Payment (3DSecure 2)
Create Recurring Payment
Store card information for later use (tokenization)

Before You Begin

Make sure you’ve been registered to our portal, created a sandbox account, and received the credentials (PRIVATE_KEY)
You have your own checkout page/form

Please follow this step-by-step guide for quick integration:

Create Checkout request and get the Session token

Our web SDK is a client application used to collect sensitive credit card information, bank account details, and other sensitive data in a more secure manner.

In this case, the same sessionToken for client application is being generated when creating an order server-to-server, and no additional effort is needed in order to allow fast and smooth payment for both developers and consumers.

Make a POST /pay-ins/checkout request:

cURL

curl --location --request POST 'https://sandbox.unipaas.com/platform/pay-ins/checkout' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{PRIVATE_KEY}}' \
--data-raw '{
  "amount": 60,
  "currency": "EUR",
  "orderId": "dfgdfh4366",
  "description": "iphone accessories",
  "email": "test@unipaas.com",
  "country": "GB",
  "items": [
    {
      "name": "iphone case",
      "amount": 50,
      "vendorId": "5ee8e655a65f08fcd71fe4d9",
      "platformFee": 15
    },
    {
      "name": "iphone screen protector",
      "amount": 10,
      "vendorId": "1ee8a555a65f08fcd71fe123",
      "platformFee": 2
    }
  ]
}'

In the Response, you will find the sessionToken field. Please keep it for the next steps.

Embed the Web SDK script

Place it on the head tag of your Checkout page.

HTML

<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script src="https://cdn.unipaas.com/unipaas.sdk.js"></script>
<link rel="stylesheet" href="https://cdn.unipaas.com/style.css">
<!-- polyfills for IE11 users -->
<script src="https://cdn.polyfill.io/v2/polyfill.min.js"></script>

Create your credit card checkout page

Create your checkout page using our Web SDK embedded secure fields, with HTML and Javascript. There are fields that must be used in order to create a credit card checkout. The following steps demonstrate how mandatory fields should be embedded in your checkout page.

Card holder name
Inside a form tag, we will add HTML code to collect the payment data from the user.
First, we will add the card holder name field:

HTML

<div class="payment-field">
   <label class="payment-field--cardholder-label">
      Cardholder name
      <div class="secure-field--container">
         <div id="holdername"></div>
      </div>
   </label>
</div>

Credit card details
Credit card details fields structure is available in two options

Single credit card details field (Recommended)

HTML

<div class="payment-field">
   <label class="payment-field--card-label">
      Card details
      <div id="card"></div>
   </label>
</div>

Separate credit card details fields

HTML

<div class="payment-field">
   <label for="card-number">
      Card number
      <div class="secure-field--container">
         <div class="secure-field" id="card-number"></div>
         <i class="secure-field--icon"></i>
      </div>
   </label>
</div>
<div class="payment-field">
   <label>
      Expiry date
      <div class="secure-field--container">
         <div class="secure-field" id="expiry-date"></div>
         <i class="secure-field--icon"></i>
      </div>
   </label>
</div>
<div class="payment-field">
   <label>
      CVC/CVV
      <div class="secure-field--container">
         <div class="secure-field" id="cvv-number"></div>
         <i class="secure-field--icon"></i>
      </div>
   </label>
</div>

Payment button
Once The Cardholder name and Credit card details fields are ready, add the Pay button to your form

HTML

<button id="submit-form">
   <div class="pay-icon"></div>
   Pay
</button>

Final HTML code
This is the final HTML code needed to embed mandatory secure credit card fields to your checkout page

HTML

<html>
   <head>
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <script src="https://cdn.unipaas.com/unipaas.sdk.js"></script>
      <link rel="stylesheet" href="https://cdn.unipaas.com/style.css">
      <!-- polyfills for IE11 users -->
      <script src="https://cdn.polyfill.io/v2/polyfill.min.js"></script>
   </head>
   <body>
      <form class="payment-form">
         <div class="payment-field">
            <label class="payment-field--cardholder-label">
               Cardholder name
               <div class="secure-field--container">
                  <div id="holdername"></div>
               </div>
            </label>
         </div>
         <div class="payment-field">
            <label class="payment-field--card-label">
               Card details
               <div id="card"></div>
            </label>
         </div>
         <div class="payment-checkbox">
            <input type="checkbox" name="save-card" />
            <label for="save-card">Save my credit card details securly for future purchases</label>
         </div>
         <button id="submit-form">
            <div class="pay-icon"></div>
            Pay
         </button>
      </form>
</html>

Initialize the SDK

Paste the following script to the end of the body tag to initialize the SDK.

JavaScript

<script>
   var unipaas = new Unipaas();

   var SESSION_TOKEN = 'TODO: token from earlier step'

   // use polyfiils for IE11
   unipaas.usePolyfills();

   unipaas.initTokenize(
       SESSION_TOKEN,
       {
           // single card details field:
           cardDetails: {
               selector: '#card',
               placeholder: { cardNumber: "1234 5678 9012 3456", cvv: "CVV", expiry: "MM/YY" },
           },

           // OR: seperate card details field:
           cardNumber: {
               selector: "#card-number",
               placeholder: "1234 5678 9012 3456 12"
           },
           cvv: { selector: "#cvv-number", placeholder: "123" },
           expiry: {
               selector: "#expiry-date",
               placeholder: "MM/YY"
           },

           // card holder field:
           cardHolder: {
               selector: "#holdername",
               placeholder: "A. Einstein"
           }
       },

       // submit button field will be sent in the third argument as additional field
       {
           additionalFields: {
               submitButton: {
                   selector: "#submit-form"
               }
           },
           mode: 'test'
       }
   );


       function disableButtonOnSuccess() {
           var sendButton = window.document.getElementById('submit-form');
           if (sendButton) {
               sendButton.disabled = true;
           }
       }

       unipaas.on('onSuccess', function (data) {
           console.log('Success:', data);
           disableButtonOnSuccess(true);
       })
       unipaas.on('onError', function (err) {
           console.log('Error:', err);
       })
</script>

Take the details of the Authorization and forward it to your server.
This step is required to confirm the Authorization status.

JavaScript

// on form submit
unipaas.on("onSubmission", () => {

});

// after token succeed
unipaas.on("OnTokenSuccess", (token) => {
  // You can keep the paymentOptionId for later use
});

// on any status except to success
unipaas.on("onError", (err) => {
  //Do something if the user cancelled the form
});

// the payment was successful
unipaas.on("onSuccess", (data) => {
  // take the data response and forward it to your server for additional checks

});

For example. we would like to disable the submission button after a successful authorization:

Example of returned Object

JSON

{
   authorizationId:"5ed899d595c589754607e86d",
   transactionId:"5ed899ff348b1f0206a9bf4d",
   authorizationStats:"Authorized",
   amount:260,
   currency:"GBP",
   consumerId: '60a66628c099a88b496d1c3a', //used in returning consumer saved card flow
   paymentOption:{
      paymentOptionId:"5ed899d495c5891df307e867",
      bin:"400002",
      brand:"VISA",
      last4digits:"0961",
      cardType:"Credit"
   },
   processor:{
      processorAuthCode:"111616",
      processorTransactionId:"1110000000006005501",
      processorErrorCode:0
   },
   threeD:{
      version:"2",
      eci:"5",
      xid:""
   }
}

Verify the Authorization status from your server side

Authorization verification is essential to ensure no manipulation occurred on the client-side.
Make a GET /pay-ins/{authorizationId} request:

cURL

curl --location --request GET 'https://sandbox.unipaas.com/platform/pay-ins/{authorizationId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{PRIVATE_KEY}}'

Authorization status must be “CAPTURED” for a successful Authorization. Check the Authorization statuses options for more information

Returning consumers saved card flow

Create a new Checkout request with the consumerId obtained in previous step and get a Session Token to be later on used on a seamless Web SDK flow:

cURL

curl --location --request POST 'https://sandbox.unipaas.com/platform/pay-ins/checkout' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{PRIVATE_KEY}}' \
--data-raw '{
  "amount": 60,
  "currency": "EUR",
  "consumerId":"60a66628c099a88b496d1c3a",
  "orderId": "dfgdfh4366",
  "description": "iphone accessories",
  "email": "test@unipaas.com",
  "country": "GB",
  "items": [
    {
      "name": "iphone case",
      "amount": 50,
      "vendorId": "5ee8e655a65f08fcd71fe4d9",
      "platformFee": 15
    },
    {
      "name": "iphone screen protector",
      "amount": 10,
      "vendorId": "1ee8a555a65f08fcd71fe123",
      "platformFee": 2
    }
  ]
}'

Example of partial returned Checkout object

JSON

{
    "id": "60a68232bce08d2b1c99190c",
    "amount": "60",
    "currency": "EUR",
    "consumerId": "5ef3c7dfac399c1fb9111347",
    .
    .
    .
    "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoiNjA5ZDEwYWVkMzdmMjg0NjUwZTIxNWZjIiwiYW1vdW50IjoiNjAiLCJjdXJyZW5jeSI6IkVVUiIsIm1lcmNoYW50dW5pcXVlaWQiOiJkZmdkZmg0MzY2IiwiY29uc3VtZXJJZCI6IjVlZjNjN2RmYWMzOTljMWZiOTExMTM0NyIsImVtYWlsIjoidGVzdEB1bmlwYWFzLmNvbSIsImNvdW50cnkiOiJHQiIsInNlbGxlcklkIjoiNjA5ZDEwYWVkMzdmMjg0NjUwZTIxNWZjIiwicGF5bWVudExpbmtJZCI6IkJIRHFCZzJwSmowIiwiaWF0IjoxNjIxNTI1MDQyLCJleHAiOjE2MjE1MjY4NDJ9.qlVd2b7vGGySuXHNXCy-jSk8PtebpWshWmDTvAoZN-0",
    "paymentOptions": [
        {
            "id": "60a66fd0b3d40d819beb17ea",//used in returning consumer saved card flow
            "cardAccount": {
                "last4digits": "0961",
                "brand": "VISA"
            }
        }
    ]
}

Web SDK pay with consumer’s saved card

HTML

<script>
  var unipaas = new Unipaas();

  var SESSION_TOKEN = 'TODO: token from earlier step'

  // use polyfiils for IE11
  unipaas.usePolyfills();

  unipaas.payWithToken(
    SESSION_TOKEN,
    {
      mode: 'test'
    }
  );

       function disableButtonOnSuccess() {
           var sendButton = window.document.getElementById('submit-form');
           if (sendButton) {
               sendButton.disabled = true;
           }
       }

       unipaas.on('onSuccess', function (data) {
           console.log('Success:', data);
           disableButtonOnSuccess(true);
       })
       unipaas.on('onError', function (err) {
           console.log('Error:', err);
       })
</script>

Then you can trigger payment by providing the paymentOptionId to makePayment function anywhere in your page:

JavaScript

unipaas.makePayment('60a66fd0b3d40d819beb17ea');

Test your integration

Use our test scenarios test your integration