# Javascript Library

## Introduction

We have created a library in Javascript that you can use to build your very own cashier directly into your site, giving you all the control just as if it would have been created by you.

The library's fonts and styles can be completely customizable according to your own website UI/UX, and we will take care of rendering the necessary payment methods and required fields for each payment method.

Once all the payments details have been collected, a POST will be made to your server with the details  you can use then to [create the deposit request using our Deposits API.](https://docs.pandablue.com/api-documentation/deposits-api)

In just a few steps, you will be able to start collecting payments through us by using our Javascript Library.

See first-hand the following example of a cashier created using the directa24.js library

{% embed url="<https://directa24.github.io/>" %}

![](https://1770394879-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M792I7hN0PzC-Sx95CP%2F-MLtbZOEy66-TZrD9coE%2F-MLtcraiW_zmDR-D-aiM%2Fimage.png?alt=media\&token=5dcf43cd-1881-49f9-a0a3-30738a7653a5)

![](https://1770394879-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M792I7hN0PzC-Sx95CP%2F-MLtbZOEy66-TZrD9coE%2F-MLtd35tVFRvON0YRXBo%2Fimage.png?alt=media\&token=6fe6245f-4a23-4d04-abc4-fc7a8b3ab464)

## Getting started

Follow the below steps to get the library working on your site:

1. Include the directa24.js library
2. Prepare the `directa24` object with your API Key
3. Include all the required values such as amount and country and the optional values such as currency, language, payer data and CSS/Javascript styles object
4. Initialize the directa24.js library to render the cashier on your site and allow the customer to complete the payment flow
5. Submit the form info collected to your server and send the payment request to our Deposits API

### Requirements

Before getting started, please consider the following requirements:

1. Your site must have HTTPS implemented in order for the library to work properly.
2. You will need to have a server listening to a POST (over HTTPS as well) with the payment data in order for you to send the request through our Deposits API.
3. You will need to register with us to get an API Key to authenticate yourself.

## 1. Including directa24.js

The first step is to include the Javascript Library onto your index.html file.

In order to do so, please add the following `<script>` tag to the HTML Header:

```markup
<head>
    <script src="https://connect-js.directa24.com/directa24.js"></script>
</head>
```

Note the Library must always be loaded directly from :

```markup
https://connect-js.directa24.com
```

For testing purposes you can use:&#x20;

```markup
https://connect-js-stg.directa24.com
```

{% hint style="success" %}
While adding or modifying features to the directa24.js library, please keep the browser's console open to see any error/message it can throw.
{% endhint %}

The API Keys between Production and STG environments are different.

## 2. Preparing the Pandablue object

Now that you have included the directa24.js library, a new object called `directa24` is created on the window.

The second step is to prepare your API Key and all the parameters that will be sent before rendering the form to the customer. To do so, instantiate the library as follows:

```javascript
let directa24Lib = directa24('EKiFOWiHnI', params);
```

The API Key can be retrieved from our Merchant Panel by going to Settings -> API Access -> Web Status Credentials -> API Key.

## 3. Including required parameters

Create an object named `params` with all the required and optional fields you want to send as follows:

```javascript
const params = {
    country: 'BR',
    amount: 100,
    currency: 'USD',
    lang: 'PT',
    url: 'https://directa24-js.com/deposit',
    payerData: {
        payerFirstName: 'FirstName',
        payerLastName: 'LastName',
        payerEmail: 'payerEmail@test.com'
    },
    disableInputDefaultValue: true
}
```

### Mandatory Parameters

| Parameter name | Format                    | Description                                                                                                                                                                                                     | Default |                                                          Validations                                                          |
| -------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: | :---------------------------------------------------------------------------------------------------------------------------: |
| `country`      | string (length: 2)        | Country code of the deposit in *ISO 3166-1 alpha-2 code* format                                                                                                                                                 |         |               [See country codes](https://docs.pandablue.com/specifications/countries-specifications#currencies)              |
| `amount`       | decimal (max decimals: 2) | Deposit amount in the currency specified                                                                                                                                                                        |         |                                                              > 0                                                              |
| `currency`     | string (length: 3)        | Currency code of the amount in *ISO 4217* format.  Must be USD or the country's local currency                                                                                                                  |         | [See currency codes](https://docs.pandablue.com/specifications/countries-specifications#countries-and-currencies). Upper case |
| `lang`         | string (length: 2)        | Language in which the deposit page will be rendered                                                                                                                                                             |   `EN`  |                                         Spanish, English or Portuguese: `[ES, EN, PT]`                                        |
| `url`          | string (max length: 2048) | Valid URL over HTTPS. It will be used to POST the form data collected to your server so you can send the payment request through our [Deposits API](https://docs.pandablue.com/api-documentation/deposits-api). |         |                                                          `HTTPS URL`                                                          |

### Optional Parameters

| Parameter name                | Format                   | Description                                                                                          | Default |                                                        Validations                                                        |
| ----------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------- | :-----: | :-----------------------------------------------------------------------------------------------------------------------: |
| `disableInputDefaultValue`    | boolean                  | Allow or disallow the customers to modify the parameters you send in the object payerData            | `false` |                                                      `[true, false]`                                                      |
| `styles`                      | Object                   | Override the default CSS styles with your own CSS/JavaScript Object                                  |         |                                                  [View details](#styles)                                                  |
| `payerData.payerFirstName`    | string (max length: 128) | Customer's first name                                                                                |         |                                               String of up to 128 characters                                              |
| `payerData.payerLastName`     | string (max length: 128) | Customer's last\_name                                                                                |         |                                               String of up to 128 characters                                              |
| `payerData.payerEmail`        | string (max length: 255) | Customer's document ID. Ensure it is correct and the user can't change it every time he/she deposits |         |                                                    Valid email address                                                    |
| `payerData.payerDocumentType` | string (max length: 10)  | Customer's document type                                                                             |         |         [document types validations](https://docs.pandablue.com/specifications/countries-specifications#documents)        |
| `payerData.payerDocument`     | string (max length: 30)  |                                                                                                      |         |            [document validations](https://docs.pandablue.com/specifications/countries-specifications#documents)           |
| `payerData.payerPhone`        | string (max length: 32)  | Valid customer's phone number                                                                        |         | [phone number validations](https://docs.pandablue.com/specifications/countries-specifications#mobile-numbers-validations) |
| `payerData.payerAddress`      | string (max length: 255) | Customer's address                                                                                   |         |                                               String of up to 255 characters                                              |
| `payerData.payerCity`         | string (max length: 128) | Customer's city                                                                                      |         |                                               String of up to 128 characters                                              |
| `payerData.payerState`        | string (max length: 3)   | Customer's state in [*ISO 3166-2 code* format](https://en.wikipedia.org/wiki/ISO_3166-2)             |         |                         Valid state code in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)                        |
| `payerData.payerZipcode`      | string (max length: 16)  | Customer's zip code                                                                                  |         |     [Zip code validations](https://docs.pandablue.com/specifications/countries-specifications#postal-code-validations)    |

{% hint style="info" %}
Even though those parameters are optional, we recommend you sending all the optional parameters you have already stored on your DB to avoid asking the customer for the same details multiple times.
{% endhint %}

### The object *STYLES*

The object `styles` allows you to override the default styles of the library. It has to be a CSS/Javascript object.&#x20;

To know more about CSS into a Javascript object, we recommend reading the following pages:

{% embed url="<https://www.w3schools.com/jsref/dom_obj_style.asp>" %}

{% embed url="<https://developer.mozilla.org/es/docs/Web/API/HTMLElement/style>" %}

To transform a CSS file to a Javascript Object, you may use the following tool:

{% embed url="<https://transform.tools/css-to-js>" %}

Apart from the CSS properties you can specify, you can also modify other components of the library by directly specifying the name of the property inside the object style as described in the following sections.

#### Font

To overwrite the font used by the library, you can specify the property `font` inside the object `styles`.

```javascript
const params ={
   ...
   "styles":{
      "font":{
         "fontFamily":"Epilogue"
      }
   }
}

```

Inside the `font` object you can modify any attribute, such as the color, weight, etc.

#### Container

The library is inside a `<div>` with the class `container` , you can modify or add styles to the div by adding the property `container` inside the object `styles`.

```javascript
const params ={
   ...
   "styles":{
      "container":{
         "backgroundColor":"blue"
      }
   }
}

```

Inside the `container` object you can modify any other attribute.

#### Spinner

In order to modify the style of the spinner loader that is shown when the form page is loading, you need to add the property `spinner` inside the object `styles`.

```javascript
const params ={
   ...
   "styles":{
      "spinner":{
         "borderTopColor":"green"
      }
   }
}

```

Inside the `spinner` object you can modify any other attribute.

#### Buttons

The library has two different buttons: "Continue" shown when choosing a payment method and to confirm the transaction and "Go Back", used to go the Payment Methods page again.

In order to modify the "Continue" button, you need to add the property `continueBtn` inside the object `styles` and  to modify the "Go Back" button use the property `backBtn`.

```javascript
const params ={
   ...
   "styles":{
      "continueBtn":{
         "backgroundColor":"green",
         ":hover":{
            "backgroundColor":"blue"
         }
      },
      "backBtn":{
         "color":"red",
         "border":"1px solid red"
      }
   }
}

```

Inside the buttons properties object you can modify any other attribute.

#### Grid View

The library has different properties you can use to modify the style of the Payment Methods Grid View:

* `gridItemBox` allows to customize the container of each payment method
* `gridItemCheckIcon` allows to customize how the payment method looks like when it was selected by the customer
* `gtidItemLabel` allows to customize the label of each payment method

```javascript
const params ={
   ...
   "styles":{
      "gridItemBox":{
         "width":"170px",
         "height":"170px",
         "backgroundColor":"red",
         ":hover":{
            "backgroundColor":"green"
         }
      },
      "gridItemCheckIcon":{
         "color":"green",
         "borderColor":"blue",
         "background":"yellow"
      },
      "gridItemLabel":{
         "color":"violet"
      }
   }
}

```

Inside the grids objects you can modify any other attribute.

#### Title

The library has two titles you can personalize:

* `stepsItems`  allows to change the style of all the titles
* `stepsItemsActive` allows to change the style of the active title

```javascript
const params ={
   ...
   "styles":{
      "stepsItems":{
         "color":"orange",
         "backgroundColor":"green"
      },
      "stepsItemActive":{
         "color":"violet",
         ":after":{
            "content":"''",
            "display":"block",
            "height":"3px",
            "position":"absolute",
            "left":0,
            "right":0,
            "bottom":0,
            "backgroundColor":"yellow"
         }
      }
   }
}

```

#### Inputs

In order to modify the input forms, you have the following properties available:

* `inputContainer`&#x20;
* `inputText`&#x20;
* `inputErrorLabel`&#x20;
* `inputErrorIcon`&#x20;

```javascript
const params ={
   ...
   "styles":{
      "inputErrorIcon":{
         "color":"red"
      }
   }
}

```

#### Selects

If you want to modify the selects that will be used to render the form and the select of the payment method you can modify the following properties:

* `inputSelect`&#x20;
* `inputSelectOption`&#x20;

```javascript
const params ={
   ...
   "inputSelect":{
      "background":"lightBlue",
      "&:hover":{
         "borderColor":"red"
      }
   },
   "inputSelectOption":{
      "background":"red",
      "&:hover":{
         "borderColor":"green"
      }
   }

}

```

## 4. Initialize directa24.js

As soon as you have all the required parameters, we will invoke the `init` function to create and render the payment page.

```markup
<script>
    const params = {
        amount: 100,
        currency: 'USD',
        lang: 'PT',
        payerData: {
            payerFirstName: 'FirstName',
            payerLastName: 'LastName',
            payerEmail: 'payerEmail@test.com'
        },
        url: 'https://directa24-js.com/deposit',
        country: 'BR',
        disableInputDefaultValue: true
    }
    let directa24Lib = directa24('EKiFOWiHnI', params);
    window.onload =  directa24Lib.init(document.getElementById('main'), 'grid', 'BL', true);
</script>

```

The `init` function is composed by the following parameters:

```javascript
public init(
   formId: HTMLElement,
   displayType: FIELD_TYPE,
   paymentMethod?: string,
   loadPaymentForm?: boolean
 ) 

```

### Parameters description

#### formId

Name of the HTML element where the library directa24.js has to render the payment page.

#### displayType

It specifies how the payment methods will be shown. It can either be in `COMBO` format or in `GRID` format. If an invalid value is sent, it defaults to GRID.

```javascript
export enum FIELD_TYPE {
 COMBO = 'combo',
 GRID = 'grid',
}

```

#### paymentMethod

The library allows you to specify the Payment Method. That way we won't ask the customer for the Payment Method again.

If the payment method is sent and it is invalid or you don't have it enabled, we will show the customer all the payment methods so they can choose one.

You can use the [Payment Methods API](https://docs.pandablue.com/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to determine which payment methods you have enabled. Also check the [Payment Methods](https://docs.pandablue.com/api-documentation/deposits-api/payment-methods#payment-methods) section for the codes, logos and more.

#### loadPaymentForm

The `loadPaymentForm` parameter, is an optional and boolean value `[true, false]` that specifies whether the payment method specified can or can't be changed by the customer.

If `true`, the user will be redirected straight to the page to complete the payment details. If `false`, the customer will be prompted to select a payment method, with the payment method specified pre-selected by default.

It not sent or an invalid value is sent, we will default to `false`.

## 5. Send the payment info to your server

Once the user has successfully went through the "payment method" selection page and the "Details" page and clicks on "Confirm", we will send to the url specified as part of the cashier invokation a POST in form-data with the details collected.

You will need to use those details to create a deposit request by using our [Deposits API to create the payment link.](https://docs.pandablue.com/api-documentation/deposits-api)

## Working Code Example

Find below a working code example:

{% embed url="<https://github.com/directa24/directa24.github.io>" %}
Directa24 GIT Repository - Example cashier with the Javascript library
{% endembed %}

As you can see, the directa24.js file is loaded directly from the header of the HTML file, the script tag contains the request to the library, and the payment form is rendered inside the `<div>` with id 'main'.

```markup
<!DOCTYPE html>
<html lang="en">
<head>

	<title>Directa24 Payment Form</title>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
        * {
            margin: 0px; 
            padding: 0px; 
        }

        body, html {
            height: 100%;
        }

        #main{
          width: 90%;
          margin-top: 25px;
        }

        .contact1 {
          width: 100%;
          min-height: 100%;
          text-align: center;
          background: #f1f2f7;

          display: -webkit-box;
          display: -webkit-flex;
          display: -moz-box;
          display: -ms-flexbox;
          display: flex;
          flex-direction: column;
          align-items: center;
        }
    </style>
    <link rel='shortcut icon' type='image/x-icon' href='https://merchants.directa24.com/favicon.ico'/>
	<link href="https://fonts.googleapis.com/css2?family=Epilogue:wght@300&display=swap" rel="stylesheet">
<!--===============================================================================================-->
	<script src="https://connect-js-stg.directa24.com/directa24.js"></script>
	
</head>
<body>

	<div class="contact1">
		<div style="width: 100%">
		  <img src="https://resources.directa24.com/misc/logo/directa-logo-crop.png" style="max-width: 200px;max-height: 100px;">
        </div>
        <div id='main'></div>
        <script>
            const params = {
                amount: 100,
                currency: 'USD',
                lang: 'PT',
                payerData: {
                    payerFirstName: 'FirstName',
                    payerLastName: 'LastName',
                    payerEmail: 'payerEmail@test.com'
                },
                url: 'https://directa24-js.com/deposit',
                country: 'BR',
                disableInputDefaultValue: true
            }
            let directa24Lib = directa24('EKiFOWiHnI', params);
            window.onload =  directa24Lib.init(document.getElementById('main'), 'grid');
        </script>
	</div>

</body>
</html>

```
