Começando com PIX por biometria

Este guia leva você de um destinatário a um pagamento concluído via PIX por biometria. Para saber o que é o PIX por biometria e como o pagador o experiencia, veja PIX por biometria.

1. Criar um destinatário#

O PIX por biometria paga os mesmos destinatários que qualquer solicitação de pagamento. Crie um destinatário de conta bancária conforme mostrado na Visão Geral de Pagamentos, ou reutilize um que você já tenha. Destinatários de contas inteligentes não são suportados.

2. Identificar o pagador (recomendado)#

Crie um Cliente de Pagamento com o CPF do pagador (e CNPJ para contas empresariais), conforme descrito em Pré-preenchendo o CPF/CNPJ, e passe seu customerId ao criar a solicitação de pagamento. Duas coisas dependem disso:

• A página de pagamento usa o número de identificação fiscal do cliente e não o solicita. Sem um cliente, o pagador digita seu CPF.
• Você pode listar as contas vinculadas de um pagador pelo customerId. Veja Gerenciando contas vinculadas.

3. Criar a solicitação de pagamento#

Crie uma solicitação de pagamento por compra:

{
  "amount": 149.9,
  "recipientId": "ab276a3d-17ba-47eb-97bf-688475037ffe",
  "description": "Pedido 4821",
  "customerId": "a2d4c1e8-5b7f-4c3a-9e2d-1f6b8c0d7e55",
  "clientPaymentId": "4821",
  "linkedJourney": false,
  "callbackUrls": {
    "success": "https://my-store.com/orders/4821/paid",
    "pending": "https://my-store.com/orders/4821/pending",
    "error": "https://my-store.com/orders/4821/error"
  }
}

Para cada campo e resposta, veja a referência da APIAPI.

A resposta é uma Solicitação de Pagamento regular com um objeto pixBiometric:

{
  "id": "5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e",
  "amount": 149.9,
  "description": "Pedido 4821",
  "status": "CREATED",
  "createdAt": "2026-10-28T13:00:00.000Z",
  "updatedAt": "2026-10-28T13:00:00.000Z",
  "callbackUrls": {
    "success": "https://my-store.com/orders/4821/paid",
    "pending": "https://my-store.com/orders/4821/pending",
    "error": "https://my-store.com/orders/4821/error"
  },
  "paymentUrl": "https://pay.pluggy.ai/5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e",
  "clientPaymentId": "4821",
  "pixBiometric": {
    "linkedJourney": false,
    "enrollment": null
  }
}

pixBiometric.enrollment é null até que a solicitação seja paga. Veja etapa 5.

4. Enviar o pagador para a página de pagamento#

Envie ao pagador a paymentUrl. A página de pagamento gerencia toda a jornada: escolhendo o banco, vinculando a conta no primeiro pagamento, criando a chave de acesso e confirmando o pagamento com biometria.

O pagador deve abrir o link em um navegador que suporte chaves de acesso. Alguns navegadores embutidos em aplicativos não conseguem usá-las; quando a página detecta um, pede ao pagador para abrir o link no navegador do dispositivo.

Você não pode criar intenções de pagamento via PIX por biometria através da API: POST /payments/intents responde 403 com PIX_BIOMETRIC_INTENT_INTERNAL_ONLY para essas solicitações. A página de pagamento as cria.

5. Rastrear o pagamento#

A solicitação de pagamento e suas intenções passam pelos status habituais (veja Ciclo de Vida e Erros da Intenção de Pagamento), e você recebe os mesmos webhooks.

Primeiro pagamento em um dispositivo (o pagador vincula uma conta):

1. payment_intent/created
2. payment_intent/waiting_payer_authorization: o pagador está a caminho do banco para aprovar o vínculo.
3. pix_biometric_enrollment/authorized: o vínculo está completo.
4. payment_intent/completed

Pagamentos posteriores (o pagador já tem um vínculo naquele dispositivo):

1. payment_intent/created
2. payment_intent/completed

payment_request/updated é enviado sempre que o status da solicitação muda, como em qualquer solicitação de pagamento.

Uma vez que a solicitação é paga, ela mostra a conta vinculada com a qual foi paga:

{
  "id": "5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e",
  "status": "COMPLETED",
  "pixBiometric": {
    "linkedJourney": false,
    "enrollment": {
      "id": "c91a5e2b-7d0f-4f3e-9a51-2f6b8e1d4c77",
      "status": "AUTHORIZED",
      "connector": {
        "id": 608,
        "name": "Santander",
        "imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/208.svg"
      },
      "debtor": {
        "name": "John Doe",
        "taxNumber": "***.456.789-**",
        "bankAccount": {
          "agency": "1234",
          "account": "****4821",
          "name": "Santander"
        }
      }
    }
  }
}

enrollment.status é o status atual do vínculo, portanto, muda se o vínculo for posteriormente revogado ou expirar. Permanece null quando a solicitação não foi paga, mesmo que o pagador tenha criado um vínculo ao longo do caminho: os webhooks pix_biometric_enrollment/* relatam esse vínculo.

Cada intenção de pagamento carrega paymentMethod: "PIX_BIOMETRIC" e o enrollmentId com o qual foi paga.

Quando um pagamento falha#

Além dos erros de pagamento em Ciclo de Vida e Erros da Intenção de Pagamento, uma intenção de PIX por biometria pode terminar com um desses valores de errorDetail.code:

Uma tentativa falhada não fecha a solicitação de pagamento: o pagador pode tentar novamente a partir da mesma paymentUrl.

Erros ao criar a solicitação de pagamento#

Testando#

O sandbox do PIX por biometria está em desenvolvimento. Até que esteja disponível, testar significa um pagamento real em produção:

• Use um valor pequeno, como 0.01.
• Pague de uma conta em uma instituição que suporte vinculação (supportsPixBiometric), em um telefone ou computador com biometria ou bloqueio de tela.
• Pague de uma conta diferente da do destinatário. Um pagamento para a mesma conta é rejeitado com SAME_ORIGIN_DESTINATION_ACCOUNTS.
• Quando terminar, revogue o vínculo de teste com POST /pix-biometric/enrollments/{id}/revoke, ou desfaça-o no aplicativo do banco.

Próximo: Gerenciando contas vinculadas.