---
title: "Generate a payment widget access token"
method: POST
path: "/payments/br/token/"
tags: ["Biometric payments Widget Access Token (Brazil)"]
---

# Generate a payment widget access token

`POST /payments/br/token/`

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

## Request body

- BiometricPaymentWidgetRequest
  - `use_cases` string[], required — The use case of the Biometric payments widget. You can choose: - `ENROLLMENT`: Use this option to enroll the user's device in the Biometric payments service. - `PAYMENT_INTENT`: Use this option if you want to create a payment for a Biometric payments 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.
  - `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.
    - `enrollment` EnrollmentBiometricPaymentWidget — 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.
      - `type` 'open_finance_biometric_pix', required — The type of enrollment. For 🇧🇷 Brazil's OFPI, can be either: - `open_finance_biometric_pix`: For biometric payments using the PIX network.
      - `external_id` string, uuid — 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 %}
      - `details` object, required — The details of the enrollment to be created.
        - `name` string — A human-readable name for the device enrollment.
        - `customer` union, 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.
          - string, uuid — Belvo's unique ID to reference the customer.
          - CustomerPaymentWidget
            - `identifier` string, required — The customer's CPF number.
            - `name` string — The full name of the customer you want to create or list enrollments for.
            - `external_id` string, uuid — 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 %}
        - `institution` string, uuid — **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.
      - `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.
    - `payment_intent` PaymentIntentBiometricWidget — Create a payment using Biometric payments in Brazil (OFPI).
      - `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`
      - `external_id` string, uuid — 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 %}
      - `description` string, required — A human-readable description of the payment.
      - `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.
      - `allowed_payment_method_types` string[], 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.
      - `payment_method_details` IndividualRequestBiometricPix, required — Details about the payment method used for Biometric payments.
        - `open_finance_biometric_pix` object, required — Details regarding the payment method used for Biometric payments by individual customers.
          - `beneficiary_bank_account` string, uuid, required — Belvo's unique ID used to identify the beneficiary's bank account.
          - `enrollment` string, uuid — 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.
      - `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.
    - `callback_urls` CallbackUrlsBiometricPaymentWidget, 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)
      - `success` string, required — The URL your user is redirected to when they successfully complete the enrollment or payment.
      - `exit` string, required — The URL your user is redirected to when they exit the process before completing the enrollment or payment.
    - `branding` BrandingBiometricWidget, required — Add customized branding elements to the Biometric payments widget.
      - `color_scheme` 'LIGHT' | 'DARK' — 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.
      - `company_name` string, required — The name of the company that will be displayed in the widget.
    - `top_tier_institutions` string[] — (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.
    - `theme` ThemeBiometricWidget[] — Use the `theme` array to add further customization to your chosen color scheme. For details regarding all the possible customizations, please see our dedicated <a href="https://developers.belvo.com/docs/branding-and-customization-biometric-pix-widget" target="_blank">Branding and Customization (Biometric payments widget)</a> guide.
      - `css_key` string, required — Widget CSS variable name.
      - `value` string, required — The HEX code for the `css_key`.

## Response `200`

Successful operation

- WidgetToken
  - `access` string — The access token to be used to authenticate the widget.
  - `refresh` string — The refresh token to be used to authenticate the widget.

## Other responses

- `400` — Bad request error
- `500` — Unexpected Error

---

[API](https://skmtc.net/belvo/apis/belvo-api-docs.md) · [All operations](https://skmtc.net/belvo/apis/belvo-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/belvo/belvo-api-docs/revisions/e82dca4a4b97/schema)