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
Embed the web SDK script
Create containers for card fields
Create a container for Apple Pay or Google Pay
Initialize the SDK
Verify the Authorization status from your server side
Returning consumers saved card flow
Test your integration

Generate checkout request and obtain session token

Make a POST /pay-ins/checkout request from your server. Read more about payment creation.

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. Keep it for the next steps.

JSON

{
  "id": "60a68232bce08d2b1c99190c",
  "amount": "60",
  "currency": "EUR",
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
}

Embed the web SDK script

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

HTML

<script src="https://cdn.unipaas.com/unipaas.sdk.js"></script>
<link rel="stylesheet" href="https://cdn.unipaas.com/style.css">

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:

HTML

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

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

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

HTML

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

HTML

<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. Item selection - Where the user selects the items to be paid.
2. An image of the pre-purchase screen, where the user is ready to make a payment.
3. An image of the all available payment methods including Google Pay button.
4. 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).
5. 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).

HTML

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

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'


   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.

JavaScript

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

JSON

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

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....",
    "paymentOptions": [
        {
            "id": "60a66fd0b3d40d819beb17ea",
            "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'


  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 the makePayment function anywhere in your page:

JavaScript

unipaas.makePayment('60a66fd0b3d40d819beb17ea');

CVV validation for returning users

To require a returning consumer to re-enter their card’s CVV before paying with a saved card, add "cvvCheck": true alongside the consumerId in the checkout request. The flag is carried by the sessionToken, so the SDK prompts for the CVV when the consumer pays with a saved payment option. No change to the client-side payment call is required.

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": "GBP",
  "country": "GB",
  "email": "test@test.com",
  "consumerId": "5ef3c7dfac399c1fb9111347",
  "cvvCheck": true,
  "items": [
    {
      "name": "Iphone case",
      "amount": 60,
      "vendorId": "5ee8e655a65f08fcd71fe4d9",
      "platformFee": 0
    }
  ]
}'

When more than one saved card is returned in paymentOptions, let the consumer choose one and pass its id to payWithToken, falling back to makePayment() for a brand-new card:

JavaScript

function onPay(selectedPaymentOptionId) {
  if (selectedPaymentOptionId) {
    unipaas.payWithToken(SESSION_TOKEN, { paymentOptionId: selectedPaymentOptionId, mode: 'test' });
  } else {
    unipaas.makePayment();
  }
}

Test your integration

Use our test scenarios test your integration