openapi: 3.0.1
info:
  title: Belvo API
  description: >-
    The Belvo API is a RESTful open-finance API for Latin America. It lets you
    connect to bank, fiscal, and employment institutions across Mexico, Brazil,
    and Colombia through Links, then retrieve accounts, balances, transactions,
    owners, incomes, and recurring expenses. The Payments (Brazil) surface
    initiates account-to-account payments over Pix and the Open Finance network.
    All requests use HTTP Basic authentication with your Secret Key ID as the
    username and Secret Key Password as the password.
  termsOfService: https://belvo.com/terms-and-conditions/
  contact:
    name: Belvo Support
    email: support@belvo.com
    url: https://developers.belvo.com
  version: '1.0'
servers:
  - url: https://api.belvo.com
    description: Production
  - url: https://sandbox.belvo.com
    description: Sandbox
security:
  - basicAuth: []
tags:
  - name: Links
    description: Manage the credential connections to institutions.
  - name: Accounts
    description: Bank accounts held inside a Link.
  - name: Transactions
    description: Detailed transaction history for accounts in a Link.
  - name: Balances
    description: Point-in-time balances for checking and savings accounts.
  - name: Owners
    description: Identity of the Link owner.
  - name: Incomes
    description: Income insights derived from account activity.
  - name: Recurring Expenses
    description: Regular subscription and utility payments.
  - name: Institutions
    description: Institutions Belvo can connect to.
  - name: Payments (Brazil)
    description: Pix / Open Finance payment initiation in Brazil.
  - name: Webhooks
    description: Asynchronous event notifications.
paths:
  /api/links/:
    get:
      operationId: listLinks
      tags:
        - Links
      summary: List all Links
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of Links.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedLinks'
    post:
      operationId: registerLink
      tags:
        - Links
      summary: Register a new Link
      description: >-
        Register a Link by providing the institution and the end-user
        credentials. Use access_mode single for a one-time pull or recurrent
        to keep data refreshed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkRequest'
      responses:
        '201':
          description: The Link was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          $ref: '#/components/responses/Error'
  /api/links/{id}/:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: detailLink
      tags:
        - Links
      summary: Get a Link's details
      responses:
        '200':
          description: The requested Link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
    patch:
      operationId: patchLink
      tags:
        - Links
      summary: Complete or update a Link request
      description: Send a token or OTP to complete a multi-factor Link request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkPatchRequest'
      responses:
        '200':
          description: The updated Link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
    delete:
      operationId: deleteLink
      tags:
        - Links
      summary: Delete a Link
      responses:
        '204':
          description: The Link was deleted.
  /api/accounts/:
    get:
      operationId: listAccounts
      tags:
        - Accounts
      summary: List all accounts
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAccounts'
    post:
      operationId: retrieveAccounts
      tags:
        - Accounts
      summary: Retrieve accounts for a Link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveRequest'
      responses:
        '200':
          description: The accounts found for the Link.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '201':
          description: The accounts were retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
  /api/accounts/{id}/:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: detailAccount
      tags:
        - Accounts
      summary: Get an account's details
      responses:
        '200':
          description: The requested account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
    delete:
      operationId: deleteAccount
      tags:
        - Accounts
      summary: Delete an account
      responses:
        '204':
          description: The account was deleted.
  /api/transactions/:
    get:
      operationId: listTransactions
      tags:
        - Transactions
      summary: List all transactions
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
        - name: link
          in: query
          schema:
            type: string
            format: uuid
        - name: account
          in: query
          schema:
            type: string
        - name: value_date__gte
          in: query
          schema:
            type: string
            format: date
        - name: value_date__lte
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: A paginated list of transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTransactions'
    post:
      operationId: retrieveTransactions
      tags:
        - Transactions
      summary: Retrieve transactions for a Link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveTransactionsRequest'
      responses:
        '200':
          description: The transactions found for the Link.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
        '201':
          description: The transactions were retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
  /api/transactions/{id}/:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: detailTransaction
      tags:
        - Transactions
      summary: Get a transaction's details
      responses:
        '200':
          description: The requested transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
  /api/balances/:
    get:
      operationId: listBalances
      tags:
        - Balances
      summary: List all balances
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of balances.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedBalances'
    post:
      operationId: retrieveBalances
      tags:
        - Balances
      summary: Retrieve balances for a Link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveBalancesRequest'
      responses:
        '200':
          description: The balances found for the Link.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Balance'
        '201':
          description: The balances were retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Balance'
  /api/owners/:
    get:
      operationId: listOwners
      tags:
        - Owners
      summary: List all owners
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of owners.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedOwners'
    post:
      operationId: retrieveOwners
      tags:
        - Owners
      summary: Retrieve owners for a Link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveRequest'
      responses:
        '200':
          description: The owners found for the Link.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Owner'
        '201':
          description: The owners were retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Owner'
  /api/incomes/:
    get:
      operationId: listIncomes
      tags:
        - Incomes
      summary: List all incomes
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of income records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedIncomes'
    post:
      operationId: retrieveIncomes
      tags:
        - Incomes
      summary: Retrieve incomes for a Link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveRequest'
      responses:
        '200':
          description: The income insights found for the Link.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Income'
        '201':
          description: The income insights were retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Income'
  /api/recurring-expenses/:
    get:
      operationId: listRecurringExpenses
      tags:
        - Recurring Expenses
      summary: List all recurring expenses
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of recurring expense records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRecurringExpenses'
    post:
      operationId: retrieveRecurringExpenses
      tags:
        - Recurring Expenses
      summary: Retrieve recurring expenses for a Link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveRequest'
      responses:
        '200':
          description: The recurring expenses found for the Link.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecurringExpense'
        '201':
          description: The recurring expenses were retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecurringExpense'
  /api/institutions/:
    get:
      operationId: listInstitutions
      tags:
        - Institutions
      summary: List all institutions
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of institutions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedInstitutions'
  /api/institutions/{id}/:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: detailInstitution
      tags:
        - Institutions
      summary: Get an institution's details
      responses:
        '200':
          description: The requested institution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Institution'
  /api/webhooks/:
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List all webhooks
      responses:
        '200':
          description: A list of registered webhook endpoints.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create a webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
      responses:
        '201':
          description: The webhook was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
  /api/webhooks/{id}/:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: detailWebhook
      tags:
        - Webhooks
      summary: Get a webhook's details
      responses:
        '200':
          description: The requested webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete a webhook
      responses:
        '204':
          description: The webhook was deleted.
  /payments/br/payment-intents/:
    get:
      operationId: listPaymentIntents
      tags:
        - Payments (Brazil)
      summary: List all payment intents
      responses:
        '200':
          description: A paginated list of payment intents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPaymentIntents'
    post:
      operationId: createPaymentIntent
      tags:
        - Payments (Brazil)
      summary: Create a payment intent
      description: >-
        Create a payment intent capturing the amount, description, provider,
        and beneficiary required to process a Pix payment over the Open Finance
        Network.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: The payment intent was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentIntent'
  /payments/br/payment-intents/{id}/:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: detailPaymentIntent
      tags:
        - Payments (Brazil)
      summary: Get a payment intent's details
      responses:
        '200':
          description: The requested payment intent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentIntent'
  /payments/br/customers/:
    get:
      operationId: listCustomers
      tags:
        - Payments (Brazil)
      summary: List all customers
      responses:
        '200':
          description: A paginated list of customers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCustomers'
    post:
      operationId: createCustomer
      tags:
        - Payments (Brazil)
      summary: Create a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        '201':
          description: The customer was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
  /payments/br/payment-institutions/:
    get:
      operationId: listPaymentInstitutions
      tags:
        - Payments (Brazil)
      summary: List all payment institutions
      responses:
        '200':
          description: A list of institutions available for payments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentInstitution'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication using your Secret Key ID as the username and
        your Secret Key Password as the password.
  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: string
        format: uuid
    PageSize:
      name: page_size
      in: query
      description: Number of items per page (max 1000).
      schema:
        type: integer
        default: 100
        maximum: 1000
    Page:
      name: page
      in: query
      description: The page number of results to return.
      schema:
        type: integer
        default: 1
  responses:
    Error:
      description: An error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Pagination:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
    RetrieveRequest:
      type: object
      required:
        - link
      properties:
        link:
          type: string
          format: uuid
          description: The Link UUID to retrieve data for.
        save_data:
          type: boolean
          default: true
    RetrieveTransactionsRequest:
      allOf:
        - $ref: '#/components/schemas/RetrieveRequest'
        - type: object
          required:
            - date_from
          properties:
            date_from:
              type: string
              format: date
            date_to:
              type: string
              format: date
            account:
              type: string
    RetrieveBalancesRequest:
      allOf:
        - $ref: '#/components/schemas/RetrieveRequest'
        - type: object
          required:
            - date_from
          properties:
            date_from:
              type: string
              format: date
            date_to:
              type: string
              format: date
    LinkRequest:
      type: object
      required:
        - institution
        - username
        - password
      properties:
        institution:
          type: string
          example: erebor_mx_retail
        username:
          type: string
        password:
          type: string
        access_mode:
          type: string
          enum:
            - single
            - recurrent
          default: single
        external_id:
          type: string
        username_type:
          type: string
    LinkPatchRequest:
      type: object
      required:
        - id
        - token
      properties:
        id:
          type: string
          format: uuid
        token:
          type: string
        link:
          type: string
          format: uuid
    Link:
      type: object
      properties:
        id:
          type: string
          format: uuid
        institution:
          type: string
        access_mode:
          type: string
          enum:
            - single
            - recurrent
        status:
          type: string
          enum:
            - valid
            - invalid
            - unconfirmed
            - token_required
        created_at:
          type: string
          format: date-time
        external_id:
          type: string
          nullable: true
        institution_user_id:
          type: string
          nullable: true
        last_accessed_at:
          type: string
          format: date-time
          nullable: true
    Account:
      type: object
      properties:
        id:
          type: string
          format: uuid
        link:
          type: string
          format: uuid
        institution:
          type: object
          properties:
            name:
              type: string
            type:
              type: string
        category:
          type: string
          example: CHECKING_ACCOUNT
        type:
          type: string
        name:
          type: string
        number:
          type: string
        currency:
          type: string
          example: MXN
        balance:
          type: object
          properties:
            current:
              type: number
            available:
              type: number
        created_at:
          type: string
          format: date-time
    Transaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
        account:
          $ref: '#/components/schemas/Account'
        amount:
          type: number
        currency:
          type: string
        description:
          type: string
        value_date:
          type: string
          format: date
        accounting_date:
          type: string
          format: date
        type:
          type: string
          enum:
            - INFLOW
            - OUTFLOW
        status:
          type: string
          enum:
            - PROCESSED
            - PENDING
            - UNCATEGORIZED
        category:
          type: string
          nullable: true
        merchant:
          type: object
          nullable: true
          properties:
            name:
              type: string
            logo:
              type: string
        created_at:
          type: string
          format: date-time
    Balance:
      type: object
      properties:
        id:
          type: string
          format: uuid
        account:
          $ref: '#/components/schemas/Account'
        value_date:
          type: string
          format: date
        current_balance:
          type: number
        currency:
          type: string
        collected_at:
          type: string
          format: date-time
    Owner:
      type: object
      properties:
        id:
          type: string
          format: uuid
        link:
          type: string
          format: uuid
        display_name:
          type: string
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone_number:
          type: string
          nullable: true
        address:
          type: string
          nullable: true
        document_id:
          type: object
          nullable: true
          properties:
            document_type:
              type: string
            document_number:
              type: string
        collected_at:
          type: string
          format: date-time
    Income:
      type: object
      properties:
        id:
          type: string
          format: uuid
        account:
          $ref: '#/components/schemas/Account'
        currency:
          type: string
        income_summary:
          type: object
          properties:
            monthly_average:
              type: number
            number_of_income_streams:
              type: integer
            number_of_income_transactions:
              type: integer
            regular_income:
              type: boolean
        collected_at:
          type: string
          format: date-time
    RecurringExpense:
      type: object
      properties:
        id:
          type: string
          format: uuid
        account:
          $ref: '#/components/schemas/Account'
        name:
          type: string
        category:
          type: string
        frequency:
          type: string
          enum:
            - WEEKLY
            - BIMONTHLY
            - MONTHLY
            - BIWEEKLY
            - QUARTERLY
            - SEMESTRALLY
            - YEARLY
        average_transaction_amount:
          type: number
        currency:
          type: string
        transactions:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              amount:
                type: number
              value_date:
                type: string
                format: date
        collected_at:
          type: string
          format: date-time
    Institution:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
          enum:
            - bank
            - fiscal
            - employment
        website:
          type: string
          nullable: true
        display_name:
          type: string
        country_codes:
          type: array
          items:
            type: string
        primary_color:
          type: string
        logo:
          type: string
          nullable: true
        resources:
          type: array
          items:
            type: string
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
        authorization_header:
          type: string
          nullable: true
        enabled:
          type: boolean
        created_at:
          type: string
          format: date-time
    WebhookRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
        authorization_header:
          type: string
    PaymentIntentRequest:
      type: object
      required:
        - amount
        - description
        - provider
      properties:
        amount:
          type: string
          example: '100.00'
        description:
          type: string
        provider:
          type: string
          example: pix
        customer:
          type: string
          format: uuid
        beneficiary:
          type: object
          properties:
            name:
              type: string
            account:
              type: object
              properties:
                institution:
                  type: string
                number:
                  type: string
                type:
                  type: string
        allowed_payment_method_types:
          type: array
          items:
            type: string
    PaymentIntent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: string
        currency:
          type: string
          example: BRL
        description:
          type: string
        status:
          type: string
          enum:
            - REQUIRES_ACTION
            - PROCESSING
            - SUCCEEDED
            - CANCELLED
            - FAILED
        provider:
          type: string
        next_action:
          type: object
          nullable: true
          properties:
            type:
              type: string
            redirect_url:
              type: string
        created_at:
          type: string
          format: date-time
    Customer:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          nullable: true
        identifier:
          type: object
          properties:
            type:
              type: string
              example: CPF
            number:
              type: string
        created_at:
          type: string
          format: date-time
    CustomerRequest:
      type: object
      required:
        - name
        - identifier
      properties:
        name:
          type: string
        email:
          type: string
        identifier:
          type: object
          required:
            - type
            - number
          properties:
            type:
              type: string
              example: CPF
            number:
              type: string
    PaymentInstitution:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        display_name:
          type: string
        status:
          type: string
        logo:
          type: string
          nullable: true
    Error:
      type: array
      items:
        type: object
        properties:
          request_id:
            type: string
          message:
            type: string
          code:
            type: string
    PaginatedLinks:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Link'
    PaginatedAccounts:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Account'
    PaginatedTransactions:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Transaction'
    PaginatedBalances:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Balance'
    PaginatedOwners:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Owner'
    PaginatedIncomes:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Income'
    PaginatedRecurringExpenses:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/RecurringExpense'
    PaginatedInstitutions:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Institution'
    PaginatedPaymentIntents:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/PaymentIntent'
    PaginatedCustomers:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Customer'