# Gerar um token de acesso para o widget de pagamento

Gerar um token de acesso para o widget de pagamento para o processo de inscrição ou pagamento por biometria.

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 de pagamentos biométricos. Você pode escolher:

  - ENROLLMENT: Use esta opção para registrar o dispositivo do usuário no serviço de pagamentos biométricos.
  - PAYMENT_INTENT: Use esta opção se você quiser criar um pagamento para uma transação de pagamentos biométricos.

> 📘 Usando o widget tanto para registro quanto para pagamentos.
>
> Se você passar ambos os casos de uso ENROLLMENT e PAYMENT_INTENT, o widget primeiro registrará 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.

  - `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 usando pagamentos biométricos no 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: "open_finance_biometric_pix"

  - `widget.payment_intent.payment_method_details` (object, required)
    Detalhes sobre o método de pagamento usado para pagamentos biométricos.

  - `widget.payment_intent.payment_method_details.open_finance_biometric_pix` (object, required)
    Detalhes sobre o método de pagamento utilizado para pagamentos biométricos por 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 de pagamentos biométricos.

  - `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 payments 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: "jwt_test_ey.........."

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

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