# Register a new bank account

Register a new bank account from which to send or request funds.

Endpoint: POST /payments/br/bank-accounts/
Version: 1.223.0
Security: basicAuth

## Header parameters:

  - `X-Belvo-API-Resource-Version` (string)
    Header indicating which version of the Payment API you want to use. Currently this is only applicable for Bank Accounts, Customers, and Payment Authorizations in Brazil. In the case that you are using our Payment Authorizations product, then you must send through this header set to Payments-BR.V2.

{% admonition type="warning" name="Coming Soon" %}
  This version is in Coming Soon. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.
{% /admonition %}
    Enum: "Payments-BR.V2"

## Request fields (application/json):

  - `body` (object) — one of:
    - V2 - Bank Account:
      - `holder` (object, required)
        Details of the account holder.
      - `holder.name` (string, required)
        The full name or business name of the account holder.
        Example: "Frangos Enlatados"
      - `holder.identifier` (string, required)
        The CPF (11 digits) or CNPJ (14 digits) of the account holder.
        Example: "12345678901122"
      - `details` (object, required)
        Details of the bank account.
      - `details.account_type` (string, required)
        The type of bank account. Can be either:
  - CHECKINGS (also known as Conta Corrente in Brazil)
  - SAVINGS (also known as Conta Poupança in Brazil)
  - PAYMENTS (also known as Conta de Pagamento Instantâneo or Conta de Pagamento in Brazil)
        Enum: "CHECKINGS", "SAVINGS", "PAYMENTS"
      - `details.agency` (string, required)
        The agency (branch number) of the institution where the account was created.
        Example: "0444"
      - `details.institution` (string, required)
        The Belvo ID of the financial institution.
        Example: "f512d996-583a-4a91-8b5b-eba2e103b068"
      - `details.number` (string, required)
        The bank account number.

{% admonition type="info" name="Valid Account Number characters" %}
  You can only send through numbers (^[0-9]+$) in the string. For example, "457220" is a valid bank account number, while "45722-0" is invalid as it contains a hyphen (-).
{% /admonition %}
        Example: "457220"
      - `external_id` (string)
        An additional unique identifier for the resource for internal purposes.

{% admonition type="success" name="Highly Recommended" %}
  We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `metadata` (object)
        Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the payment intent.

{% admonition type="info" name="Metadata Limitations" %}
  You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.
{% /admonition %}
        Example: {"internal_reference_id":"GGq73487w2"}
    - V1 - OFPI Business:
      - `institution` (string, required)
        Belvo's unique ID for the institution that the bank account is created in.
        Example: "f512d996-583a-4a91-8b5b-eba2e103b068"
      - `external_id` (string)
        An additional unique identifier for the resource for internal purposes.

{% admonition type="success" name="Highly Recommended" %}
  We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `holder` (object, required)
        Details regarding the business bank account holder.
      - `holder.type` (string, required)
        The type of bank account. For business bank accounts, this must be set to BUSINESS.
        Enum: "BUSINESS"
      - `holder.information` (object, required)
        Additional information about the bank account holder required in order to create the account for OFPI.
      - `holder.information.name` (string, required)
        The full name of the business
        Example: "Gustavo Veloso Entertainment Universe"
      - `holder.information.identifier_type` (string, required)
        The customer's ID document type. For businesses in Brazil, this must be set to CNPJ.
        Enum: "CNPJ"
      - `holder.information.identifier` (string, required)
        The CNPJ document number.
        Example: "00000000000191"
      - `details` (object, required)
        Information regarding the bank account.
      - `details.account_type` (string, required)
        The type of bank account. Can be either:

  - CHECKINGS (also known as Conta Corrente in Brazil)
  - SAVINGS (also known as Conta Poupança in Brazil)
  - SALARY (also known as Conta Salário in Brazil)
  - PAYMENTS (also known as Conta de Pagamento Instantâneo or Conta de Pagamento in Brazil)
        Enum: "CHECKINGS", "SAVINGS", "SALARY", "PAYMENTS"
      - `details.agency` (string, required)
        The agency (branch number) of the institution where the account was created.
        Example: "0444"
      - `details.number` (string, required)
        The bank account number.

> 📘 Valid account number characters
>
> You can only send through numbers (^[0-9]+$) in the string. For example, "457220" is a valid bank account number, while "45722-0" is invalid as it contains a hyphen (-).
        Example: "457220"
    - V1 - OFPI Individual:
      - `institution` (string, required)
        Belvo's unique ID for the institution that the bank account is created in.
        Example: "f512d996-583a-4a91-8b5b-eba2e103b068"
      - `external_id` (string)
        An additional unique identifier for the resource for internal purposes.

{% admonition type="success" name="Highly Recommended" %}
  We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `holder` (object, required)
        Details regarding the individual bank account holder.
      - `holder.type` (string, required)
        The type of bank account. For individuals, this must be set to INDIVIDUAL.
        Enum: "INDIVIDUAL"
      - `holder.information` (object, required)
        Additional information about the bank account holder required in order to create the account for OFPI.
      - `holder.information.first_name` (string, required)
        The bank account holder's first name.
        Example: "Gustavo"
      - `holder.information.last_name` (string, required)
        The bank account holder's last name.
        Example: "Veloso"
      - `holder.information.identifier_type` (string, required)
        The customer's ID document type. For individuals in Brazil, this must be set to CPF.
        Enum: "CPF"
      - `holder.information.identifier` (string, required)
        The document number of the customer's ID.
        Example: "00000000191"
      - `details` (object, required)
        Information regarding the bank account.
      - `details.account_type` (string, required)
        The type of bank account. Can be either:

  - CHECKINGS (also known as Conta Corrente in Brazil)
  - SAVINGS (also known as Conta Poupança in Brazil)
  - SALARY (also known as Conta Salário in Brazil)
  - PAYMENTS (also known as Conta de Pagamento Instantâneo or Conta de Pagamento in Brazil)
        Enum: same as `details.account_type` in "V1 - OFPI Business" (4 values)
      - `details.agency` (string, required)
        The agency (branch number) of the institution where the account was created.
        Example: "0444"
      - `details.number` (string, required)
        The bank account number.

> 📘 Valid account number characters
>
> You can only send through numbers (^[0-9]+$) in the string. For example, "457220" is a valid bank account number, while "45722-0" is invalid as it contains a hyphen (-).
        Example: "457220"

## Response 201 fields (application/json):

  - `body` (object) — one of:
    - V2 - Bank Account:
      - `id` (string, required)
        Belvo's unique identifier for the current item.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `created_at` (string, required)
        The ISO-8601 timestamp of when the data point was created in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `updated_at` (string, required)
        The ISO-8601 timestamp of when the data point was updated in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `active` (boolean, required)
        Indicates if the bank account is active (and can be used to receive funds).
        Example: true
      - `holder` (object, required)
        Details of the account holder.
      - `holder.name` (string, required)
        The full name or business name of the account holder.
        Example: "Frangos Enlatados"
      - `holder.identifier` (string, required)
        The CPF (11 digits) or CNPJ (14 digits) of the account holder.
        Example: "12345678901122"
      - `details` (object, required)
        Details of the bank account.
      - `details.institution` (string, required)
        The Belvo ID of the financial institution.
        Example: "f512d996-583a-4a91-8b5b-eba2e103b068"
      - `details.account_type` (string, required)
        The type of bank account. Can be either:
  - CHECKINGS (also known as Conta Corrente in Brazil)
  - SAVINGS (also known as Conta Poupança in Brazil)
  - PAYMENTS (also known as Conta de Pagamento Instantâneo or Conta de Pagamento in Brazil)
        Enum: same as `details.account_type` in "V2 - Bank Account" (3 values)
      - `details.agency` (string, required)
        The agency (branch number) of the institution where the account was created.
        Example: "0444"
      - `details.number` (string, required)
        The bank account number.

{% admonition type="info" name="Valid Account Number characters" %}
  You can only send through numbers (^[0-9]+$) in the string. For example, "457220" is a valid bank account number, while "45722-0" is invalid as it contains a hyphen (-).
{% /admonition %}
        Example: "457220"
      - `external_id` (string, required)
        An additional unique identifier for the resource for internal purposes.

{% admonition type="success" name="Highly Recommended" %}
  We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `metadata` (object, required)
        Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the payment intent.

{% admonition type="info" name="Metadata Limitations" %}
  You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.
{% /admonition %}
        Example: {"internal_reference_id":"GGq73487w2"}
    - V1 - Bank Account (No Request Header):
      - `id` (string, required)
        Belvo's unique identifier for the current item.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `created_at` (string, required)
        The ISO-8601 timestamp of when the data point was created in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_by` (string, required)
        The unique ID for the user that created this item.
        Example: "bcef7f35-67f2-4b19-b009-cb38795faf09"
      - `customer` (string,null, required)
        Belvo's unique ID for the customer associated with the bank account.

For BUSINESS bank accounts, this field is null.
      - `external_id` (string)
        An additional unique identifier for the resource for internal purposes.

{% admonition type="success" name="Highly Recommended" %}
  We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `institution` (string,null, required)
        Belvo's unique ID for the institution that the bank account is created in.

For BUSINESS bank accounts that Belvo creates for organizations, this field is set to null.
      - `details` (object, required)
        Information regarding the bank account.
      - `details.account_type` (string, required)
        The type of bank account. Can be either:

  - CHECKINGS (also known as Conta Corrente in Brazil)
  - SAVINGS (also known as Conta Poupança in Brazil)
  - SALARY (also known as Conta Salário in Brazil)
  - PAYMENTS (also known as Conta de Pagamento Instantâneo or Conta de Pagamento in Brazil)
        Enum: same as `details.account_type` in "V1 - OFPI Business" (4 values)
      - `details.agency` (string, required)
        The agency (branch number) of the institution where the account was created.
        Example: "0444"
      - `details.number` (string, required)
        The bank account number.

> 📘 Valid account number characters
>
> You can only send through numbers (^[0-9]+$) in the string. For example, "457220" is a valid bank account number, while "45722-0" is invalid as it contains a hyphen (-).
        Example: "457220"
      - `holder` (any, required) — one of:
        - OFPI Brazil 🇧🇷 INDIVIDUAL:
          - `type` (string, required)
            The type of bank account. For individuals, this must be set to INDIVIDUAL.
            Enum: same as `holder.type` in "V1 - OFPI Individual" (1 values)
          - `information` (object, required)
            Details regarding the individual bank account holder.
          - `information.first_name` (string, required)
            The bank account holder's first name.
            Example: "Dom"
          - `information.last_name` (string, required)
            The bank account holder's last name.
            Example: "Mesa"
          - `information.identifier_type` (string, required)
            The customer's ID document type. For individuals in Brazil, this must be set to CPF.
            Enum: same as `holder.information.identifier_type` in "V1 - OFPI Individual" (1 values)
          - `information.identifier` (string, required)
            The document number of the customer's ID.
            Example: "00000000191"
        - OFPI Brazil 🇧🇷 BUSINESS:
          - `type` (string, required)
            The type of bank account. For businesses, this must be set to BUSINESS.
            Enum: same as `holder.type` in "V1 - OFPI Business" (1 values)
          - `information` (object, required)
            Details regarding the individual bank account holder.
          - `information.name` (string, required)
            The bank account holder's first name.
            Example: "Gustavo Veloso Entertainment Universe"
          - `information.identifier_type` (string, required)
            The customer's ID document type. For businesses in Brazil, this must be set to CNPJ.
            Enum: same as `holder.information.identifier_type` in "V1 - OFPI Business" (1 values)
          - `information.identifier` (string, required)
            The CNPJ document number.
            Example: "00000000000191"

## Response 400 fields (application/json):

  - `code` (string, required)
    A unique error code (null, does_not_exist, required, already_registered, invalid_choice, max_length, min_length, blank, null, cancellation_error, idempotency_key_invalid) that allows you to classify and handle the error programmatically.
    Example: "required"

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


The description can be (among others):

  - This field is required.
  - Object with name=narnia does not exist.
  - This field may not be null.
  - This field may not be blank.
  - This customer is already registered
  - Ensure this field has at least 2 characters.
  - Ensure this field has no more than 4 characters.
  - Entered value is not valid.
  - You must set all required fields: username, password, username_type.
  - Payment Intent cannot be canceled because it is not SCHEDULED.
  - Payment Intent cannot be canceled as the cutoff time (23:59:00) has passed.
  - The provided idempotency key is invalid.
    Example: "This field is required."

  - `request_id` (string, required)
    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"

  - `field` (string,null)
    Name of the field where the error was encountered.

> Note: This field is only present when the error is related to a specific field.
    Example: "institution"

## 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"