Belvo Payment Institutions (Brazil) API

openapi: 3.2.0
info:
  title: Belvo API Docs Payment Institutions (Brazil) API
  version: 1.223.0
  description: '# Introduction


    Reach new audiences and convert more users by easily and safely connecting to their financial data, understanding their behavior and enabling instant payments with open finance. Through our API, you can access:


    ## Available Information and Payment Methods


    Belvo is an open banking API for Latin America that allows companies to access banking and fiscal information in a secure as well as agile way. Through our API, you can access:


    - Banking Information in Brazil

    - Employment Information in Brazil

    - Employment Information in Mexico

    - Fiscal Information in Mexico

    - Fiscal Information in Chile


    You can also use our API to make payments in:


    - Brazil

    - Mexico


    ## Data Dictionaries


    If you woud like the response documentation in Excel or CSV form, please download them from our public GitHub Reposiitory: Belvo Open Finance Data Dictionaries. Our EXCEL and CSV files are additionally localized into Spanish and Portuguese (Brazil). ## Environments


    We currently offer two environments: sandbox and production. ### Sandbox


    Available for:


    - 🟢 Aggregation and Enrichment

    - ⚪️ Payment Initiation


    Use our Sandbox environment to build your integration. We offer dummy data that mimics that of real-world use cases, which means you can test out all the endpoints, use the widget, and implement webhooks - just as you would with real-world data! All you need to get started with the Sandbox environment is to get your API keys. We really recommend that you start creating your integration in this environment. ### Production


    Available for:


    - 🟢 Aggregation and Enrichment

    - 🟢 Payment Initiation


    After you have tested your integration in the Sandbox environment and are ready to go live, you''ll need to request access to our Production environment. After you request access, our Sales Team will get in contact with you to schedule a meeting just to ensure your needs are met, and then you''ll just need to go through a certification process with one of our engineers to make sure that your integration is running optimally. To prepare for the certification meeting, just follow our Integration checklist. Once your integration is certified, all you''ll need to do is:


    - [ ] Request Production API keys (and change your Sandbox API keys in the code to these new ones). - [ ] Change the base URL that you make requests to from `sandbox.belvo.com` to `api.belvo.com`. - [ ] If you''re using webhooks, make sure to set a Production URL for your webhooks. ## Response codes


    We use the following HTTP status code in the response depending on the

    success or failure:


    | Status Code | Description |

    |-----------|-------|

    | `200` | ✅ **Success** - The content is available in the response body. |

    | `201` | ✅ **Success** - The content was created successfully on Belvo. |

    | `204` | ✅ **Success** - No content to return. |

    | `400` | ❌ **Bad Request Error** - Request returned an error, detail in the content.|

    | `401` | ❌ **Unauthorized** - The Belvo credentials provided are not valid.|

    | `404` | ❌ **Not Found** - The resource you try to access cannot be found.|

    | `405` | ❌ **Method Not Allowed** - The HTTP method you are using is not accepted for this resource.|

    | `408` | ❌ **Request Timeout** - The request timed out and was terminated by the server.|

    | `428` | ❌ **MFA Token Required** - MFA token was required by the institution to connect. |

    | `500` | ❌ **Internal Server Error** - The detail of the error is available in the response body.|


    ## Error handling


    Belvo API errors are returned in JSON format. For example, an error might look like this:


    ```json

    [

    {

    "request_id": "a6e1c493d7a29d91aed4338e6fcf077d",

    "message": "This field is required.",

    "code": "required",

    "field": "link"

    }

    ]

    ```


    Typically, an error response will have the following parameters:


    - `request_id`: a unique ID for the request, you should share it with the Belvo support team for investigations. - `message`: human-readable description of the error. - `code`: a unique code for the error.'
  contact:
    name: Need help?
    url: https://developers.belvo.com
    email: support@belvo.com
  x-logo:
    url: https://files.readme.io/5111448-belvo-for-developers.svg
    altText: Belvo Logo
servers:
- url: https://sandbox.belvo.com
  description: Sandbox
security:
- basicAuth: []
tags:
- name: Payment Institutions (Brazil)
  description: A **payment institution** is an entity that Belvo can access information from. You can see a complete list of institutions available for payments by making a List request to this endpoint.
paths:
  /payments/br/institutions/:
    get:
      tags:
      - Payment Institutions (Brazil)
      operationId: ListPaymentInstitutionsBrazil
      summary: List all payment institutions
      description: List all available payment institutions.
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/name__payments'
      - $ref: '#/components/parameters/institution_type'
      - $ref: '#/components/parameters/institution_id__in'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/common_pagination_properties'
                - properties:
                    results:
                      type: array
                      description: Array of institution objects.
                      items:
                        $ref: '#/components/schemas/paymentInstitutionBR'
        '401':
          $ref: '#/components/responses/401_unauthorized_error'
        '403':
          $ref: '#/components/responses/403_access_denied_error'
        '404':
          $ref: '#/components/responses/404_not_found_error'
        '408':
          $ref: '#/components/responses/408_request_timeout_error'
        '500':
          $ref: '#/components/responses/500_unexpected_error'
components:
  parameters:
    institution_id__in:
      name: id__in
      in: query
      description: Return information for these institution `id`s.
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          format: uuid
          example: 6b3dea0f-be29-49d1-aabe-1a6d588642e6
    institution_type:
      name: institution_type
      in: query
      description: Return results only for this institution type. Can be either `INDIVIDUAL` or `BUSINESS`.
      schema:
        type: string
        enum:
        - INDIVIDUAL
        - BUSINESS
        example: INDIVIDUAL
    page:
      name: page
      in: query
      description: A page number within the paginated result set.
      schema:
        type: integer
        format: int32
        minimum: 1
        example: 1
    name__payments:
      name: name
      in: query
      description: "Return an institution with this Belvo-designated name.\n\n**Note:**\n\nThis filter supports both full and partial search queries, with a minimum of three characters required.\n\nFor example, searching for `itau` may match the following values:\n\n  - `itau_unibanco_retail`\n  - `itau_unibanco_business`\n  - `itau_retail`\n  - `itau_business`\n  - `superdigital_retail`\n  - `superdigital_business`\n"
      schema:
        type: string
        minLength: 3
        example: itau
    page_size:
      name: page_size
      in: query
      description: '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).

        '
      schema:
        type: integer
        format: int32
        default: 100
        minimum: 1
        maximum: 1000
        example: 100
  responses:
    408_request_timeout_error:
      description: Request Timeout
      content:
        application/json:
          schema:
            type: array
            title: Request Timeout
            description: "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n  \n"
            items:
              $ref: '#/components/schemas/RequestTimeoutError'
    403_access_denied_error:
      description: Access to Belvo API denied
      content:
        application/json:
          schema:
            type: array
            description: 'This error occurs when you try to access Belvo''s resource without the correct permissions.

              '
            items:
              $ref: '#/components/schemas/AccessToResourceDenied'
    401_unauthorized_error:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: array
            items:
              anyOf:
              - $ref: '#/components/schemas/UnauthorizedError'
              - $ref: '#/components/schemas/ConsentWithoutAccountsError'
    404_not_found_error:
      description: Not Found Error
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/NotFoundError'
    500_unexpected_error:
      description: Unexpected Error
      content:
        application/json:
          schema:
            type: array
            title: Unexpected Error
            description: "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n  \n"
            items:
              $ref: '#/components/schemas/UnexpectedError'
  schemas:
    request_id:
      type: string
      pattern: '[a-f0-9]{32}'
      description: '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
    ConsentWithoutAccountsError:
      type: object
      title: Consent Without Accounts
      description: 'This error occurs when your user has removed accounts associated with the consent they provided. For example, when your user first generated their consent, they had a checking and a loan account at the institution but has closed those accounts since then.

        '
      properties:
        code:
          type: string
          description: 'A unique error code (`consent_without_accounts`) that allows you to classify and handle the error programmatically.



            ℹ️ Check our DevPortal for more information on how to handle <a href="https://developers.belvo.com/docs/belvo-api-errors#401-consent_without_accounts" target="_blank">401 consent_without_accounts errors</a>.

            '
          example: consent_without_accounts
        message:
          type: string
          description: "A short description of the error. \n\n\nFor `invalid` errors relating to `fetch_resources`, the description is:\n  \n  - `The institution only supports the following resources: (comma-separated list of supported resources)`.\n"
          example: 'The institution only supports the following resources: EMPLOYMENT_RECORDS, OWNERS'
        request_id:
          $ref: '#/components/schemas/request_id'
    UnauthorizedError:
      type: object
      title: Unauthorized Error
      description: 'This error occurs when you try to make an API call using incorrect Belvo API credentials (either your secret key or secret password, or both, are incorrect).

        '
      properties:
        code:
          type: string
          description: 'A unique error code (`authentication_failed`) that allows you to classify and handle the error programmatically.



            ℹ️ Check our DevPortal for more information on how to handle <a href="https://developers.belvo.com/docs/belvo-api-errors#401-authentication_failed" target="_blank">401 authentication_failed errors</a>.

            '
          example: authentication_failed
        message:
          type: string
          description: "A short description of the error. \n\n\nFor `authentication_failed` errors, the description is:\n\n  - `Invalid Secret Keys`.\n"
          example: Invalid Secret Keys
        request_id:
          $ref: '#/components/schemas/request_id'
    paymentInstitutionBR:
      type: object
      required:
      - id
      - active
      - name
      - display_name
      - legal_entity_name
      - website
      - logo
      - icon_logo
      - text_logo
      - primary_color
      - country
      - form_fields
      - sort_priority
      - description
      properties:
        id:
          type: string
          format: uuid
          description: Belvo's unique ID to reference the institution.
          example: bbaceead-7b96-46d8-9354-38dec9707004
        code:
          type: string
          description: The ISPB code of the institution.
          example: '12345678'
        active:
          type: boolean
          description: Indicates whether this institution is available for use or not.
          example: true
        institution_type:
          type: string
          enum:
          - BUSINESS
          - INDIVIDUAL
          description: The type of institution. Can be either `BUSINESS` or `INDIVIDUAL`.
          example: INDIVIDUAL
        name:
          type: string
          description: The name of the institution, as designated by Belvo.
          example: wakanda_national
        display_name:
          type: string
          description: The customer-facing name of the institution.
          example: Wakanda National Bank
        legal_entity_name:
          type:
          - string
          - 'null'
          description: '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
        website:
          type: string
          description: The URL of the institution's website.
          example: https://www.wakandanational.com
        logo:
          type: string
          description: The URL of the institution's logo.
          example: https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_logo.svg
        icon_logo:
          type: string
          description: The URL of the institution's icon logo.
          example: https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_icon_logo.svg
        text_logo:
          type: string
          description: The URL of the institution's text logo.
          example: https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_text_logo.svg
        primary_color:
          type: string
          description: The primary color on the institution's website.
          example: '#fdbc24'
        country:
          type: string
          maxLength: 3
          description: 'The country that the institution is located in. For Brazil, this is always set to `BRA`.

            '
          example: BRA
        form_fields:
          type:
          - array
          - 'null'
          description: This field is not applicable for OFPI and will return an empty array.
          example: []
        sort_priority:
          type: integer
          format: int32
          description: 'Number that represents the order in which the institution should be displayed in an application, with `1` being the highest.

            '
          example: 1
        description:
          type:
          - string
          - 'null'
          description: A brief description of the insitution.
          example: 'Simple, transparent and secure: Wakanda Bank is the leading financial technology company in Latin America.'
    AccessToResourceDenied:
      type: object
      title: Access to Belvo API denied
      description: 'This error occurs when you try to access Belvo''s resource without the correct permissions.

        '
      properties:
        code:
          type: string
          description: '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 <a href="https://developers.belvo.com/docs/belvo-api-errors#403-access_to_resource_denied" target="_blank">403 access_to_resource_denied</a>.

            '
          example: access_to_resource_denied
        message:
          type: string
          description: "A short description of the error. \n\n\nFor `access_to_resource_denied` errors, the description is:\n  \n  - `You don't have access to this resource.`.\n"
          example: You don't have access to this resource.
        request_id:
          $ref: '#/components/schemas/request_id'
    UnexpectedError:
      type: object
      title: Unexpected Error
      description: 'This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.

        '
      properties:
        code:
          type: string
          description: '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 <a href="https://developers.belvo.com/docs/belvo-api-errors#500-unexpected_error" target="_blank">500 unexpected_error errors</a>.

            '
          example: unexpected_error
        message:
          type: string
          description: "A short description of the error. \n\n\nFor `unexpected_error` errors, the description is:\n  \n  - `Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution`.\n"
          example: Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution
        request_id:
          $ref: '#/components/schemas/request_id'
    NotFoundError:
      type: object
      title: Not Found
      properties:
        code:
          type: string
          description: 'A unique error code (`not_found`) that allows you to classify and handle the error programmatically.

            '
          example: not_found
        message:
          type: string
          description: "A short description of the error.\n\n\nFor `not_found` errors, the description is:\n\n  - `Not found`\n"
          example: Not found
        request_id:
          $ref: '#/components/schemas/request_id'
    RequestTimeoutError:
      type: object
      title: Request Timeout
      description: 'Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.

        '
      properties:
        code:
          type: string
          description: '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 <a href="https://developers.belvo.com/docs/belvo-api-errors#408-request_timeout" target="_blank">408 request_timeout errors</a>.

            '
          example: request_timeout
        message:
          type: string
          description: "A short description of the error. \n\n\nFor `request_timeout` errors, the description is:\n  \n  - `The request timed out, you can retry asking for less data by changing your query parameters`.\n"
          example: The request timed out, you can retry asking for less data by changing your query parameters
        request_id:
          $ref: '#/components/schemas/request_id'
    common_pagination_properties:
      type: object
      properties:
        count:
          type: integer
          format: int32
          description: The total number of results in your Belvo account.
          example: 130
        next:
          type:
          - string
          - 'null'
          format: uri
          description: '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:
          type:
          - string
          - 'null'
          format: uri
          description: 'The URL to the previous page of results. If there is no previous page, the

            value is `null`.

            '
          example: null
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: "Belvo employs **basic authentication** using your secret keys (You can find your API secret keys in your Belvo Dashboard, under the **Developers** section).\n\n\nTo authenticate, you need to use your API `secretId` as the `username` and your API `secretPassword` as the `password`. These credentials need to be **Base64 encoded** and included in the `Authorization` header of your HTTP requests. For example:\n\n\n```shell\ncurl -X GET https://sandbox.belvo.com/api/ \\\n  -H \"Authorization: Basic $(echo -n 'YOUR_SECRET_ID:YOUR_SECRET_PASSWORD' | base64)\"\n```\n\nReplace `YOUR_SECRET_ID` and `YOUR_SECRET_PASSWORD` with your actual credentials. **Never expose your credentials in client-side code or public repositories**."
x-tagGroups:
- name: Core Resources
  tags:
  - Institutions
  - Links
  - Widget Access Token
  - Consents
- name: Open Finance Data Aggregation (Brazil)
  tags:
  - Owners
  - Accounts
  - Balances
  - Exchanges
  - Transactions
  - Bills
  - Investments Brazil
  - Investment Transactions Brazil
- name: Employments Brazil
  tags:
  - Employments Brazil
- name: Employment Records Mexico
  tags:
  - Employment Records Mexico
  - Current Employments Mexico
- name: Fiscal Mexico
  tags:
  - Invoices
  - Tax compliance status
  - Tax returns
  - Tax retentions
  - Tax status
  - Financial Statements
- name: Fiscal Chile
  tags:
  - Invoices Chile
  - Tax Status Chile
  - Debt Reports Chile
- name: Enrichment API
  tags:
  - Incomes
  - Recurring Expenses
  - Risk Insights
  - Employment Metrics
- name: Payment Initiation (Brazil)
  tags:
  - Payment Initiation introduction (Brazil)
  - Payment Institutions (Brazil)
  - Customers (Brazil)
  - Bank Accounts (Brazil)
  - Payment Authorizations (Brazil)
  - Charges (Brazil)
  - Payment Intents (Brazil)
  - Biometric payments Widget Access Token (Brazil)
  - Enrollments (Brazil)
  - Payment Transactions (Brazil)
x-provenance:
  method: harvested
  publisher: Belvo
  source: https://developers.belvo.com/_bundle/apis/BelvoOpenApiSpec.json?download
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)