Get States by Country

About this guide

This page explains how to get a list of states for the countries in Latin America using EBANX.js. This is a helpful tool to ensure you send data in the standard format and avoid denied transactions due to invalid state codes.

If you are not integrated with EBANX Direct API yet, please take a look in 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:

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

How it works

To get the list of states for a given country using EBANX.js, follow the steps below:

1. 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.79.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',

   });

2. Create an object with the country code

   Create an object with with the following field:

   const options = {

   country: 'br',

   };

   The available countries are:

   Country	Country Code
   Argentina	ar
   Brazil	br
   Chile	cl
   Mexico	mx
   Peru	pe

3. Get the list of countries

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

   EBANX.referenceData

   .states(options)

   .get()

   .then((statesList) => {

   // use the statesList object to fullfil your payment

   })

   .catch((error) => {

   // handle any errors that can happen

   });

   EBANX.referenceData.states returns a Promise object, so, make sure you handle the asynchrounous call properly by using a callback function. A successful authentication response contains the following fields:

   //The statesList object created in the previous step will have the following fields:

   {

   "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"

   }

   ]

   }

Live sample

Here's a quick sample of how you can use EBANX.js to get a state list:

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.