# Gerar um token de acesso para o widget de pagamento

Gerar um token de acesso para o widget de pagamento para o processo de cadastro ou pagamento com Pix Biométrico.

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

## Request fields (application/json):

  - `use_cases` (array, required)
    O caso de uso do widget Biometric Pix. Você pode escolher:

  - ENROLLMENT: Use esta opção se você deseja cadastrar o dispositivo do usuário no serviço Biometric Pix.
  - PAYMENT_INTENT: Use esta opção se você deseja criar um pagamento para uma transação Biometric Pix.

> 📘 Usando o widget para ambos os casos de uso: cadastro e pagamentos.
>
> Se você passar ambos os casos de uso ENROLLMENT e PAYMENT_INTENT, o widget primeiro irá cadastrar o usuário e, em seguida, criar uma intenção de pagamento.
    Enum: "ENROLLMENT", "PAYMENT_INTENT"

  - `widget` (object, required)
    O objeto widget contém informações adicionais sobre como configurar o widget, incluindo detalhes de inscrição\, informações de pagamento\ e URLs de callback.

> 📘 Objetos condicionalmente obrigatórios
>
> Os objetos enrollment e payment_intent são obrigatórios de forma condicional, com base nos use_cases que você fornecer. Para simplificar sua integração, recomendamos que você sempre passe ambos os casos de uso (ENROLLMENT e PAYMENT_INTENT), e então forneça tanto os objetos enrollment quanto payment_intent.

  - `widget.enrollment` (object)
    O objeto enrollment contém informações chave que são necessárias para inscrever o dispositivo do usuário na instituição deles ou para listar as inscrições associadas ao usuário.

  - `widget.enrollment.type` (string, required)
    O tipo de inscrição. Para o OFPI do 🇧🇷 Brasil, pode ser:

  - open_finance_biometric_pix: Para pagamentos biométricos usando a rede PIX.
    Enum: "open_finance_biometric_pix"

  - `widget.enrollment.external_id` (string)
    Um identificador exclusivo adicional para o recurso para fins internos.

{% admonition type="success" name="Altamente Recomendado" %}
  Recomendamos usar este campo para armazenar seu próprio identificador exclusivo para cada recurso (cliente, conta bancária, intenção de pagamento ou inscrição). Isso pode ser útil para rastrear o recurso em seu sistema e para fins de depuração.
{% /admonition %}
    Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"

  - `widget.enrollment.details` (object, required)
    Os detalhes da inscrição a ser criada.

  - `widget.enrollment.details.name` (string)
    Um nome legível para humanos para o registro do dispositivo.
    Example: "600f1b4a-Mobile"

  - `widget.enrollment.details.customer` (any, required)
    O cliente para o qual você deseja criar ou listar inscrições. Você pode fornecer o ID Belvo ou o CPF do cliente.

> 📘 Novos clientes
>
> Se você fornecer um CPF para um usuário que não existe no Belvo, criaremos um novo cliente com o CPF fornecido.
    - `identifier` (string, required)
      O número de CPF do cliente.
      Example: "10187609363"
    - `name` (string)
      O nome completo do cliente para o qual você deseja criar ou listar inscrições.
      Example: "Gustavo Veloso"
    - `external_id` (string)
      Um identificador exclusivo adicional para o recurso para fins internos.

{% admonition type="success" name="Altamente Recomendado" %}
  Recomendamos usar este campo para armazenar seu próprio identificador exclusivo para cada recurso (cliente, conta bancária, intenção de pagamento ou inscrição). Isso pode ser útil para rastrear o recurso em seu sistema e para fins de depuração.
{% /admonition %}
      Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"

  - `widget.enrollment.details.institution` (string)
    Opcional: ID exclusivo da Belvo para referenciar a instituição do pagador.

Se você fornecer o ID da instituição, o widget pulará a etapa de seleção da instituição.
    Example: "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0"

  - `widget.enrollment.metadata` (object, required)
    Objeto opcional e personalizável onde você pode fornecer quaisquer pares de chave-valor adicionais para seus propósitos internos. Por exemplo, um número de referência interno.

⚠️ Nota: Você pode fornecer até 50 chaves (as chaves podem ter até 50 caracteres cada e cada valor pode ter até 500 caracteres). Não oferecemos suporte a objetos aninhados, apenas valores ASCII.
    Example: {"internal_reference_id":"GGq73487w2"}

  - `widget.payment_intent` (object)
    Criar um Pagamento Pix Biométrico para o Brasil (OFPI).

  - `widget.payment_intent.amount` (string, required)
    Valor a ser pago pelo seu cliente. Para OFPI, você pode enviar números com até duas casas decimais, separados por um ponto .. Por exemplo: 1234.12
    Example: "1234.12"

  - `widget.payment_intent.external_id` (string)
    Um identificador exclusivo adicional para o recurso para fins internos.

{% admonition type="success" name="Altamente Recomendado" %}
  Recomendamos usar este campo para armazenar seu próprio identificador exclusivo para cada recurso (cliente, conta bancária, intenção de pagamento ou inscrição). Isso pode ser útil para rastrear o recurso em seu sistema e para fins de depuração.
{% /admonition %}
    Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"

  - `widget.payment_intent.description` (string, required)
    Uma descrição legível por humanos do pagamento.
    Example: "Shoe payment"

  - `widget.payment_intent.statement_description` (string)
    Uma descrição que aparecerá no extrato bancário do cliente (recomendado).

> Nota: Se você não usar o parâmetro statement_description, o valor de description será utilizado como a descrição no extrato.
    Example: "Super Shoe Store - Brown Sneakers"

  - `widget.payment_intent.allowed_payment_method_types` (array, required)
    Uma lista de tipos de métodos de pagamento permitidos nesta intenção de pagamento. Para OFPI do 🇧🇷 Brasil, pode ser:

  - open_finance: Para pagamentos regulares.
  - open_finance_biometric_pix: Para pagamentos biométricos usando a rede PIX.
    Enum: same as `widget.enrollment.type` (1 values)

  - `widget.payment_intent.payment_method_details` (object, required)
    Detalhes sobre o método de pagamento Biometric Pix.

  - `widget.payment_intent.payment_method_details.open_finance_biometric_pix` (object, required)
    Detalhes sobre o método de pagamento Biometric Pix para clientes individuais.

  - `widget.payment_intent.payment_method_details.open_finance_biometric_pix.beneficiary_bank_account` (string, required)
    ID único da Belvo usado para identificar a conta bancária do beneficiário.
    Example: "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"

  - `widget.payment_intent.payment_method_details.open_finance_biometric_pix.enrollment` (string)
    O enrollment.id para a intenção de pagamento.

> 📘 Nota
>
> Se você passar o enrollment.id na solicitação, o widget pulará a tela "Listar inscrições" e solicitará automaticamente a digitalização biométrica do usuário.
    Example: "7dc245e3-5f75-4534-bafa-431fc0893593"

  - `widget.payment_intent.metadata` (object, required)
    Objeto opcional e personalizável onde você pode fornecer quaisquer pares de chave-valor adicionais para seus propósitos internos. Por exemplo, um número de referência interno.

⚠️ Nota: Você pode fornecer até 50 chaves (as chaves podem ter até 50 caracteres cada e cada valor pode ter até 500 caracteres). Não oferecemos suporte a objetos aninhados, apenas valores ASCII.
    Example: {"internal_reference_id":"GGq73487w2"}

  - `widget.callback_urls` (object, required)
    No objeto callback_urls, você deve adicionar links para onde seu usuário deve ser redirecionado nos seguintes casos:

- success (seu usuário completou com sucesso o processo de inscrição ou pagamento)
- exit (seu usuário saiu do widget antes de completar o processo de inscrição ou pagamento)

  - `widget.callback_urls.success` (string, required)
    A URL para a qual o usuário é redirecionado quando conclui com sucesso a inscrição ou o pagamento.
    Example: "your_deeplink_here://success"

  - `widget.callback_urls.exit` (string, required)
    A URL para a qual o usuário é redirecionado quando sai do processo antes de concluir a inscrição ou pagamento.
    Example: "your_deeplink_here://exit"

  - `widget.branding` (object, required)
    Adicione elementos de marca personalizados ao widget Biometric Pix.

  - `widget.branding.color_scheme` (string)
    O esquema de cores do widget. Você pode escolher entre LIGHT e DARK. Por padrão, o widget usa o esquema de cores LIGHT.

> 📘 Personalizando o esquema de cores
>
> Se você quiser personalizar ainda mais as cores para esses modos, consulte o parâmetro theme.
    Enum: "LIGHT", "DARK"

  - `widget.branding.company_name` (string, required)
    O nome da empresa que será exibido no widget.
    Example: "Acme Inc."

  - `widget.top_tier_institutions` (array)
    (Opcional) Um array de instituições para exibir inicialmente no widget (os usuários ainda poderão pesquisar por outras instituições). Você pode selecionar entre 1 a 5 instituições da lista disponível. As instituições serão exibidas na ordem em que você as fornecer no array. Se você não passar este parâmetro, o widget exibirá todas as instituições disponíveis.
    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 o array theme para adicionar mais personalização ao seu esquema de cores escolhido. Para detalhes sobre todas as possíveis personalizações, consulte nosso guia dedicado de Branding and Customization (Biometric Pix Widget).

  - `widget.theme.css_key` (string, required)
    Nome da variável CSS do widget.
    Example: "--color-primary-base"

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

## Response 200 fields (application/json):

  - `access` (string)
    O token de acesso a ser usado para autenticar o widget.
    Example: "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3MzYwMTk1LCJpYXQiOjE3MjczNTg5OTUsImp0aSI6ImRhN2Q3OTM1ZDZlZTQ0MTBhYTMwYTc3NWQ1OWMxZWIzIiwidXNlcl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsIm9yZ2FuaXphdGlvbl9uYW1lIjoiRG9taW5payBDaG9sZXdza2kncyB0ZWFtIiwib3JnYW5pemF0aW9uX2lkIjoiNmU5YmU4ODQtNDc4MS00MTQzLWI2NzMtYWNhMDI0NzVlZThjIiwic2NvcGVzIjpbInJlYWRfaW5zdGl0dXRpb25zIiwid3JpdGVfbGlua3MiXSwiZW52aXJvbm1lbnQiOiJzYW5kYm94IiwiYXBpX3VybCI6InNhbmRib3guYmVsdm8uY29tIiwiY3JlZGVudGlhbHNfc3RvcmFnZSI6IjMwZCIsInN0YWxlX2luIjoiMzY1ZCIsImZldGNoX3Jlc291cmNlcyI6WyJPV05FUlMiLCJFTVBMT1lNRU5UUyJdLCJpc3MiOiJzYW5kYm94LmJlbHZvLmNvbSJ9.DaQ8xVTEjA4BD-0SbBCQDylO3NrjhsHiWXTaoPdKWRucS2E0jxNUHC5lwrejrz73-GytgcXTeiI1fhZBYW719A"

  - `refresh` (string)
    O token de atualização a ser usado para autenticar o widget.
    Example: "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjM0OTQzODk5NSwiaWF0IjoxNzI3MzU4OTk1LCJqdGkiOiI2YmUyMGFmNTcxZDU0NjQzYjA0Y2U3YTVhNjI5ZDRiMSIsInVzZXJfaWQiOiI2ZTliZTg4NC00NzgxLTQxNDMtYjY3My1hY2EwMjQ3NWVlOGMiLCJvcmdhbml6YXRpb25fbmFtZSI6IkRvbWluaWsgQ2hvbGV3c2tpJ3MgdGVhbSIsIm9yZ2FuaXphdGlvbl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsInNjb3BlcyI6WyJyZWFkX2luc3RpdHV0aW9ucyIsIndyaXRlX2xpbmtzIl0sImVudmlyb25tZW50Ijoic2FuZGJveCIsImFwaV91cmwiOiJzYW5kYm94LmJlbHZvLmNvbSIsImNyZWRlbnRpYWxzX3N0b3JhZ2UiOiIzMGQiLCJzdGFsZV9pbiI6IjM2NWQiLCJmZXRjaF9yZXNvdXJjZXMiOlsiT1dORVJTIiwiRU1QTE9ZTUVOVFMiXSwiaXNzIjoic2FuZGJveC5iZWx2by5jb20ifQ.T-tnX2BwAjQI0MaYCO686bZD6H7EMIgi_CbOWtHDexGIiTKLer0d7RJGisXJqM6oA_L4y_A_774LEj8NNb7YXQ"

## Response 500 fields (application/json):

  - `code` (string)
    Um código de erro único (unexpected_error) que permite classificar e tratar o erro de forma programática.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 500 unexpected_error.
    Example: "unexpected_error"

  - `message` (string)
    Uma breve descrição do erro.

Para erros unexpected_error, a descrição é:

  - Belvo não consegue processar a solicitação devido a um problema interno do sistema ou a uma resposta não suportada de uma instituição.
    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)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"