Integration through JavaScript SDK (Vanilla)

Our JavaScript SDK (framework-free) allows you to integrate the checkout into your website easily and securely. This SDK handles rendering the interface and managing all communication with Paylands to process transactions.

This library is responsible for rendering the user interface and handling the necessary communication with the Paylands platform to execute any type of transaction smoothly.

In order to use the SDK it will be necessary to have previously generated a server-side order in Paylands. This order must contain the uuid of the previously created checkout. For more information on how to generate an order with checkout, see section Integration via API.

1. Include the SDK on your website

Load the client-side script:

<script async src="https://api.paylands.com/assets/checkout/paylands-checkout-sdk.js"></script>

And initialize the SDK providing the token obtained in the payment order generation:

const paylandsCheckout = await PaylandsCheckout.create({token: '9fdade323e7...'});

This will return an instance of PaylandsCheckout that can be used to interact with the SDK.

2. SDK Functions

Redirect

To redirect the user to the checkout, simply call the redirect function.

await paylandsCheckout.redirect();

Rendering

To render the checkout in a specific container, call the render function.

await paylandsCheckout.render('renderContainer');

Request
container	Required	ID of the container the checkout will be rendered on

Note: To complete the payment, don't forget step 3.

Card form

To render a customizable card form in a specific container, call the card function.

await paylandsCheckout.card({
    container: 'renderContainer',
    form: { ... },
    customization: { ... }
});

Request
container	Required	ID of the container the form will be rendered on
form (Object)	Required	Configuration Form
customization (Object)	Required	Customization Form

form (Object)
holderLabel	Optional	Input label for card holder
holderError	Optional	Error to show if value is incorrect
panLabel	Optional	Input label for card Pan
panError	Optional	Error to show if value is incorrect
expiryLabel	Optional	Input label for expiration date card
expiryError	Optional	Error to show if value is incorrect
cvvLabel	Optional	Input label for CVV card
cvvError	Optional	Error to show if value is incorrect

customization (Object)
font	Optional	Text font
textColor	Optional	Text color
backgroundColor	Optional	Background color
errorColor	Optional	Error text color
borderColor	Optional	Inputs color border
borderRadius	Optional	Inputs radius border
padding	Optional	Padding
inputTextSize	Optional	Input text size
labelTextSize	Optional	Label text size
iconSize	Optional	Icon size
iconColor	Optional	Icon color

How to validate the form?

The form has its own validation, the result of which will be sent to the main website in the card_valid event.

window.addEventListener('message', event => {
    if (event.data.card_valid === true) {
        console.log('El formulario es válido');
    }
    if (event.data.card_valid === false) {
        console.log('El formulario contiene errores');
    }
});

How to submit?

Send a pay event with the value card.

button.addEventListener("click", () => window.postMessage({ pay: "card" }));

Note: To complete the payment, don't forget step 3.

Google Pay button

To render a Google Pay button in a specific container, call the google_pay function. The merchant needs to have Google Pay enabled in their Paylands account. For more information, see the Google Pay section.

await paylandsCheckout.google_pay('renderContainer');

Request
container	Required	ID of the container on which the Google Pay button will be rendered

Note: To complete the payment, don't forget step 3.

Apple Pay button

To render an Apple Pay button in a specific container, call the apple_pay function. The merchant needs to have Apple Pay enabled in their Paylands account. For more information, see the Apple Pay section.

await paylandsCheckout.apple_pay('renderContainer');

Request
container	Required	ID of the container on which the Apple Pay button will be rendered

Note: To complete the payment, don't forget step 3.

PayPal button

To render a PayPal button in a specific container, call the payPal function. It is necessary that the merchant has PayPal enabled in his Paylands account.

await paylandsCheckout.payPal({
    container: 'renderContainer',
    form: { ... },
    customization: { ... }
});

Request
container	Required	ID of the container on which the PayPal button will be rendered
form (Object)	Required	Button configuration
customization (Object)	Required	Button customization

form (Object)
prefilledAddress	Optional	User address
prefilledCountry	Optional	User country

customization (Object)
layout	Optional	https://developer.paypal.com/sdk/js/reference/#link-layout
color	Optional	https://developer.paypal.com/sdk/js/reference/#link-color
label	Optional	https://developer.paypal.com/sdk/js/reference/#link-label
borderRadius	Optional	https://developer.paypal.com/sdk/js/reference/#link-borderradius

Note: To complete the payment, don't forget step 3.

Alternative Payment Methods

To render an alternative payment method in a specific container, call the <PAYMENT METHOD NAME> function. Currently, the available alternative payment methods are:

• bizum
• boleto
• cofidis
• efecty
• loterica
• mbway
• multibanco
• pago_facil
• payshop
• pse
• safetypay
• pix
• picpay
• mach
• khipu
• klap
• servipag
• flowpay
• spei
• webpay

await paylandsCheckout.bizum({
    container: '#renderContainer',
    form { ... },
    customization: { ... }
});

Note: To know which form fields are required for a specific payment method, check its section in the documentation.

Request
container	Required	ID of the container where the form will be rendered
form (Object)	Required	Form configuration
customization (Object)	Required	Form customization

form (Object)
nameLabel	Optional	Input label for name
nameError	Optional	Error to show if the value is incorrect
lastNameLabel	Optional	Input label for last name
lastNameError	Optional	Error to show if the value is incorrect
emailLabel	Optional	Input label for email
emailError	Optional	Error to show if the value is incorrect
prefilledName	Optional	User's name if known
prefilledLastName	Optional	User's last name if known
prefilledEmail	Optional	User's email if known
prefixLabel	Optional	Input label for phone prefix
prefixError	Optional	Error to show if the value is incorrect
phoneLabel	Optional	Input label for phone number
phoneError	Optional	Error to show if the value is incorrect
prefilledPrefix	Optional	User's prefix if known
prefilledPhone	Optional	User's phone number if known
prefilledDocumentIdentificationNumber	Optional	User's personal identification number if known
documentIdentificationNumberLabel	Optional	Input label for personal identification number
documentIdentificationNumberError	Optional	Error to show if the value is incorrect
addressLabel	Optional	Input label for address
addressError	Optional	Error to show if the value is incorrect
zipCodeLabel	Optional	Input label for zip code
zipCodeError	Optional	Error to show if the value is incorrect
cityLabel	Optional	Input label for city
cityError	Optional	Error to show if the value is incorrect
countryLabel	Optional	Input label for country
countryError	Optional	Error to show if the value is incorrect
prefilledAddress	Optional	User's address if known
prefilledZipCode	Optional	User's zip code if known
prefilledCity	Optional	User's city if known
prefilledCountry	Optional	User's country if known

customization (Object)
font	Optional	Text font
primaryColor	Optional	Button color
textColor	Optional	Text color
backgroundColor	Optional	Background color
errorColor	Optional	Error text color
borderColor	Optional	Inputs border color
borderRadius	Optional	Inputs border radius
padding	Optional	Padding
inputTextSize	Optional	Input text size
labelTextSize	Optional	Label text size
iconSize	Optional	Icon size
iconColor	Optional	Icon color
buttonText	Optional	Button content
buttonTextSize	Optional	Button text size

How to validate the form?

The form has its own validation, which communicates through the <PAYMENT METHOD>_valid event.

3. The customer completes the payment

Once the user completes the payment, an event will be sent on the page itself with one of the following values to be handled by the merchant:

Response
redirect	URL to redirect the user with the payment result OK/KO
render	HTML content to render on the page. This happens because user intervention is required again, usually to complete the 3DS. Minimum recomended size is 500x600.
error	HTML content with the error occurred.

window.addEventListener('message', event => {
    if (event.data.redirect) {
        window.location.href = event.data.redirect;
    } else if (event.data.render) {
        const container = document.getElementById('renderContainer');
        if (container) {
          container.innerHTML = event.data.render;
        }
        const submitButton = document.getElementById('submitBTN');
        if (submitButton) {
          submitButton.click()
        } else {
          const form = document.querySelector('form')
          if (form) {
            form.submit()
          }
        }
    } else if (event.data.error) {
        const container = document.getElementById('renderContainer');
        if (container) {
          container.innerHTML = event.data.error;
        }
    }

Note: This is not necessary if you have used the redirect function of the SDK. In this case, the SDK will redirect the client to the corresponding redirect URL according to the result of the operation:

• If the payment has been made successfully it is redirected to the url specified in the url_ok field of the order.
• In any other case it redirects to the url specified in the url_ko field of the order.

4. Example usage

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Checkout Example via SDK</title>
</head>
<body>
  <div id="payment-container" style="max-width: 400px;"></div>
  <script>
    const script = document.createElement('script');
    script.src = 'https://api.paylands.com/assets/checkout/paylands-checkout-sdk.js';
    script.onload = async () => {
      const paylandsCheckout = await PaylandsCheckout.create({
        token: ORDER_TOKEN, // Replace with the order token generated in your backend
        environment: 'SANDBOX', // Change to 'PRODUCTION' for the production environment
      });

      await paylandsCheckout.render('payment-container'); // Check the documentation for more payment options

      window.addEventListener('message', event => {
        if (event.data.redirect) {
            window.location.href = event.data.redirect;
        } else if (event.data.render) {
            const container = document.getElementById('renderContainer');
            if (container) {
              container.innerHTML = event.data.render;
            }
            const submitButton = document.getElementById('submitBTN');
            if (submitButton) {
              submitButton.click()
            } else {
              const form = document.querySelector('form')
              if (form) {
                form.submit()
              }
            }
        } else if (event.data.error) {
            const container = document.getElementById('renderContainer');
            if (container) {
              container.innerHTML = event.data.error;
            }
      });
    };
    script.onerror = () => {
      console.error('Error loading the Paylands SDK');
    };
    document.head.appendChild(script);
  </script>
</body>
</html>