# Generate a payment widget access token

Generate a payment widget access token for the Biometric Pix enrollment or payment process.

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

## Request fields (application/json):

  - `use_cases` (array, required)
    The use case of the Biometric Pix widget. You can choose:

  - ENROLLMENT: Use this option if you want to enroll you user's device in the Biometric Pix service.
  - PAYMENT_INTENT: Use this option if you want to create a payment for a Biometric Pix transaction.

> 📘 Using the widget for both enrollment and payments.
>
> If you pass both the ENROLLMENT and PAYMENT_INTENT use cases, the widget will first enroll the user and then create a payment intent.
    Enum: "ENROLLMENT", "PAYMENT_INTENT"

  - `widget` (object, required)
    The widget object contains additional information about how to set up the widget, including enrollment details\, payment information\, and callback URLs.

> 📘 Conditionally requireed objects
>
> The enrollment and payment_intent objects are conditionally required, based on the use_cases you provide. To simplify your integration, we recommend you always pass both use cases (ENROLLMENT as well as PAYMENT_INTENT), and then pass both the enrollment and payment_intent objects.

  - `widget.enrollment` (object)
    The enrollment object contains key information that is required in order to enroll the user's device with their institution or to list the enrollments associated with the user.

  - `widget.enrollment.type` (string, required)
    The type of enrollment. For 🇧🇷 Brazil's OFPI, can be either:

  - open_finance_biometric_pix: For biometric payments using the PIX network.
    Enum: "open_finance_biometric_pix"

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

  - `widget.enrollment.details` (object, required)
    The details of the enrollment to be created.

  - `widget.enrollment.details.name` (string)
    A human-readable name for the device enrollment.
    Example: "600f1b4a-Mobile"

  - `widget.enrollment.details.customer` (any, required)
    The customer you want to create or list enrollments for. You can provide either the Belvo ID or the CPF for the customer.

> 📘 New customers
>
> If you provide a CPF for a user that does not exist in Belvo, we will create a new customer with the provided CPF.
    - `identifier` (string, required)
      The customer's CPF  number.
      Example: "10187609363"
    - `name` (string)
      The full name of the customer you want to create or list enrollments for.
      Example: "Gustavo Veloso"
    - `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"

  - `widget.enrollment.details.institution` (string)
    Optional: Belvo's unique ID to reference the payer's institution.

If you provide the institution ID, the widget will skip the institution selection step.
    Example: "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0"

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


⚠️ Note: 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.
    Example: {"internal_reference_id":"GGq73487w2"}

  - `widget.payment_intent` (object)
    Create a Biometric Pix Payment for Brazil (OFPI).

  - `widget.payment_intent.amount` (string, required)
    Amount to be paid by your customer. For OFPI, you can send through numbers with up to two decimal points, separated by a . period. For example: 1234.12
    Example: "1234.12"

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

  - `widget.payment_intent.description` (string, required)
    A human-readable description of the payment.
    Example: "Shoe payment"

  - `widget.payment_intent.statement_description` (string)
    A description that will appear on the customer's bank statement (recommended).


> Note: If you do not use the statement_description parameter, the description value will be used as the statement description.
    Example: "Super Shoe Store - Brown Sneakers"

  - `widget.payment_intent.allowed_payment_method_types` (array, required)
    A list of payment method types allowed in this payment intent. For 🇧🇷 Brazil's OFPI, can be either:

  - open_finance: For regular payments.
  - open_finance_biometric_pix: For biometric payments using the PIX network.
    Enum: same as `widget.enrollment.type` (1 values)

  - `widget.payment_intent.payment_method_details` (object, required)
    Details about the Biometric Pix payment method.

  - `widget.payment_intent.payment_method_details.open_finance_biometric_pix` (object, required)
    Details regarding the Biometric Pix payment method for individual customers.

  - `widget.payment_intent.payment_method_details.open_finance_biometric_pix.beneficiary_bank_account` (string, required)
    Belvo's unique ID used to identify the beneficiary's bank account.
    Example: "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"

  - `widget.payment_intent.payment_method_details.open_finance_biometric_pix.enrollment` (string)
    The enrollment.id for the payment intent.

> 📘 Note
>
> If you pass the enrollment.id in the request, the widget will skip the "List enrollments" screen and automatically prompt the user for their biometric scan.
    Example: "7dc245e3-5f75-4534-bafa-431fc0893593"

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


⚠️ Note: 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.
    Example: {"internal_reference_id":"GGq73487w2"}

  - `widget.callback_urls` (object, required)
    In the callback_urls object, you must add links to where your user should be redirected to in the following cases:

- success (your user successfully completed the enrollment or payment process)
- exit (your user exited the widget before they completed the enrollment or payment process)

  - `widget.callback_urls.success` (string, required)
    The URL your user is redirected to when they successfully complete the enrollment or payment.
    Example: "your_deeplink_here://success"

  - `widget.callback_urls.exit` (string, required)
    The URL your user is redirected to when they exit the process before completing the enrollment or payment.
    Example: "your_deeplink_here://exit"

  - `widget.branding` (object, required)
    Add customized branding elements to the Biometric Pix widget.

  - `widget.branding.color_scheme` (string)
    The color scheme of the widget. You can choose between LIGHT and DARK. By default, the widget uses the LIGHT color scheme.

> 📘 Customizing the color scheme
>
> If you want to further customize the colors for these modes, please see the theme parameter.
    Enum: "LIGHT", "DARK"

  - `widget.branding.company_name` (string, required)
    The name of the company that will be displayed in the widget.
    Example: "Acme Inc."

  - `widget.top_tier_institutions` (array)
    (Optional) An array of institutions to initially display in the widget (users will still be able to search for other institutions). You can select between 1 to 5 institutions from the available list. The institutions will display in the order you provide them in the array. If you do not pass this parameter, the widget will display all available institutions.
    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)
    Use the theme array to add further customization to your chosen color scheme. For details regarding all the possible customizations, please see our dedicated Branding and Customization (Biometric Pix Widget) guide.

  - `widget.theme.css_key` (string, required)
    Widget CSS variable name.
    Example: "--color-primary-base"

  - `widget.theme.value` (string, required)
    The HEX code for the css_key.
    Example: "#907AD6"

## Response 200 fields (application/json):

  - `access` (string)
    The access token to be used to authenticate the widget.
    Example: "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3MzYwMTk1LCJpYXQiOjE3MjczNTg5OTUsImp0aSI6ImRhN2Q3OTM1ZDZlZTQ0MTBhYTMwYTc3NWQ1OWMxZWIzIiwidXNlcl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsIm9yZ2FuaXphdGlvbl9uYW1lIjoiRG9taW5payBDaG9sZXdza2kncyB0ZWFtIiwib3JnYW5pemF0aW9uX2lkIjoiNmU5YmU4ODQtNDc4MS00MTQzLWI2NzMtYWNhMDI0NzVlZThjIiwic2NvcGVzIjpbInJlYWRfaW5zdGl0dXRpb25zIiwid3JpdGVfbGlua3MiXSwiZW52aXJvbm1lbnQiOiJzYW5kYm94IiwiYXBpX3VybCI6InNhbmRib3guYmVsdm8uY29tIiwiY3JlZGVudGlhbHNfc3RvcmFnZSI6IjMwZCIsInN0YWxlX2luIjoiMzY1ZCIsImZldGNoX3Jlc291cmNlcyI6WyJPV05FUlMiLCJFTVBMT1lNRU5UUyJdLCJpc3MiOiJzYW5kYm94LmJlbHZvLmNvbSJ9.DaQ8xVTEjA4BD-0SbBCQDylO3NrjhsHiWXTaoPdKWRucS2E0jxNUHC5lwrejrz73-GytgcXTeiI1fhZBYW719A"

  - `refresh` (string)
    The refresh token to be used to authenticate the widget.
    Example: "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjM0OTQzODk5NSwiaWF0IjoxNzI3MzU4OTk1LCJqdGkiOiI2YmUyMGFmNTcxZDU0NjQzYjA0Y2U3YTVhNjI5ZDRiMSIsInVzZXJfaWQiOiI2ZTliZTg4NC00NzgxLTQxNDMtYjY3My1hY2EwMjQ3NWVlOGMiLCJvcmdhbml6YXRpb25fbmFtZSI6IkRvbWluaWsgQ2hvbGV3c2tpJ3MgdGVhbSIsIm9yZ2FuaXphdGlvbl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsInNjb3BlcyI6WyJyZWFkX2luc3RpdHV0aW9ucyIsIndyaXRlX2xpbmtzIl0sImVudmlyb25tZW50Ijoic2FuZGJveCIsImFwaV91cmwiOiJzYW5kYm94LmJlbHZvLmNvbSIsImNyZWRlbnRpYWxzX3N0b3JhZ2UiOiIzMGQiLCJzdGFsZV9pbiI6IjM2NWQiLCJmZXRjaF9yZXNvdXJjZXMiOlsiT1dORVJTIiwiRU1QTE9ZTUVOVFMiXSwiaXNzIjoic2FuZGJveC5iZWx2by5jb20ifQ.T-tnX2BwAjQI0MaYCO686bZD6H7EMIgi_CbOWtHDexGIiTKLer0d7RJGisXJqM6oA_L4y_A_774LEj8NNb7YXQ"

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