Financial Institutions

GET https://api-sandbox.letpay.io/financialInstitution

This endpoint returns the catalog of financial institutions (banks) available for a given country, along with the code that identifies each one. That code is exactly the value you must send in the bank_code field of bank transfer payments and refunds.

Use it as the source of truth for bank codes: query it for the country you are going to transact in, present the returned institutions to the payer or beneficiary, and send back the code they selected.

Bank codes are specific to each country

The country query parameter is required and defines which catalog is returned. Each country has its own numbering scheme, so the same code means a different institution depending on the country. For example, 001 is Banco de Chile in Chile (country=CL), but Banco Central de Reserva in Peru (country=PE).

Always call this endpoint with the country of the transaction and send only a code returned by that call. Reusing a code from another country's catalog, or a code that is no longer listed, causes the transaction to be rejected.

Authorization

Header	Value
X-Auth-Token	MY_ACCESS_TOKEN

Request Description

Query Parameters

Parameter	Type	Required	Description
country	String	Yes	Country code in ISO 3166-1 alpha-2 (e.g. BR, MX, CO, CL, PE). Determines which institutions are returned.

Path Parameters

Parameter	Type	Required	Description
code	String	No	Appended to the path (/financialInstitution/{code}) to return a single institution instead of the full list. Useful to validate a bank_code before sending a transaction. Must still be combined with country.

Response Description

• financial_institutions (array/object): The institutions available for the requested country.
  • code (string): The institution identifier. This is the value to send as bank_code.
  • name (string): Short name of the institution.
  • full_name (string): Full registered name of the institution.
• refresh_token (string): Token to be used on the next request.

Where the Bank Code Is Used

Product	Country	Field	Reference
Payment (Bank Transfer)	Colombia	payment.bank_transfer.bank_code	Bank Transfer
Refund	Payment country	bank_code	Refunds

Do not hardcode bank codes

Institutions are added, merged, and removed over time. Query this endpoint to get the list that is currently valid for each country.

Example Request

200 - Success

Example Request

200 - Success

    curl --location 'https://api-sandbox.letpay.io/financialInstitution?country=BR' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN'

Example Response

Header

  Content-Type: application/json

Body

    {
      "financial_institutions": [
        {
          "code": "246",
          "name": "BCO ABC BRASIL S.A.",
          "full_name": "Banco ABC Brasil S.A."
        }
      ],
      "refresh_token": "MY_ACCESS_TOKEN"
    }

200 - Filtered By Code

Example Request

200 - Filtered By Code

  curl --location 'https://api-sandbox.letpay.io/financialInstitution/246?country=BR' \
  --header 'X-Auth-Token: MY_ACCESS_TOKEN'

Example Response

Header

  Content-Type: application/json

Body

    {
      "financial_institutions": [
        {
          "code": "246",
          "name": "BCO ABC BRASIL S.A.",
          "full_name": "Banco ABC Brasil S.A."
        }
      ],
      "refresh_token": "MY_ACCESS_TOKEN"
    }

401 - Unauthorized

Example Request

401 - Unauthorized

    curl --location 'https://api-sandbox.letpay.io/financialInstitution?country=BR' \
    --header 'X-Auth-Token: INVALID_ACCESS_TOKEN'

Example Response

Header

  Content-Type: application/json

Body

  {
    "timestamp": "2024-05-15T19:52:26.833+00:00",
    "status": 401,
    "error": "Unauthorized",
    "message": "Access Denied",
    "path": "/financialInstitution"
  }