The web SDK solution simplifies payment handling and allows platforms to customize their checkout experience, incorporating card payments as well as Apple Pay and Google Pay integration.

With the web SDK, you have the ability to securely handle sensitive information without the burden of PCI compliance, all while tailoring the checkout process to align with your product's user experience. The web SDK offers complete support for Strong Customer Authentication (SCA) through its seamless integration of the 3D Secure 2.0 protocol, this ensures that your customers maintain confidence and satisfaction throughout their payment journey.

The web SDK capabilities

One-time payments
SCA Payments (3D Secure 2.0)
Saved cards payments (tokenisation)

Prerequisites

Please ensure that you have completed the following steps:

Registration: Register on the UNIPaaS portal.
Sandbox account: Upon completing the registration process, you will gain instant access to a sandbox account for testing purposes.
Credentials: Obtain your private key for authentication purposes.

Additionally, make sure you have a dedicated checkout page or form to integrate the web SDK seamlessly.

Integration guide

Generate checkout request and obtain session token

Make a POST /pay-ins/checkout request.

Embed the web SDK script

Place the following script within the head tag of your Checkout page.

<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 containers for card fields

To successfully create a credit card checkout, it is essential to include the following containers.

Cardholder name field
To enable the required input of user's name for payment processing, include the following code within a form tag:

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

Credit card details fields
To enable the required input of card details, include one of the following code options within a form tag:

⚙️
There are two available options for the structure of the credit card details fields.

Unified credit card details field (Recommended)

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

Separate credit card details fields

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

"Save card" checkbox

To offer users the option to store their card for future purchases, you can allocate a container for the "Save card" checkbox using the following code:

<div class="payment-checkbox">
  <input type="checkbox" name="save-card"></input>
   <label for="save-card">Save my credit card details securly for future purchases</label>
</div>

Payment submission button
After creating the cardholder name and credit card details fields containers, finalise the checkout page structure by including the payment submission button container.

<button id="submit-payment">Pay now</button>

Create a container for Apple Pay or Google Pay

To enable Google Pay and Apple Pay integration within UNIPaaS Checkout WebSDK product, you need to verify your domain with Apple and Google. UNIPaaS team will support you in this process.

Please be sure to register both your development and production domains and subdomains.

We highly recommend verifying both Apple and Google pay

For Apple Pay:

Send UNIPaaS the domain in which you plan to implement the WebSDK
UNIPaaS will generate a domain association file for you to implement on your domain.
Once UNIPaaS provide you with the association file you should locate it in a well-known directory of your http server (see Apple instructions).
Notify UNIPaaS the file was implemented, and we will approve your domain with Apple.
Post production approval you can remove the file.

For Google Pay:

Send UNIPaaS the URL in which you plan to implement the WebSDK and the following images:
1. An image of the pre-purchase screen, where the user is ready to make a payment. Showing all available payment methods.
2. An image of the checkout page / frame when Google Pay button is selected.
3. Google Pay API payment screen. Where the user is shown the payment method they saved to Google Pay. (Note: Android will not allow you to make a screenshot for this screen, use a different device to do so).
4. Post purchase screen. Where the user has made a successful payment.
  Use Google Pay brand guidelines to speed up approval.
UNIPaaS will submit these documents on your behalf and will communicate any feedback to you.
Once the domain is approved, UNIPaaS will notify you.

Once the domain is verified use the following to build the container:

You should use a single container when using GooglePay and ApplePay. Due to restrictions, ApplePay and GooglePay buttons cannot be displayed together (Apple may disapprove your domain). The script below contains a prioritizations that will be used to render only one of the options within the div container (based on the device it loaded on).

<div id="applepay_googlepay"></div>

Initialize the SDK

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

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

         paymentComponents: [ //for both GooglePay and Apple Pay - priotirize Apple Pay and render immediately on load
           {type: "applePay", params: {selector: "#applepay_googlepay"}, priority: true, renderImmediately: true},
           {type: "googlePay", params: {selector: "#applepay_googlepay"}, renderImmediately: true}
         ],
           
           mode: 'test' //possible values: live (production) or test(sandbox)
       }
   );
   
   
       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.

// on form submit
unipaas.on("onSubmission", () => { //for cards and a Apple Pay and Google Pay
  
});

// 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:

Response

{//on success
   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 --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 --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": "[email protected]",
  "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

{
    "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

<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:

unipaas.makePayment('60a66fd0b3d40d819beb17ea');

Test your integration

Use our test scenarios test your integration