Country States Codes Endpoint

Learn how to use the Country States Codes Endpoint to retrieve the list of States ISO codes in each country

Country States Codes Endpoint

GET https://api-stg.onekeypayments.com/v3/states?country={ISO_CODE}

This API allows you to retrieve the list of ISO codes and the names of the states available in each country, allowing you to dynamically retrieve those on your front-end.

Query Parameters

Name	Type	Description
country	string	Country ISO code

Headers

Name	Type	Description
Authorization	string	Authorization Header. Format: "Bearer your_read_only_key"

200 Bank list successfully retrieved

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

401 Invalid credentials error

Introduction

This endpoint is used to retrieve and display to your customer the list of States available on their country. In case we add or remove a State, this endpoint will reflect those updates real-time and, therefore, it is a good idea to constantly check this endpoint for the list of banks.

Once the user selected their State by its name (For example on a dropdown), you need to send its code to us in the payer.address.state field of the deposits requests.

The endpoint is read only and so it uses a read only API Key. It can even be used from the front-end without major security concerns.

Bank Codes Request

Request Example

// URL
GET: https://api-stg.onekeypayments.com/v3/states?country=BR

// HEADERS
Authorization: Bearer EKiFOWiHnI 

Request Fields

Type	Field	Format	Description
Query Param	country	String (length: 2)	Country ISO code
Header	Authorization	String	Bearer Token Authentication. It is a concatenation of the word "Bearer " and your Read Only API Key.

Bank Codes Response

Response Example

Brazil

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

Colombia

Response fields

Field	Format	Description
iso	String (length between 1 and 3)	State code in ISO 3166-2 format. It is the value you must send in the payer.address.state field of the Deposits requests
name	String	Name of the State