# Generar un token de acceso para el widget de pago

Generar un token de acceso para el widget de pago para el proceso de inscripción o pago con pagos biométricos.

Endpoint: POST /payments/br/token/
Version: 1.223.0
Security: basicAuth

## Request fields (application/json):

  - `use_cases` (array, required)
    El caso de uso del widget de pagos biométricos. Puedes elegir:

  - ENROLLMENT: Usa esta opción para registrar el dispositivo del usuario en el servicio de pagos biométricos.
  - PAYMENT_INTENT: Usa esta opción si deseas crear un pago para una transacción de pagos biométricos.

> 📘 Usar el widget tanto para registro como para pagos.
>
> Si pasas ambos casos de uso, ENROLLMENT y PAYMENT_INTENT, el widget primero registrará al usuario y luego creará una intención de pago.
    Enum: "ENROLLMENT", "PAYMENT_INTENT"

  - `widget` (object, required)
    El objeto widget contiene información adicional sobre cómo configurar el widget, incluyendo detalles de inscripción\, información de pago\ y URLs de callback.

> 📘 Objetos condicionalmente requeridos
>
> Los objetos enrollment y payment_intent son requeridos condicionalmente, según los use_cases que proporciones. Para simplificar tu integración, te recomendamos que siempre pases ambos casos de uso (ENROLLMENT así como PAYMENT_INTENT), y luego pases tanto los objetos enrollment como payment_intent.

  - `widget.enrollment` (object)
    El objeto enrollment contiene información clave que se requiere para inscribir el dispositivo del usuario con su institución o para listar las inscripciones asociadas con el usuario.

  - `widget.enrollment.type` (string, required)
    El tipo de inscripción. Para la OFPI de 🇧🇷 Brasil, puede ser:

  - open_finance_biometric_pix: Para pagos biométricos utilizando la red PIX.
    Enum: "open_finance_biometric_pix"

  - `widget.enrollment.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"

  - `widget.enrollment.details` (object, required)
    Los detalles de la inscripción que se va a crear.

  - `widget.enrollment.details.name` (string)
    Un nombre legible para humanos para la inscripción del dispositivo.
    Example: "600f1b4a-Mobile"

  - `widget.enrollment.details.customer` (any, required)
    El cliente para el que deseas crear o listar inscripciones. Puedes proporcionar el ID de Belvo o el CPF del cliente.

> 📘 Nuevos clientes
>
> Si proporcionas un CPF para un usuario que no existe en Belvo, crearemos un nuevo cliente con el CPF proporcionado.
    - `identifier` (string, required)
      El número de CPF del cliente.
      Example: "10187609363"
    - `name` (string)
      El nombre completo del cliente para el que desea crear o listar inscripciones.
      Example: "Gustavo Veloso"
    - `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"

  - `widget.enrollment.details.institution` (string)
    Opcional: ID único de Belvo para referenciar la institución del pagador.

Si proporcionas el ID de la institución, el widget omitirá el paso de selección de la institución.
    Example: "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0"

  - `widget.enrollment.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.

⚠️ Nota: Solo puedes proporcionar hasta 50 claves (las claves pueden tener hasta 50 caracteres cada una y cada valor puede tener hasta 500 caracteres). No admitimos objetos anidados, solo valores ASCII.
    Example: {"internal_reference_id":"GGq73487w2"}

  - `widget.payment_intent` (object)
    Crear un pago utilizando pagos biométricos en Brasil (OFPI).

  - `widget.payment_intent.amount` (string, required)
    Cantidad a pagar por su cliente. Para OFPI, puede enviar números con hasta dos decimales, separados por un . punto. Por ejemplo: 1234.12
    Example: "1234.12"

  - `widget.payment_intent.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"

  - `widget.payment_intent.description` (string, required)
    Una descripción legible para humanos del pago.
    Example: "Shoe payment"

  - `widget.payment_intent.statement_description` (string)
    Una descripción que aparecerá en el extracto bancario del cliente (recomendado).

> Nota: Si no utiliza el parámetro statement_description, se usará el valor de description como la descripción del extracto.
    Example: "Super Shoe Store - Brown Sneakers"

  - `widget.payment_intent.allowed_payment_method_types` (array, required)
    Una lista de tipos de métodos de pago permitidos en esta intención de pago. Para OFPI de 🇧🇷 Brasil, puede ser:

  - open_finance: Para pagos regulares.
  - open_finance_biometric_pix: Para pagos biométricos utilizando la red PIX.
    Enum: same as `widget.enrollment.type` (1 values)

  - `widget.payment_intent.payment_method_details` (object, required)
    Detalles sobre el método de pago utilizado para pagos biométricos.

  - `widget.payment_intent.payment_method_details.open_finance_biometric_pix` (object, required)
    Detalles sobre el método de pago utilizado para pagos biométricos por clientes individuales.

  - `widget.payment_intent.payment_method_details.open_finance_biometric_pix.beneficiary_bank_account` (string, required)
    El ID único de Belvo utilizado para identificar la cuenta bancaria del beneficiario.
    Example: "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"

  - `widget.payment_intent.payment_method_details.open_finance_biometric_pix.enrollment` (string)
    El enrollment.id para la intención de pago.

> 📘 Nota
>
> Si pasas el enrollment.id en la solicitud, el widget omitirá la pantalla de "Listar inscripciones" y solicitará automáticamente al usuario su escaneo biométrico.
    Example: "7dc245e3-5f75-4534-bafa-431fc0893593"

  - `widget.payment_intent.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.

⚠️ Nota: Solo puedes proporcionar hasta 50 claves (las claves pueden tener hasta 50 caracteres cada una y cada valor puede tener hasta 500 caracteres). No admitimos objetos anidados, solo valores ASCII.
    Example: {"internal_reference_id":"GGq73487w2"}

  - `widget.callback_urls` (object, required)
    En el objeto callback_urls, debes agregar enlaces a donde tu usuario debe ser redirigido en los siguientes casos:

- success (tu usuario completó con éxito el proceso de inscripción o pago)
- exit (tu usuario salió del widget antes de completar el proceso de inscripción o pago)

  - `widget.callback_urls.success` (string, required)
    La URL a la que se redirige a tu usuario cuando completa con éxito la inscripción o el pago.
    Example: "your_deeplink_here://success"

  - `widget.callback_urls.exit` (string, required)
    La URL a la que se redirige a tu usuario cuando sale del proceso antes de completar la inscripción o el pago.
    Example: "your_deeplink_here://exit"

  - `widget.branding` (object, required)
    Agregue elementos de marca personalizados al widget de pagos biométricos.

  - `widget.branding.color_scheme` (string)
    El esquema de color del widget. Puedes elegir entre LIGHT y DARK. Por defecto, el widget utiliza el esquema de color LIGHT.

> 📘 Personalización del esquema de color
>
> Si deseas personalizar aún más los colores para estos modos, consulta el parámetro theme.
    Enum: "LIGHT", "DARK"

  - `widget.branding.company_name` (string, required)
    El nombre de la empresa que se mostrará en el widget.
    Example: "Acme Inc."

  - `widget.top_tier_institutions` (array)
    (Opcional) Un array de instituciones para mostrar inicialmente en el widget (los usuarios aún podrán buscar otras instituciones). Puedes seleccionar entre 1 a 5 instituciones de la lista disponible. Las instituciones se mostrarán en el orden en que las proporciones en el array. Si no pasas este parámetro, el widget mostrará todas las instituciones disponibles.
    Enum: "nubank_retail", "inter_retail", "picpay_retail", "mercadopago_retail", "itau_retail", "santander_retail", "c6_retail", "bradesco_retail", "banco_do_brasil_retail", "sicredi_retail", "btg_retail", "caixa_retail", "pan_retail", "pagseguro_retail"

  - `widget.theme` (array)
    Utiliza el array theme para añadir más personalización a tu esquema de color elegido. Para obtener detalles sobre todas las posibles personalizaciones, consulta nuestra guía dedicada de Branding and Customization (Biometric payments widget).

  - `widget.theme.css_key` (string, required)
    Nombre de la variable CSS del widget.
    Example: "--color-primary-base"

  - `widget.theme.value` (string, required)
    El código HEX para el css_key.
    Example: "#907AD6"

## Response 200 fields (application/json):

  - `access` (string)
    El token de acceso que se utilizará para autenticar el widget.
    Example: "jwt_test_ey.........."

  - `refresh` (string)
    El token de actualización que se utilizará para autenticar el widget.
    Example: "jwt_test_ey.........."

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