Drop-in

EBANX.js Drop-in is a pre-built, embeddable solution designed to help you integrate EBANX’s payment processing services into your website with minimal custom development. It provides you with a seamless, ready-made interface for handling payments, including credit cards, local payment methods, and other payment options supported by EBANX, without the need for complex custom implementation.

By using EBANX.js Drop-in, you can offer your customers a smooth and secure payment experience while reducing the time and effort needed to implement a custom solution.

Features

1. Easy integration - The Drop-in solution is designed to be quickly integrated into your website by adding a few lines of code, making it easier to get up and running with EBANX’s payment processing services.
2. Customizable UI - While it comes with a default design, it can be customized to match your website’s look and feel, allowing you to retain brand consistency.
3. Payment methods - The Drop-in supports various payment methods, including local options in Latin America (such as Boleto Bancário and PIX in Brazil), credit and debit cards, and other popular methods, providing flexibility for customers.
4. Security - EBANX.js Drop-in handles sensitive payment data securely by leveraging tokenization. It means the card or payment data is never stored directly on your servers, reducing the risk of breaches and simplifying PCI compliance.
5. Support for multiple payment flows - The Drop-in solution allows for different payment flows, such as direct payments, installments, and recurring payments.
6. Localized experience - With support for various languages, currencies, and payment methods tailored to specific countries, EBANX.js Drop-in enables a localized checkout experience for users, particularly in Latin American markets.

Requirements

• Credentials - Ensure you have your EBANX.js Public Integration Key, which can be found in your EBANX Dashboard. If you don't have it, complete the Merchant Signup Form.

Instructions

To render a Drop-in checkout component:

1. Install EBANX.js

   Insert script tag

   Add the following to your HTML.

   <script src="https://ebanx-js.ebanx.com/latest/dist/ebanx.min.js"></script>
   
   

   Initialize

   Include the following function in your JavaScript.

   EBANX.init({
     publicIntegrationKey: '{your_public_integration_key}',
     country: '{country_code_here}',
     mode: 'test',
   });
   
   

   Initialization parameters

   Field	Description
   publicIntegrationKey	Merchant's public integration key
   country	Customer country code. 2-digit String International standard - ISO 3166-1 alpha-2
   mode	test or production

2. Create an instance

   Instantiate EBANX Drop-in.

   const dropin = EBANX.dropin.create();

3. Mount your instance

   Parameters: Use the following parameters to mount an instance of Drop-in

   Parameter	Description	Default
   target	The HTML identifier where you want Drop-In to render the checkout. Typically, you’ll create an empty div with an assigned ID, which you’ll then pass as the target value for rendering.	N/A
   amount	The amount value of the payment. This value is used to calculate the installment values displayed.	N/A
   instalments	The maximum number of installments you want to offer for the payment. For instance, if you set it to 12, the customer will see options ranging from 1 to 12 installments.	1
   paymentMethods	An array of the payment methods you want to display. The available values are creditcard, debitcard, and _all.	_all
   lookAndFeel	Allows you to choose between a raw HTML format, where you can apply your own custom CSS, or a pre-designed checkout template provided by EBANX. Values: raw or vanilla. You can customize the EBANX vanilla option with a HEX color value.	vanilla
   values	An object to prefill any input fields. This is helpful if you already have customer data stored in a session and want to prefill fields, saving the customer from entering the information again.

   
   

   Example: Replace values with your own.

   dropin.mount('#dropin', {   // Target element ID
     amount: '100',
     values: valuesOption,     // Prefilled input fields
     lookAndFeel: {
       name: 'vanilla',
       primaryColor: '#4C70FC',
     },
     instalments: 12,
     paymentMethods: ['creditcard', 'debitcard'],
   });

4. Create HTML form-wrapper

   Once your checkout is rendered, listen for submit events. This can be achieved by wrapping your div in a form tag.

   <form id="dropin-form">
     <div id="dropin"></div>
   </form>

5. Form submissions

   Use the handleSubmit() function, passing the submit event object as an argument.

   const form = document.querySelector('#dropin-form');
   
   form.onsubmit = async (event) => {
     try {
       const paymentData = await dropin.handleSubmit(event); // payment information object
     } catch (error) {
       console.error(error);
     }
   };

6. Form response

   If successful, handleSubmit() will return an object containing the payment request details required to make a Direct API call:

   // Example response from handleSubmit.
   {
     "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"
   }

7. Send payment request to Direct API

   Use the payment request information from step 6 in your Direct API call.

   Only use the token in the creditcard object.

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_ebanx_integration_key",
       "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"
       }
     }'

8. Congratulations!

   You have successfully integrated the Drop-in feature.

Additional Information

1. Event listeners

Drop-In provides event listeners that allow you to customize your checkout experience.

• onReady - 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.

dropin.onReady(() => console.log('Checkout is being displayed.'));

• onInputChange - This event listener is triggered whenever the user makes a change in the checkout form. It accepts a callback function with a summary object as its parameter, which allows you to track input changes and validate each field. Below is an example where the name of the changed input field is logged in the browser console each time a change occurs:

// onInputChange

let lastFieldChanged = '';
dropin.onInputChange((summary) => { // Triggered every time a field is changed
  console.log(summary.reference);
  lastFieldChanged = summary.reference;
});

• onComplete - This event listener is triggered once all mandatory fields are filled out and data validations are successful. It’s useful when you need to perform an action only after ensuring the form is fully ready for submission. Here’s an example that logs “Completed!” in the console when the form is ready for submission:

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

• onCardComplete - This event listener is triggered when all mandatory fields for generating a card token are completed and pass validation. It’s helpful when you want to generate a token before other optional information is submitted. Below is an example that logs “Card Fields Completed!” in the console when the tokenization fields are fully filled out and validated:

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

2. Prefilled inputs when mounting

The mount function accepts an object that can include any customer data you’ve already stored. This allows you to prefill input fields and render the checkout with the provided information. 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 prefilled input fields
  lookAndFeel: {
    name: 'vanilla',
    primaryColor: '#4C70FC',
  },
  instalments: 12,
  paymentMethods: ['creditcard', 'debitcard'],
});

3. Customize with CSS

The following classes are available:

• .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

4. Customize with Javascript

Before render

For fields within an iframe, customize 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',
    },
  };
}

After render

To dynamically update the look and feel of iframe fields after they’ve been rendered, use the setLookAndFeelTheme() function and pass the new theme settings.

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',
    },
  };
}

Resources

Use the following resources when testing in Sandbox Mode. All transactions in sandbox mode simulate real transactions, but no actual funds are moved.

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.