# Registrar una nueva cuenta bancaria

Registrar una nueva cuenta bancaria desde la cual enviar o solicitar fondos.

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

## Header parameters:

  - `X-Belvo-API-Resource-Version` (string)
    Encabezado que indica qué versión de la API de Pagos deseas utilizar. Actualmente, esto solo es aplicable para Cuentas Bancarias, Clientes y Autorizaciones de Pago en Brasil. En el caso de que estés utilizando nuestro producto de Autorizaciones de Pago, entonces debes enviar este encabezado configurado en Payments-BR.V2.

{% admonition type="warning" name="Próximamente" %}
  Esta versión está en Próximamente. Por lo tanto, pueden ocurrir cambios menores o errores. Si encuentras algún problema, por favor contacta a tu representante de Belvo.
{% /admonition %}
    Enum: "Payments-BR.V2"

## Request fields (application/json):

  - `body` (object) — one of:
    - V2 - Cuenta Bancaria:
      - `holder` (object, required)
        Detalles del titular de la cuenta.
      - `holder.name` (string, required)
        El nombre completo o nombre comercial del titular de la cuenta.
        Example: "Frangos Enlatados"
      - `holder.identifier` (string, required)
        El CPF (11 dígitos) o CNPJ (14 dígitos) del titular de la cuenta.
        Example: "12345678901122"
      - `details` (object, required)
        Detalles de la cuenta bancaria.
      - `details.account_type` (string, required)
        El tipo de cuenta bancaria. Puede ser:
  - CHECKINGS (también conocida como Conta Corrente en Brasil)
  - SAVINGS (también conocida como Conta Poupança en Brasil)
  - PAYMENTS (también conocida como Conta de Pagamento Instantâneo o Conta de Pagamento en Brasil)
        Enum: "CHECKINGS", "SAVINGS", "PAYMENTS"
      - `details.agency` (string, required)
        La agencia (número de sucursal) de la institución donde se creó la cuenta.
        Example: "0444"
      - `details.institution` (string, required)
        El Belvo ID de la institución financiera.
        Example: "f512d996-583a-4a91-8b5b-eba2e103b068"
      - `details.number` (string, required)
        El número de cuenta bancaria.

{% admonition type="info" name="Caracteres válidos para el número de cuenta" %}
  Solo puedes enviar números (^[0-9]+$) en la cadena. Por ejemplo, "457220" es un número de cuenta bancaria válido, mientras que "45722-0" es inválido ya que contiene un guion (-).
{% /admonition %}
        Example: "457220"
      - `external_id` (string)
        Un identificador único adicional para el recurso con fines internos.

{% admonition type="success" name="Altamente Recomendado" %}
  Recomendamos usar este campo para almacenar su propio identificador único para cada recurso (cliente, cuenta bancaria, intención de pago o inscripción). Esto puede ser útil para rastrear el recurso en su sistema y para fines de depuración.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `metadata` (object)
        Objeto opcional y personalizable donde puedes proporcionar cualquier par clave-valor adicional para tus propósitos internos. Por ejemplo, un número de referencia interno para la intención de pago.

{% admonition type="info" name="Limitaciones de Metadata" %}
  Solo puedes proporcionar hasta 50 claves (las claves pueden tener hasta 50 caracteres cada una y cada valor puede tener hasta 500 caracteres). No soportamos objetos anidados, solo valores ASCII.
{% /admonition %}
        Example: {"internal_reference_id":"GGq73487w2"}
    - V1 - Negocio OFPI:
      - `institution` (string, required)
        El ID único de Belvo para la institución en la que se crea la cuenta bancaria.
        Example: "f512d996-583a-4a91-8b5b-eba2e103b068"
      - `external_id` (string)
        Un identificador único adicional para el recurso con fines internos.

{% admonition type="success" name="Altamente Recomendado" %}
  Recomendamos usar este campo para almacenar su propio identificador único para cada recurso (cliente, cuenta bancaria, intención de pago o inscripción). Esto puede ser útil para rastrear el recurso en su sistema y para fines de depuración.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `holder` (object, required)
        Detalles sobre el titular de la cuenta bancaria empresarial.
      - `holder.type` (string, required)
        El tipo de cuenta bancaria. Para cuentas bancarias de negocios, esto debe establecerse en BUSINESS.
        Enum: "BUSINESS"
      - `holder.information` (object, required)
        Información adicional sobre el titular de la cuenta bancaria requerida para crear la cuenta para OFPI.
      - `holder.information.name` (string, required)
        El nombre completo del negocio
        Example: "Gustavo Veloso Entertainment Universe"
      - `holder.information.identifier_type` (string, required)
        El tipo de documento de identificación del cliente. Para las empresas en Brasil, esto debe establecerse en CNPJ.
        Enum: "CNPJ"
      - `holder.information.identifier` (string, required)
        El número de documento CNPJ.
        Example: 191
      - `details` (object, required)
        Información sobre la cuenta bancaria.
      - `details.account_type` (string, required)
        El tipo de cuenta bancaria. Puede ser:

  - CHECKINGS (también conocida como Conta Corrente en Brasil)
  - SAVINGS (también conocida como Conta Poupança en Brasil)
  - SALARY (también conocida como Conta Salário en Brasil)
  - PAYMENTS (también conocida como Conta de Pagamento Instantâneo o Conta de Pagamento en Brasil)
        Enum: "CHECKINGS", "SAVINGS", "SALARY", "PAYMENTS"
      - `details.agency` (string, required)
        La agencia (número de sucursal) de la institución donde se creó la cuenta.
        Example: "0444"
      - `details.number` (string, required)
        El número de cuenta bancaria.

> 📘 Caracteres válidos para el número de cuenta
>
> Solo puedes enviar números (^[0-9]+$) en la cadena. Por ejemplo, "457220" es un número de cuenta bancaria válido, mientras que "45722-0" es inválido ya que contiene un guion (-).
        Example: "457220"
    - V1 - OFPI Individual:
      - `institution` (string, required)
        El ID único de Belvo para la institución en la que se crea la cuenta bancaria.
        Example: "f512d996-583a-4a91-8b5b-eba2e103b068"
      - `external_id` (string)
        Un identificador único adicional para el recurso con fines internos.

{% admonition type="success" name="Altamente Recomendado" %}
  Recomendamos usar este campo para almacenar su propio identificador único para cada recurso (cliente, cuenta bancaria, intención de pago o inscripción). Esto puede ser útil para rastrear el recurso en su sistema y para fines de depuración.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `holder` (object, required)
        Detalles sobre el titular de la cuenta bancaria individual.
      - `holder.type` (string, required)
        El tipo de cuenta bancaria. Para individuos, esto debe establecerse en INDIVIDUAL.
        Enum: "INDIVIDUAL"
      - `holder.information` (object, required)
        Información adicional sobre el titular de la cuenta bancaria requerida para crear la cuenta para OFPI.
      - `holder.information.first_name` (string, required)
        El nombre de pila del titular de la cuenta bancaria.
        Example: "Gustavo"
      - `holder.information.last_name` (string, required)
        El apellido del titular de la cuenta bancaria.
        Example: "Veloso"
      - `holder.information.identifier_type` (string, required)
        El tipo de documento de identificación del cliente. Para individuos en Brasil, esto debe establecerse en CPF.
        Enum: "CPF"
      - `holder.information.identifier` (string, required)
        El número de documento de la identificación del cliente.
        Example: 191
      - `details` (object, required)
        Información sobre la cuenta bancaria.
      - `details.account_type` (string, required)
        El tipo de cuenta bancaria. Puede ser:

  - CHECKINGS (también conocida como Conta Corrente en Brasil)
  - SAVINGS (también conocida como Conta Poupança en Brasil)
  - SALARY (también conocida como Conta Salário en Brasil)
  - PAYMENTS (también conocida como Conta de Pagamento Instantâneo o Conta de Pagamento en Brasil)
        Enum: same as `details.account_type` in "V1 - Negocio OFPI" (4 values)
      - `details.agency` (string, required)
        La agencia (número de sucursal) de la institución donde se creó la cuenta.
        Example: "0444"
      - `details.number` (string, required)
        El número de cuenta bancaria.

> 📘 Caracteres válidos para el número de cuenta
>
> Solo puedes enviar números (^[0-9]+$) en la cadena. Por ejemplo, "457220" es un número de cuenta bancaria válido, mientras que "45722-0" es inválido ya que contiene un guion (-).
        Example: "457220"

## Response 201 fields (application/json):

  - `body` (object) — one of:
    - V2 - Cuenta Bancaria:
      - `id` (string, required)
        Identificador único de Belvo para el elemento actual.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `created_at` (string, required)
        La marca de tiempo ISO-8601 de cuando se creó el punto de datos en la base de datos de Belvo.
        Example: "2022-02-09T08:45:50.406032Z"
      - `updated_at` (string, required)
        La marca de tiempo ISO-8601 de cuando el punto de datos fue actualizado en la base de datos de Belvo.
        Example: "2022-02-09T08:45:50.406032Z"
      - `active` (boolean, required)
        Indica si la cuenta bancaria está activa (y se puede usar para recibir fondos).
        Example: true
      - `holder` (object, required)
        Detalles del titular de la cuenta.
      - `holder.name` (string, required)
        El nombre completo o nombre comercial del titular de la cuenta.
        Example: "Frangos Enlatados"
      - `holder.identifier` (string, required)
        El CPF (11 dígitos) o CNPJ (14 dígitos) del titular de la cuenta.
        Example: "12345678901122"
      - `details` (object, required)
        Detalles de la cuenta bancaria.
      - `details.institution` (string, required)
        El Belvo ID de la institución financiera.
        Example: "f512d996-583a-4a91-8b5b-eba2e103b068"
      - `details.account_type` (string, required)
        El tipo de cuenta bancaria. Puede ser:
  - CHECKINGS (también conocida como Conta Corrente en Brasil)
  - SAVINGS (también conocida como Conta Poupança en Brasil)
  - PAYMENTS (también conocida como Conta de Pagamento Instantâneo o Conta de Pagamento en Brasil)
        Enum: same as `details.account_type` in "V2 - Cuenta Bancaria" (3 values)
      - `details.agency` (string, required)
        La agencia (número de sucursal) de la institución donde se creó la cuenta.
        Example: "0444"
      - `details.number` (string, required)
        El número de cuenta bancaria.

{% admonition type="info" name="Caracteres válidos para el número de cuenta" %}
  Solo puedes enviar números (^[0-9]+$) en la cadena. Por ejemplo, "457220" es un número de cuenta bancaria válido, mientras que "45722-0" es inválido ya que contiene un guion (-).
{% /admonition %}
        Example: "457220"
      - `external_id` (string, required)
        Un identificador único adicional para el recurso con fines internos.

{% admonition type="success" name="Altamente Recomendado" %}
  Recomendamos usar este campo para almacenar su propio identificador único para cada recurso (cliente, cuenta bancaria, intención de pago o inscripción). Esto puede ser útil para rastrear el recurso en su sistema y para fines de depuración.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `metadata` (object, required)
        Objeto opcional y personalizable donde puedes proporcionar cualquier par clave-valor adicional para tus propósitos internos. Por ejemplo, un número de referencia interno para la intención de pago.

{% admonition type="info" name="Limitaciones de Metadata" %}
  Solo puedes proporcionar hasta 50 claves (las claves pueden tener hasta 50 caracteres cada una y cada valor puede tener hasta 500 caracteres). No soportamos objetos anidados, solo valores ASCII.
{% /admonition %}
        Example: {"internal_reference_id":"GGq73487w2"}
    - V1 - Cuenta Bancaria (Sin Encabezado de Solicitud):
      - `id` (string, required)
        Identificador único de Belvo para el elemento actual.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `created_at` (string, required)
        La marca de tiempo ISO-8601 de cuando se creó el punto de datos en la base de datos de Belvo.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_by` (string, required)
        El ID único para el usuario que creó este elemento.
        Example: "bcef7f35-67f2-4b19-b009-cb38795faf09"
      - `customer` (string,null, required)
        El ID único de Belvo para el cliente asociado con la cuenta bancaria.

Para cuentas bancarias de tipo BUSINESS, este campo es null.
      - `external_id` (string)
        Un identificador único adicional para el recurso con fines internos.

{% admonition type="success" name="Altamente Recomendado" %}
  Recomendamos usar este campo para almacenar su propio identificador único para cada recurso (cliente, cuenta bancaria, intención de pago o inscripción). Esto puede ser útil para rastrear el recurso en su sistema y para fines de depuración.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `institution` (string,null, required)
        El ID único de Belvo para la institución en la que se crea la cuenta bancaria.

Para las cuentas bancarias de tipo BUSINESS que Belvo crea para organizaciones, este campo se establece en null.
      - `details` (object, required)
        Información sobre la cuenta bancaria.
      - `details.account_type` (string, required)
        El tipo de cuenta bancaria. Puede ser:

  - CHECKINGS (también conocida como Conta Corrente en Brasil)
  - SAVINGS (también conocida como Conta Poupança en Brasil)
  - SALARY (también conocida como Conta Salário en Brasil)
  - PAYMENTS (también conocida como Conta de Pagamento Instantâneo o Conta de Pagamento en Brasil)
        Enum: same as `details.account_type` in "V1 - Negocio OFPI" (4 values)
      - `details.agency` (string, required)
        La agencia (número de sucursal) de la institución donde se creó la cuenta.
        Example: "0444"
      - `details.number` (string, required)
        El número de cuenta bancaria.

> 📘 Caracteres válidos para el número de cuenta
>
> Solo puedes enviar números (^[0-9]+$) en la cadena. Por ejemplo, "457220" es un número de cuenta bancaria válido, mientras que "45722-0" es inválido ya que contiene un guion (-).
        Example: "457220"
      - `holder` (any, required) — one of:
        - OFPI Brazil 🇧🇷 INDIVIDUAL:
          - `type` (string, required)
            El tipo de cuenta bancaria. Para individuos, esto debe establecerse en INDIVIDUAL.
            Enum: same as `holder.type` in "V1 - OFPI Individual" (1 values)
          - `information` (object, required)
            Detalles sobre el titular de la cuenta bancaria individual.
          - `information.first_name` (string, required)
            El nombre de pila del titular de la cuenta bancaria.
            Example: "Dom"
          - `information.last_name` (string, required)
            El apellido del titular de la cuenta bancaria.
            Example: "Mesa"
          - `information.identifier_type` (string, required)
            El tipo de documento de identificación del cliente. Para individuos en Brasil, esto debe establecerse en CPF.
            Enum: same as `holder.information.identifier_type` in "V1 - OFPI Individual" (1 values)
          - `information.identifier` (string, required)
            El número de documento de la identificación del cliente.
            Example: 191
        - OFPI Brazil 🇧🇷 NEGOCIOS:
          - `type` (string, required)
            El tipo de cuenta bancaria. Para empresas, esto debe establecerse en BUSINESS.
            Enum: same as `holder.type` in "V1 - Negocio OFPI" (1 values)
          - `information` (object, required)
            Detalles sobre el titular de la cuenta bancaria individual.
          - `information.name` (string, required)
            El nombre de pila del titular de la cuenta bancaria.
            Example: "Gustavo Veloso Entertainment Universe"
          - `information.identifier_type` (string, required)
            El tipo de documento de identificación del cliente. Para las empresas en Brasil, esto debe establecerse en CNPJ.
            Enum: same as `holder.information.identifier_type` in "V1 - Negocio OFPI" (1 values)
          - `information.identifier` (string, required)
            El número de documento CNPJ.
            Example: 191

## Response 400 fields (application/json):

  - `code` (string, required)
    Un código de error único (null, does_not_exist, required, already_registered, invalid_choice, max_length, min_length, blank, null, cancellation_error, idempotency_key_invalid) que te permite clasificar y manejar el error de manera programática.
    Example: "required"

  - `message` (string, required)
    Una breve descripción del error.

La descripción puede ser (entre otras):

  - Este campo es obligatorio.
  - El objeto con nombre=narnia no existe.
  - Este campo no puede ser nulo.
  - Este campo no puede estar en blanco.
  - Este cliente ya está registrado.
  - Asegúrese de que este campo tenga al menos 2 caracteres.
  - Asegúrese de que este campo no tenga más de 4 caracteres.
  - El valor ingresado no es válido.
  - Debe establecer todos los campos obligatorios: username, password, username_type.
  - Payment Intent no puede ser cancelado porque no está SCHEDULED.
  - Payment Intent no puede ser cancelado ya que el tiempo límite (23:59:00) ha pasado.
  - La clave de idempotencia proporcionada no es válida.
    Example: "This field is required."

  - `request_id` (string, required)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

  - `field` (string,null)
    Nombre del campo donde se encontró el error.

> Nota: Este campo solo está presente cuando el error está relacionado con un campo específico.
    Example: "institution"

## Response 403 fields (application/json):

  - `code` (string)
    Un código de error único (access_to_resource_denied) que te permite clasificar y manejar el error de manera programática.

ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    Una breve descripción del error.

Para los errores access_to_resource_denied, la descripción es:

  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    Un código de error único (not_found) que te permite clasificar y manejar el error de manera programática.
    Example: "not_found"

  - `message` (string)
    Una breve descripción del error.

Para errores not_found, la descripción es:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    Un código de error único (request_timeout) que te permite clasificar y manejar el error de manera programática.

ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar errores 408 request_timeout.
    Example: "request_timeout"

  - `message` (string)
    Una breve descripción del error.

Para los errores de request_timeout, la descripción es:

  - 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)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    Un código de error único (unexpected_error) que te permite clasificar y manejar el error de manera programática.

ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar errores 500 unexpected_error.
    Example: "unexpected_error"

  - `message` (string)
    Una breve descripción del error.

Para los errores unexpected_error, la descripción es:

- Belvo no puede procesar la solicitud debido a un problema interno del sistema o a una respuesta no soportada de una institució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` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"