Get States by Country

The EBANX Get States by Country feature allows you to dynamically retrieve a list of states or provinces for a given country, simplifying the checkout process for your customers. This feature ensures that the list of states is always up-to-date and tailored to the specific country the customer is selecting, making your forms more intuitive and localized.

Features

1. Improved user experience - By automatically populating the state dropdown based on the selected country, you reduce errors and improve the accuracy of the data your customers provide, leading to fewer failed transactions or address mismatches.
2. Seamless integration - The API can be easily integrated into your existing checkout or registration forms, ensuring that the correct state or province list is shown for each country without requiring manual updates.
3. Localized checkout - Supporting country-specific state/province listings makes the checkout process feel more localized, which can increase trust and conversion rates among international customers.
4. Real-time data - Since the data is fetched directly from the EBANX API, you always have the most current state/province information for each supported country, ensuring consistency and accuracy in your forms.

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 get the list of states for a given country using EBANX.js, follow the steps below:

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 object using country code

   Create an object with the country code.

   const options = {
     country: 'br',
   };

   The available countries are:

   Country	Country Code
   Argentina	ar
   Brazil	br
   Chile	cl
   Costa Rica	cr
   Dominican Republic	do
   Egypt	eg
   Guatemala	gt
   India	in
   Kenya	ke
   Mexico	mx
   Panama	pa
   Peru	pe
   Paraguay	py
   South Africa	za
   El Salvador	sv
   Uruguay	uy

3. Request list of states

   Call the EBANX.referenceData.states function using the object created in the previous step.

   EBANX.referenceData
     .states(options)
     .get()
     .then((statesList) => {
       // use statesList to fullfil payment
     })
     .catch((error) => {
       // handle errors
     });

4. Response

   The following object is returned as a Promise.

   Example -> Brazil states list

   // statesList
   {
       "quantity": 27,
       "stateList": [
           {
               "stateCode": "AC",
               "stateName": "Acre"
           },
           {
               "stateCode": "AL",
               "stateName": "Alagoas"
           },
           {
               "stateCode": "AP",
               "stateName": "Amapá"
           },
           {
               "stateCode": "AM",
               "stateName": "Amazonas"
           },
           {
               "stateCode": "BA",
               "stateName": "Bahia"
           },
           {
               "stateCode": "CE",
               "stateName": "Ceará"
           },
           {
               "stateCode": "DF",
               "stateName": "Distrito Federal"
           },
           {
               "stateCode": "ES",
               "stateName": "Espírito Santo"
           },
           {
               "stateCode": "GO",
               "stateName": "Goiás"
           },
           {
               "stateCode": "MA",
               "stateName": "Maranhão"
           },
           {
               "stateCode": "MT",
               "stateName": "Mato Grosso"
           },
           {
               "stateCode": "MS",
               "stateName": "Mato Grosso do Sul"
           },
           {
               "stateCode": "MG",
               "stateName": "Minas Gerais"
           },
           {
               "stateCode": "PA",
               "stateName": "Pará"
           },
           {
               "stateCode": "PB",
               "stateName": "Paraíba"
           },
           {
               "stateCode": "PR",
               "stateName": "Paraná"
           },
           {
               "stateCode": "PE",
               "stateName": "Pernambuco"
           },
           {
               "stateCode": "PI",
               "stateName": "Piauí"
           },
           {
               "stateCode": "RJ",
               "stateName": "Rio de Janeiro"
           },
           {
               "stateCode": "RN",
               "stateName": "Rio Grande do Norte"
           },
           {
               "stateCode": "RS",
               "stateName": "Rio Grande do Sul"
           },
           {
               "stateCode": "RO",
               "stateName": "Rondônia"
           },
           {
               "stateCode": "RR",
               "stateName": "Roraima"
           },
           {
               "stateCode": "SC",
               "stateName": "Santa Catarina"
           },
           {
               "stateCode": "SP",
               "stateName": "São Paulo"
           },
           {
               "stateCode": "SE",
               "stateName": "Sergipe"
           },
           {
               "stateCode": "TO",
               "stateName": "Tocantins"
           }
       ]
   }

5. Congratulations!

   You have succesfully integrated the Get states by country feature using EBANX.js.

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.