Store Card (Tokenization) with Web SDK

Use this functionality when you want to store a consumer's card details for future use, as part of a returning consumer payment flow.

Card schemes often insist that a zero-authorization transaction (amount=0) gets sent before allowing card credentials to be stored for future use. In Europe the card schemes require the completion of Strong Customer Authentication (SCA) for each zero-authorization request.

Billing a consumer's saved card may trigger the SCA flow, upon issuer request, depending on the country and charged amount.

Use Web SDK to Store credit card details

Create a POST /pay-ins/token request:

curl --location --request POST 'https://sandbox.unipaas.com/platform/pay-ins/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{PRIVATE_KEY}}' \
--data-raw '{
    "email": "[email protected]",
    "country": "GB"
}'

In the Response you will find the sessionToken field. Keep it for the next steps.

Embed the Web SDK script

Put it on 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">

Add HTML code for the mandatory payment option details

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

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

<button id="submit-form">Save card</button>

Initialise the SDK

Put the script at the end of the body tag.

<script>
  var unipaas = new Unipaas();

  var SESSION_TOKEN = 'TODO: token from earlier step'

  unipaas.initTokenize(
    SESSION_TOKEN,
    {
      cardNumber: {
        selector: "#card-number",
        placeholder: "1234 5678 9012 3456 12"
      },
      cvv: { selector: "#cvv-number", placeholder: "123" },
      expiry: {
        selector: "#expiry-date",
        placeholder: "MM/YY"
      },
      cardHolder: {
        selector: "#holdername",
        placeholder: "A. Einstein"
      }
    },
    {
      additionalFields: {
        submitButton: {
          selector: "#submit-form"
        }
      },
      mode: 'test'
    }
  );

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

Listen to the client Events

// after token succeed
unipaas.on("onSuccess", (authorization) => {
  const consumerId = authorization.consumerId;
  // keep the consumerId for later use 
});

From the response JSON, save the consumerId, it will be later used to identify a returning consumer and get available payment options for that consumer.

The authorization object in the onSuccess callback will look like the following:

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

Create checkout for returning consumer

Create a new Checkout request with the consumerId obtained in the previous step and get a Session Token to be later on used on the 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
    }
  ]
}'

The response will list all payment options that are saved for the requested consumer. You can use this list of payment options to present your Consumers with their saved payment methods.

In the next step, you will use the id of one of the available paymentOptions to charge the relevant card.

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

Use the sessionToken you obtained in the previous step as per below:

<script>
  var unipaas = new Unipaas();

  var SESSION_TOKEN = 'TODO: token from earlier step'

  unipaas.payWithToken(
    SESSION_TOKEN,
    {
      mode: 'test'
    }
  );
  unipaas.on('onSuccess', function (data) {
    console.log('Success:', data);
  })
  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');

Recurring Transactions Using a Payment Option ID

If you already have a paymentOptionId that has been created for recurring transactions, you can charge the saved card directly using the following request:

Example API Request:

{
  "amount": 23.99,
  "consumer": {
    "country": "GB",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe"
  },
  "country": "GB",
  "currency": "GBP",
  "description": "Test Plan Description",
  "vendorId": "65ad0887ba5bb927d1abea8a",
  "paymentOptionId": "6699167a3acfb81509da5765",
  "reference": "19168"
}