Skip to main content

Atelio cards SDK

Overview​

We provide the AtelioCards SDK in the Atelio Web SDK to shield you from the burden and compliance requirements needed when handling personal data.

Anyone that wants to store or process card details (that include the PAN, CVV, expiry date, and PINs), you have to comply with PCI DSS data security requirements. To achieve compliance requires a lot of overhead. To reduce this overhead, we provide our AtelioCard SDK that takes care of vaulting and tokenizing sensitive card information for you. Using our SDK, you can easily allow your customers to retrieve their card details, and set and reset PINs without having to develop code that is compliant from scratch. The SDK takes care of preventing anyone not authorized from seeing your customers' sensitive card details.

The SDK relies heavily on Promises which makes it easy to handle the asynchronous requests that are made to the API. The SDK provides a AtelioCards object containing several methods which map to the calls and parameters that are described in detail in Atelio Web SDK Documentation.

To use the SDK, you can either build the repo yourself or install it.

Requirements​

To build the repo (with or without sample files), you need Node.js v6.3.0 or above.

Node installation includes NPM which is responsible for dependency management.

Importing the package​

You can import the package into your code using either NPM or CDN.

Using NPM​

To import the package using Node Package Management (NPM), do the following:

  1. Install the package by entering the following in a terminal window: npm install bond-sdk-web
  2. Import the package into your JavaScript code as follows:
JavaScript
import { AtelioCards } from 'bond-sdk-web';

Using CDN​

To import the package using a Content Delivery Network (CDN), you can use either JavaScript or HTML. For additional information, see CDN.

import AtelioCards from 'https://cdn.atelio.com/sdk/web/v1/bond-sdk-web.js';

Using the AtelioCards SDK​

The snippets and descriptions below are generic examples of how you can use the SDK to execute a request.

For details regarding specific methods, see the SDK documentation.

1. Authorize the calls using temporary tokens​

Before executing any request, you need to authorize the calls to the Atelio API and to initialize AtelioCards. Make an authorized call from your backend with the correct customer_id or business_id to receive temporary tokens (identity, authorization).

Note: These are short-lived tokens lasting for a maximum of five API calls or up to five minutes.

curl --request POST \
--url https://sandbox.atelio.com/api/v0.1/auth/key/temporary \
--header 'Content-Type: application/json' \
--header 'Identity: YOUR_IDENTITY' \
--header 'Authorization: YOUR_AUTHORIZATION' \
--data '{"customer_id": "YOUR_CUSTOMER_ID"}'

📘 Note

For a business resource, use business_id in place of the customer_id.

2. Initialize AtelioCards​

Call the constructor using:

JavaScript
const bondCards = new AtelioCards({ live: false });

Note: use live: true to access the live environment.

3. Make a request​

You can now use the various methods from the SDK to reveal/manage PCI-sensitive data for a particular card ID.

Following the Promises notation, use:

  • .then() to handle all successful requests
  • .catch() to handle all failed requests

Most of the calls take an object as the only parameter but refer to the API documentation to tailor the request as needed.

The following is an example of a request:

JavaScript
bondCards
  .show({
    cardId: 'YOUR_CARD_ID',
    identity: 'YOUR_IDENTITY',
    authorization: 'YOUR_AUTHORIZATION',
    field: "number",
    htmlSelector: "#num",
  })
  .then((data) => {
    // Handle data
  })
  .catch((error) => {
    // Handle an error
  })

4. Control loading​

You can control loading using the methods from the SDK:

  1. Show the loader.
  2. Wait for a response.
  3. Hide it when needed.

The following is an example:

JavaScript
  // Handle show loading
  bondCards
    .showMultiple(configuration)
    .then((data) => {
      // Handle hide loading
    })
    .catch((error) => {
      // Handle hide loading
    });

👍 Check out the demo app

To see more examples of using the AtelioCards SDK, you can check out the Atelio SDK demo on GitHub.

Displaying card details​

Card details in HTML​

You can use AtelioCards to insert iFrames with relevant card details into an HTML page using <div> elements with IDs.

The following pseudocode inserts the retrieved card details in a page:

HTML
<div class="field">
   Card Number
   <div id="num" class="card-field"></div>
   <div id="num_copy_btn"></div>
</div>
<div class="field">
   Expiration Date
   <div id="exp" class="card-field"></div>
   <div id="exp_copy_btn"></div>
</div>
<div class="field">
   CVV2
   <div id="cvv" class="card-field"></div>
   <div id="cvv_copy_btn"></div>
</div>

Card details in JavaScript​

There are two methods to display card details in JavaScript:

atelioCards
.show({
    cardId: 'YOUR_CARD_ID',
    identity: 'YOUR_IDENTITY',
    authorization: 'YOUR_AUTHORIZATION',
    field: "number",
    htmlSelector: "#num",
})
.then((data) => {
    // Handle data
    atelioCards.copy({
    iframe: data,
    htmlSelector: '#num-copy-btn',
    callback: (status) => {
        if (status === 'success') {
        console.log('copied!')
        } else {
        console.log('error!')
        }
    },
    format: {
        replaceThis: "\\W",
        withThis: "",
    },
    text: 'Copy data',
    css: cssBtn,
    })
    .then((data) => {
            // Handle data
        })
    .catch((error) => {
            // Handle an error
        })
})
.catch((error) => {
    // Handle an error
})

AtelioCards in script files​

  1. Import the SDK
  2. Get temporary security tokens
  3. Initialize the AtelioCards class

1. Import the SDK​

Import usingJavaScript
node.jsimport { BondCards } from 'bond-sdk-web';
the CDNimport { BondCards } from 'cdn.atelio.com/sdk/web/v1/bond-sdk-web.js';

2. Get temporary security tokens​

Use the following sample code with the API to get temporary tokens by making a call to the backend.

curl --request POST \
--url https://sandbox.atelio.com/api/v0.1/auth/key/temporary \
--header 'Content-Type: application/json' \
--header 'Identity: YOUR_IDENTITY' \
--header 'Authorization: YOUR_AUTHORIZATION' \
--data '{"customer_id": "YOUR_CUSTOMER_ID"}'

📘 Note

For a business resource, use business_id in place of the customer_id`.

3. Initialize the AtelioCards class​

Initialize the AtelioCards class using the following JavaScript:

JavaScript
const bondCards = new AtelioCards({ live: false });

Pass {live: true} when using the live environment.

4. Display a PIN​

On an event such as a button click or page load, you can call bondCards.show() for each of the fields whose data you want to display using appropriate parameter values.

You need to send the following:

  • card_id
  • Temporary Identity and Authorization tokens
  • Field type:
    • number for the credit card number
    • expiry for the expiry date
    • cvv for the card verification value
  • The HTML/CSS selector of the div/field where you want the iFrame to be inserted

.show example​

JavaScript
bondCards
  .showPIN({
    cardId: 'YOUR_CARD_ID',
    identity: 'YOUR_IDENTITY',
    authorization: 'YOUR_AUTHORIZATION',
    reset: true // (optional) Reset the PIN and show new PIN
    htmlSelector: "#pin",
    css: {'font-size': '14px'} // (optional) An object of CSS rules to apply to the response.
  })
  .then((data) => {
    // The iFrame with revealed data will already be inserted.
    // But you can get a reference to it here and handle data further if you like.
  })
  .catch((error) => {
    // Handle an error
  });

Formatting examples​

You can manipulate card numbers and expiry dates in a number of ways, as shown in the table below.

Change requiredReplace this:With this:
To separate card number using dashes:
4111111111111111 --> 4111-1111-1111-1111		'(\\d{4})(\\d{4})(\\d{4})(\\d{4})','$1-$2-$3-$4'
To separate card number using spaces:
4111111111111111 --> 4111 1111 1111 1111		'(\\d{4})(\\d{4})(\\d{4})(\\d{4})','$1 $2 $3 $4'
To remove spaces:
4111 1111 1111 1111 --> 4111111111111111		' '''
To remove the first two dashes:
4111-1111-1111-1111 --> 411111111111-1111		'-'"", count: 2
To separate card expiry month and year using a slash:
122021 --> 12/2021		'(\\d{2})(\\d{4})''$1/$2'

Setting a card's PIN​

Setting a card PIN in HTML​

You can use BondCards from the Atelio Web SDK to insert <form> fields with IDs into an HTML page to capture PIN details using <div> elements. The following pseudocode captures PIN details.

HTML
<form id="cc-form">
  <div class="field">
    New PIN
    <div id="cc-new-pin" class="card-field"></div>
  </div>
</form>

AtelioCards SDK in script files​

Before you can use the AtelioCards SDK in you scripts, you need to:

  1. Import the SDK
  2. Get temporary security tokens
  3. Initialize the BondCards class

1. Import the SDK​

Import usingJavaScript
node.jsimport { BondCards } from 'bond-sdk-web';
the CDNimport { BondCards } from 'cdn.atelio.com/sdk/web/v1/bond-sdk-web.js';

2. Get temporary security tokens​

Use the following sample code with the API to get temporary tokens by making a call to the backend:

curl --request POST \
--url https://sandbox.atelio.com/api/v0.1/auth/key/temporary \
--header 'Content-Type: application/json' \
--header 'Identity: YOUR_IDENTITY' \
--header 'Authorization: YOUR_AUTHORIZATION' \
--data '{"customer_id": "YOUR_CUSTOMER_ID"}'

3. Initialize the AtelioCards class​

JavaScript
const bondCards = new AtelioCards({ live: true });

4. Call bondCards.field()​

On an event such as a page load, you can call bondCards.field() for each <div> where you want a user to enter PIN data.

You need to send the following:

  • HTML/CSS selector of the <div> where you want the form field to be inserted
  • Field type:
    • new_pin

Example call of bondCards.field()​

JavaScript
bondCards
  .field({
    selector: "#cc-new-pin",
    type: "new_pin",
  })
  .catch((error) => {
    console.error("error", error);
  });

5. Add an event listener​

Add an event listener to call AtelioCards when the form is submitted.

You need to send the following:

  • card_id
  • Temporary Identity and Authorization tokens.
  • Form field values (new_pin is a required field).
  • A callback function you want executed when the HTTP request has completed successfully.
  • A callback function you want triggered when a field is invalid or upon an error.

Example of adding an event listener​

JavaScript
document.querySelector("#cc-form").addEventListener("submit", (e) => {
  e.preventDefault();
  bondCards.submit({
    cardId: 'YOUR_CARD_ID',
    identity: 'YOUR_IDENTITY',
    authorization: 'YOUR_AUTHORIZATION',
    newPin: document.getElementById("cc-new-pin").value,
    successCallback: function (status, data) {
      console.log('Successfully set new pin as: ', data.new_pin);
    },
    errorCallback: function (errors) {
      console.log(errors);
    },
  });
});