# List all payment institutions

List all available payment institutions.

Endpoint: GET /payments/br/institutions/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

  - `page_size` (integer)
    Indicates how many results to return per page. By default we return 100 results per page.

ℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).
    Example: 100

  - `name` (string)
    Return an institution with this Belvo-designated name.

Note:

This filter supports both full and partial search queries, with a minimum of three characters required.

For example, searching for itau may match the following values:

  - itau_unibanco_retail
  - itau_unibanco_business
  - itau_retail
  - itau_business
  - superdigital_retail
  - superdigital_business
    Example: "itau"

  - `institution_type` (string)
    Return results only for this institution type. Can be either INDIVIDUAL or BUSINESS.
    Enum: "INDIVIDUAL", "BUSINESS"

  - `id__in` (array)
    Return information for these institution ids.
    Example: ["6b3dea0f-be29-49d1-aabe-1a6d588642e6"]

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of results in your Belvo account.
    Example: 130

  - `next` (string,null)
    The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

In our documentation example, we use {endpoint} as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, accounts or owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908&page=2"

  - `previous` (string,null)
    The URL to the previous page of results. If there is no previous page, the
value is null.

  - `results` (array)
    Array of institution objects.

  - `results.id` (string, required)
    Belvo's unique ID to reference the institution.
    Example: "bbaceead-7b96-46d8-9354-38dec9707004"

  - `results.code` (string)
    The ISPB code of the institution.
    Example: "12345678"

  - `results.active` (boolean, required)
    Indicates whether this institution is available for use or not.
    Example: true

  - `results.institution_type` (string)
    The type of institution. Can be either BUSINESS or INDIVIDUAL.
    Enum: "BUSINESS", "INDIVIDUAL"

  - `results.name` (string, required)
    The name of the institution, as designated by Belvo.
    Example: "wakanda_national"

  - `results.display_name` (string, required)
    The customer-facing name of the institution.
    Example: "Wakanda National Bank"

  - `results.legal_entity_name` (string,null, required)
    The name of the legal entity of the institution, as registered with the relevant regulatory authority. Only applicable for 🇧🇷 Brazil OFPI.
    Example: "Wakanda Bank, National Association"

  - `results.website` (string, required)
    The URL of the institution's website.
    Example: "https://www.wakandanational.com"

  - `results.logo` (string, required)
    The URL of the institution's logo.
    Example: "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_logo.svg"

  - `results.icon_logo` (string, required)
    The URL of the institution's icon logo.
    Example: "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_icon_logo.svg"

  - `results.text_logo` (string, required)
    The URL of the institution's text logo.
    Example: "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_text_logo.svg"

  - `results.primary_color` (string, required)
    The primary color on the institution's website.
    Example: "#fdbc24"

  - `results.country` (string, required)
    The country that the institution is located in. For Brazil, this is always set to BRA.
    Example: "BRA"

  - `results.form_fields` (array,null, required)
    This field is not applicable for OFPI and will return an empty array.
    Example: []

  - `results.sort_priority` (integer, required)
    Number that represents the order in which the institution should be displayed in an application, with 1 being the highest.
    Example: 1

  - `results.description` (string,null, required)
    A brief description of the insitution.
    Example: "Simple, transparent and secure: Wakanda Bank is the leading financial technology company in Latin America."

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For not_found errors, the description is:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"