Version: current

Drop-In

About this guide

This page explains how to render a checkout generated by EBANX directly on your page. Drop-In is a solution that allows you to display all the necessary fields and language specific to the country you are targeting in Latin America. It also takes care of tokenizing card information, retrieving Device IDs and performing 3DS 2.0 authentication. Since Drop-In is rendered directly in your page, it is fully customizable, and you can taylor it to match your website's experience!

Drop-In makes it easy for you to integrate with our Direct API. If you are not familiar with EBANX Direct API yet, please take a look at this basic guide about it. Are you not sure if EBANX Direct API is the best option for your e-commerce? Please, talk with one of our integration specialists.

What you will need

Before starting your integration, please make sure that you have:

An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;

How it works

Submitting a Payment

To render a checkout page using Drop-In and submit a payment, follow the steps below:

Add EBANX.js to your webpage
Our client SDK enables you to securely collect payment information from your customers. Add the following script to your webpage:
<script type="text/javascript" src="https://ebanx-js.ebanx.com/v1.106.0/dist/ebanx.js"></script>
And initialize it with your Merchant's Configuration:
EBANX.init({
publicIntegrationKey: 'your_integration_key_goes_here',
country: 'br',
mode: 'test',
});
Initialize Drop-In
Call the EBANX.dropin.create function assigning it to a new constant.
const dropin = EBANX.dropin.create();
Once created, use the mountfunction to initialize Drop-In. This function takes the following parameters:
- target: The identifier in your HTML where you want Drop-In to render the checkout. Typically, you will create an empty div and give it an ID. It is this ID you will provide as the target value
- options: An object containing the following parameters you can use to taylor the checkout to your specific needs:
  - amount: The amount value of the payment. This value is used to calculate the instalment values displayed.
  - instalments: The max number of instalments you want to provide for that payment. For example, if you provide 12, it'll display options from 1 to 12 instalments. Default value: 1
  - paymentMethods: An array of the payment methods you want to display. The available values are creditcard,debitcard and _all. Default value: _all
  - lookAndFeel: This parameter allows you to choose between a raw HTML format, to which you can apply your own CSS, and a preformatted checkout designed by EBANX. The available values are raw and vanilla. Additionally, for the EBANX vanilla option, you can provide the HEX value of a color, to customize it yo your own brand. To do so, use the following format: {name: "vanilla", primaryColor?: string }. Default value: vanilla
  - values: This object allows you to pre-fill any input fields. This is very useful in case you already have some of your customer's data stored in a session and want to use it to save your customer some typing. Default value: {}
Here's an example of how you could use mount to create a checkout:
dropin.mount('#dropin', {
amount: '100',
values: valuesOption,
lookAndFeel: {
name: 'vanilla',
primaryColor: '#4C70FC',
},
instalments: 12,
paymentMethods: ['creditcard', 'debitcard'],
});
With that, you have a checkout rendered and ready to go!
Track form submits and handle the submit data
Now that your checkout is rendered, you will need to listen to submit events. You can do that by wrapping your <div id="dropin"></div> in a form HTML tag.
<form id="dropin-form">
<div id="dropin"></div>
</form>
Feel free to use any method you feel more comfortable to manipulate your HTML (jQuery, for example). In the example below, we use vanilla Javascript functions to manipulate the DOM.
When listening to submit events, you can use the handleSubmit function, passing the submit event object to it as a parameter.
const form = document.querySelector('#dropin-form');

form.onsubmit = async (event) => {
try {
const paymentData = await dropin.handleSubmit(event); //object that will store teh payment information
} catch (error) {
console.error(error);
}
};
If successful, handleSubmit will return an object with the payment request information you need to perform a Direct API call. Here's an example:
{
"name": "Test User",
"email": "customer+dropin@ebanx.com",
"phone_number": "999999999",
"document": "01234567890",
"country": "BR",
"zipcode": "80010010",
"state": "PR",
"city": "Curitiba",
"address": "Rua Marechal Deodoro",
"street_number": "630",
"street_complement": "26° Andar",
"creditcard": {
"bin": "411111",
"exp_date": "12/2050",
"last_four": "1111",
"token": "90d13f351cef86c2e48da8534df4f366977e41cd2b9ca6c6839002007a9350deac17368e51e3ad9c81aa4273b0d3212cf6fa7d862e2e0fb4660029972e65c240"
},
"instalments": 1,
"payment_type": "creditcard",
"payment_type_code": "visa",
"device_id": "6dbc8b90b7c6f8c7faaa391f50e5c76d",
"user_value_5": "ebanxjs-dropin"
}
Send the payment request to Direct API
Now that you have all the payment information you need. Simply add them to your API call, and you are all set!
Here's an example of a Direct API call. Note that only the token is provided to the creditcard object.
curl -X POST 'https://sandbox.ebanxpay.com/ws/direct' \
-d 'request_body={
"integration_key": "your_test_integration_key_here",
"operation": "request",
"payment": {
"amount_total": 100,
"currency_code": "BRL",
"merchant_payment_code": "3ad1f4096a2",
"name": "Test User",
"email": "customer+dropin@ebanx.com",
"phone_number": "999999999",
"document": "01234567890",
"country": "BR",
"zipcode": "80010010",
"state": "PR",
"city": "Curitiba",
"address": "Rua Marechal Deodoro",
"street_number": "630",
"street_complement": "26° Andar",
"creditcard": {
"token": "90d13f351cef86c2e48da8534df4f366977e41cd2b9ca6c6839002007a9350deac17368e51e3ad9c81aa4273b0d3212cf6fa7d862e2e0fb4660029972e65c240"
},
"instalments": 1,
"payment_type": "creditcard",
"payment_type_code": "visa",
"device_id": "6dbc8b90b7c6f8c7faaa391f50e5c76d",
"user_value_5": "ebanxjs-dropin"
}
}'

Event Listeners

Drop-In also provides event listeners which you can use to taylor your checkout experience. These event listeners are:

onReady: This event listener is triggered when Drop-In finishes rendering the form. This event can be used in cases where you want to perform an action only when you are sure that the form is being displayed. Here's an example where we console log a "Checkout ready!!" message only when Drop-In finishes rendering the form:

dropin.onReady(() => console.log('Checkout ready!!'));

onInputChange: This event listener is triggered every time the user performs any change in the checkout form. It accepts a callback function which has a summary object as parameter. You can use this function to track input changes and validation of each field in the checkout. Here's an example where the input field's name is displayed in the browser console every time it is changed:

let lastFieldChanged = '';
dropin.onInputChange((summary) => {
  //This event listener is triggered every time a field is changed

  console.log(summary.reference);
  lastFieldChanged = summary.reference;
});

onComplete: This event listener is triggered when all mandatory fields are filled in and all data validations have passed. This is useful for when you want to perform an action only after you are sure that the form is ready to be submitted. Here's an example where we console log a "Completed!" message only when the form is ready:

dropin.onComplete(() => console.log('Completed!'));

onCardComplete: This event listener is triggered when all mandatory fields for generating a card token are filled in and all data validations have passed. This is useful for when you want to generate a token before other pieces of information that are not mandatory for tokenization are fully submitted. Here's an example where we console log a "Completed!" message only when the fields required for tokenization are filled:

dropin.onCardComplete(() => console.log('Card Fields Completed!'));

Initializing Drop-In with pre-filled inputs

The mount function accepts an object that can contain customer data that you might have already stored. You can use this object to pre-fill any input fields and render the checkout with the information provided by this parameter. Here's an example:

const valuesOption = {
  // Object used to pre fill any information on the form
  billingAddressCity: 'Curitiba',
  billingAddressStreet: 'Rua Marechal Deodoro',
  billingAddressStreetNumber: '630',
  billingAddressState: 'PR',
  billingAddressZipcode: '80010010',
  billingAddressComplement: '26° Andar',
  customerName: 'Test User',
  customerDocument: '01234567890',
  customerEmail: 'customer+dropin@ebanx.com',
  customerPhoneNumber: '999999999',
  creditCardCvv: '123',
  creditCardDueDate: '12/2050',
  creditCardHolderName: 'Carlos Silva',
  creditCardNumber: '4111111111111111',
  debitCardCvv: '123',
  debitCardDueDate: '12/2050',
  debitCardHolderName: 'Carlos Silva',
  debitCardNumber: '4000000000010000',
  selectedInstalmentsNumber: '1',
  selectedPaymentType: 'creditcard',
};

const dropin = EBANX.dropin.create();
dropin.mount('#dropin', {
  amount: '100',
  values: valuesOption, //parameter used to add pre filled input fields
  lookAndFeel: {
    name: 'vanilla',
    primaryColor: '#4C70FC',
  },
  instalments: 12,
  paymentMethods: ['creditcard', 'debitcard'],
});

Customizing Drop-In with CSS and Javascript

Drop-In can be customized using traditional CSS for most of its fields. For that, the following HTML classes are available and can be referenced in your CSS:

ebanx-dropin--error
ebanx-dropin__personal-info
ebanx-dropin__billing-address
ebanx-dropin__payment-types
ebanx-dropin__field
ebanx-dropin__field__label
ebanx-dropin__field__label
ebanx-dropin__field--selector
ebanx-dropin__field--error
ebanx-dropin__field__error-message
ebanx-dropin__payment-type
ebanx-dropin__payment-type-selector
ebanx-dropin__payment-type-selector__label
ebanx-dropin__payment-type-selector__input

For fields that are inside an iframe, customization happens using Javascript through the theme object:

dropin.mount('#dropin', {
  amount: '100',
  values: getInitialValues(),
  lookAndFeel: {
    name: 'raw',
    theme: {
      secureField: { base: getBaseTheme() },
    },
  },
});

function getBaseTheme() {
  return {
    width: '100%',
    padding: '14px',
    border: '1px solid #AAA',
    borderRadius: '3px',
    outline: 'none',
    boxSizing: 'border-box',
    ':focus': {
      border: '1px solid #04646C',
      outline: '2px auto #04646C',
    },
    '::placeholder': {
      color: '#777',
    },
  };
}

And for updating the look and feel of iframe fields dynamically, after they've been rendered, use the setLookAndFeelTheme function passing on the new themes

dropin.setLookAndFeelTheme({
  secureField: {
    base: getBaseTheme(),
    invalid: getInvalidTheme(),
  },
});

function getBaseTheme() {
  return {
    width: '100%',
    padding: '14px',
    border: '1px solid #AAA',
    borderRadius: '3px',
    outline: 'none',
    boxSizing: 'border-box',
    ':focus': {
      border: '1px solid #04646C',
      outline: '2px auto #04646C',
    },
    '::placeholder': {
      color: '#777',
    },
  };
}

function getInvalidTheme() {
  return {
    border: '1px solid #fe807c',
    outline: '2px auto #fe807c',
    ':focus': {
      border: '1px solid #fe807c',
      outline: '2px auto #fe807c',
    },
  };
}

Live Sample

Here's a sample of a checkout being rendered using all the steps described in this guide and display the payment object on the screen after it is submitted:

info

Open your console to see the event listeners being triggered and displaying messages.

See the Pen by ferpa2012 (@ferpa2012) on CodePen.

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

If you’re not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
In case you’re already our partner please get in touch with our support team at integration@ebanx.com.

Drop-In#

About this guide#

What you will need#

How it works#

Submitting a Payment#

Add EBANX.js to your webpage

Initialize Drop-In

Track form submits and handle the submit data

Send the payment request to Direct API

Event Listeners#

Initializing Drop-In with pre-filled inputs#

Customizing Drop-In with CSS and Javascript#

Live Sample#

info

Getting help#

Drop-In

About this guide

What you will need

How it works

Submitting a Payment

Event Listeners

Initializing Drop-In with pre-filled inputs

Customizing Drop-In with CSS and Javascript

Live Sample

Getting help