Card tokenization SDK

The Paylands tokenization SDK is a Javascript library that allows to store customer cards using a form contained in an iframe within the Paylands domain. In this way, merchants that cannot manage card data can use this form to request it from users without the merchant itself being involved in the collection and storage of such data. This process returns the tokenized card to the merchant.

The Javascript SDK communicates with the client's web through events, so that each method of the SDK will throw an event to the DOM that can be picked up by the client to act accordingly.

Integration

Let's perform the integration of the Tokenization Javascript SDK to load the form and send the card to Paylands.

1. Load the SDK library in your web or app.

The library can be obtained from the following link:

https://api.paylands.com/js/v1-iframe.js

You can load the library by copying and pasting the following script into your website:

<script type="text/javascript" src="https://api.paylands.com/js/v1-iframe.js"></script>

Once the library is loaded there will be a new global variable paylands with which we can interact.

2. Create the client user to which the card will be assigned

To display the form it is necessary to first create the client to which the card will be assigned. From your server you must make a request to the Paylands API to Create the customer.

curl --request POST 'https://api.paylands.com/v1/customer' \
--header 'Authorization: pk_test_3c140607778e1217f56ccccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
  "signature": "121149a0ba5361191d740fa898784a8b",
  "customer_ext_id": "customer15487"
}'

This request returns the token of the client that we will have to use in the next step.

{
  "message": "OK",
  "code": 200,
  "current_time": "2017-01-12T09:12:58+0100",
  "Customer": {
    "external_id": "customer15487",
    "token": "TOKEN"
  }
}

3. Display the form

With the user's token we must make a call to the paylands.initializate() method when the paylandsLoaded event is fired in the DOM. Otherwise, the paylands variable may not be initialized.

In our DOM we create a div where we want to display the form.

<div id="paylands-iframe"></div>

With this Javascript call we will load the form in the paylands-iframe div for the client of the token obtained in the previous step.

<script>
window.addEventListener('message', receiveMessage => {
    if (receiveMessage.data === 'paylandsLoaded') {
        //Listen to paylandsLoaded message to continue
        console.log('PaylandsLoaded', paylands);
        //If we are testing we should change the mode to sandbox
        //In production remove this line
        paylands.setMode('sandbox');
        //Initialize the form
        paylands.initializate(
            'TOKEN',
            'paylands-iframe'
        )
    }
}, false);
</script>

The form will appear with the following format.

SDK Tokenization Form

You can customize the appearance of the form in the Paylands Backend → Customization → Templates. By clicking the create new button, you will be able to select the Tokenization Letter type template where it will allow you to completely modify its appearance. In the case of having configured a custom template we will have to apply it in our code using the setTemplate method.

paylands.setTemplate(
    C082AA84-EC2D-4ED2-9312-D099283232E490' // UUID of the template you created.
)

note

Customization using a Template tokenization letter template is completely optional. If setTemplate is not used, the form will load the default template.

4. Save the card

Once the form is loaded and the user has entered their card details, we will make a request to paylands.storeSourceCard() to store it in Paylands.

When executing the paylands.storeSourceCard() method, first the entered data is validated and depending on whether there is an error or not, the error or validation event will be fired respectively. This validation only validates the format of the data entered.

info

If you need to check that the card has funds, that it is not blocked, etc, this method supports two parameters: the first is a boolean value set to true to indicate that you need to validate the card against the bank. The second parameter is the service_uuid included with the API credentials. The validation consists of a 0€ charge on the user's card to verify that the card is valid.

Let's see how we would do it:

paylands.storeSourceCard(
    true, //we want to validate the card against the bank.
    '3BF33A39-897E-4FBB-98CA-D1C0C55CA898' //service_uuid
)

5. Inform user of result

The previous step will trigger an event by which the user can be informed if the operation was successful or if there was an error.

If the event is error, the erroneous elements of the form will be indicated.
If the event is savedCard, it means that the card has been tokenized.

<script>
window.addEventListener('message', receiveMessage => {
    if (receiveMessage.data === 'error') {
        console.log('Card error');
    } else if (receiveMessage.data === 'savedCard') {
        console.log('Card saved successfully');
    }
}, false);
</script>

The savedCard event will contain the tokenized card data.

{
    "code": "200",
    "current_time": "2022-01-25T11:55:05+0200",
    "customer": {
        "external_id": "1239111NBC"
    },
    "source": {
        "object": "CARD",
        "uuid": "33SISMS-C254-4783-386C-603058EISAC25",
        "type": "C",
        "token": "elsellsSrfa2ercf119283BanScrIcana2f4be9acfMISUS188",
        "brand": "VISA",
        "country": 724,
        "holder": "UNKNOWN",
        "bin": 454881,
        "last4": "0004",
        "expire_month": "01",
        "expire_year": "22",
        "additional": null,
        "bank": "SERVIRED, SOCIEDAD ESPANOLA DE MEDIOS DE PAGO, S.A.",
        "prepaid": "",
        "validation_date": null
    }
}

6. Receiving card data on the server

If there is a need to receive the savedCard notification on the server, it is possible to do so by indicating the server URL to notify using the setURLPost method.

paylands.setURLPost(
    'URL_NOTIFICATION' // URL of your server that Paylands will notify to
)

The notification sent will have the same structure as the savedCard event receives:

{
    "code": "200",
    "current_time": "2022-01-25T11:55:05+0200",
    "customer": {
        "external_id": "1239111NBC"
    },
    "source": {
        "object": "CARD",
        "uuid": "33SISMS-C254-4783-386C-603058EISAC25",
        "type": "C",
        "token": "elsellsSrfa2ercf119283BanScrIcana2f4be9acfMISUS188",
        "brand": "VISA",
        "country": 724,
        "holder": "UNKNOWN",
        "bin": 454881,
        "last4": "0004",
        "expire_month": "01",
        "expire_year": "22",
        "additional": null,
        "bank": "SERVIRED, SOCIEDAD ESPANOLA DE MEDIOS DE PAGO, S.A.",
        "prepaid": "",
        "validation_date": null
    }
}

note

Receiving the notification on the server is completely optional. If your web/app does not require it, you can skip this step.

Methods

All the public methods available in the paylands global variable are listed below:

setMode: used when sandbox testing is in progress. The value to be passed as parameter is "sandbox". If this method is not used, it is assumed that the calls are made in production.
initializate: this is the main method, which will load the card form. The first parameter must be the token obtained when create user. The second parameter is the DOM element in which the form will be inserted.
setTemplate: this method specifies the form template to be displayed. It receives only one parameter, the UUID of the template.
validate: at any time this method can be executed to get the current status of the card data. The triggered event is validation.
setAdditional: this method assigns a description to the card.
setURLPost: if you need the card saving to send a background notification to the server, you can use this method to specify the URL to which the tokenized card data will be sent.
storeSourceCard: this method is used to store the card in Paylands. First the entered data is validated and depending on whether there is an error or not, the error or validation event will be fired respectively. This validation only validates the format of the data entered. If you need to check that the card has funds, that it is not blocked, etc., this method supports two parameters: the first is a boolean value set to true to indicate that you need to validate the card against the bank. The second parameter is the service_uuid included with the API credentials. The validation consists of a 0€ charge on the user's card to verify that the card is valid.
setFocus: this method can be used to set the cursor on the required input:
- If no parameter is specified, the focus will be set on the first empty INPUT.
- If the ID of any INPUT is specified, the focus will be set on this one.

Events

The following are the events that are triggered by the SDK to be handled by the client web/app:

paylandsLoaded: this event is fired when the SDK has been loaded and the paylands variable is available for use.
initiated: This event is triggered when the card form has been loaded.
validation: This event is triggered when the validate method is executed.
- If validated with all fields empty:
  .
- If all fields are correct:
error: This event will contain which fields have incorrect data.
savedCard: This event returns the tokenized card.

Integration​

1. Load the SDK library in your web or app.​

2. Create the client user to which the card will be assigned​

3. Display the form​

4. Save the card​

5. Inform user of result​

6. Receiving card data on the server​

Methods​

Events​