# 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](/docs/payments/pix-biometric). - Iniciação de Pagamento habilitada para seu cliente. - Um [webhook](/docs/webhooks) registrado para eventos de pagamento, para que você saiba sobre pagamentos concluídos e contas vinculadas sem precisar fazer polling. ## 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](/docs/payments/overview), 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](/docs/payments/overview#pre-filling-the-cpfcnpj), 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](/docs/payments/pix-biometric-enrollments). ## 3. Criar a solicitação de pagamento Crie uma solicitação de pagamento por compra: ```json title="POST /payments/requests/pix-biometric (request)" { "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" } } ``` | Campo | Obrigatório | Descrição | |---|---|---| | `amount` | Sim | Valor em BRL, com até duas casas decimais. Mínimo `0.01`. | | `recipientId` | Sim | O destinatário que recebe o pagamento. Apenas destinatários de conta bancária. | | `description` | Não | Exibido para o pagador. Até 140 caracteres. | | `customerId` | Não | O Cliente de Pagamento que identifica o pagador. Recomendado. | | `clientPaymentId` | Não | Seu próprio identificador para o pagamento. Até 200 caracteres. | | `linkedJourney` | Não | `true` permite que o pagador também compartilhe seu saldo com você ao vincular. Veja [Compartilhando saldo](/docs/payments/pix-biometric-enrollments#sharing-balance). Padrão é `false`. | | `callbackUrls` | Não | Para onde a página de pagamento envia o pagador quando o pagamento é bem-sucedido, fica pendente ou falha. Igual a qualquer solicitação de pagamento. | Para cada campo e resposta, veja a [referência da API](/reference/pix-por-biometria/payment-request-create-pix-biometric). A resposta é uma Solicitação de Pagamento regular com um objeto `pixBiometric`: ```json title="POST /payments/requests/pix-biometric (response)" { "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](#5-track-the-payment). O sandbox do PIX por biometria está em desenvolvimento. Até que esteja disponível, uma solicitação criada com `isSandbox: true` é rejeitada com `PIX_BIOMETRIC_SANDBOX_NOT_SUPPORTED`. Veja [Testando](#testing). ## 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. O primeiro pagamento começa em um navegador, continua no banco e retorna à página de pagamento. Se o banco enviar o pagador de volta para um navegador ou dispositivo diferente, a página pede que eles retornem ao ponto de partida ou vinculem novamente a partir de lá. 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](/docs/payments/intent-lifecycle)), 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: ```json title="GET /payments/requests/{id} (excerpt)" { "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](/docs/payments/intent-lifecycle), uma intenção de PIX por biometria pode terminar com um desses valores de `errorDetail.code`: | Status da intenção | `errorDetail.code` | Significado | |---|---|---| | `CONSENT_REJECTED` | `ENROLLMENT_REJECTED` | A instituição ou o pagador rejeitaram o vínculo, portanto, o primeiro pagamento não foi realizado. | | `CONSENT_REJECTED` | `ENROLLMENT_NOT_COMPLETED` | O vínculo expirou ou terminou antes que o pagador o completasse, por exemplo, porque ele não voltou do banco a tempo. | | `CANCELED` | `PIX_BIOMETRIC_SUPERSEDED` | O pagador iniciou uma nova tentativa na mesma solicitação de pagamento, por exemplo, escolhendo outro banco. A nova tentativa continua. | 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 | Status | `codeDescription` | Significado | |---|---|---| | `400` | `PIX_BIOMETRIC_SANDBOX_NOT_SUPPORTED` | `isSandbox` estava `true`. O sandbox do PIX por biometria está em desenvolvimento. | | `400` | `PIX_BIOMETRIC_RECIPIENT_NOT_SUPPORTED` | O destinatário é uma conta inteligente. | | `403` | `PAYMENT_INITIATION_NOT_ALLOWED` | A Iniciação de Pagamento não está habilitada para seu cliente. | | `404` | `PAYMENT_RECIPIENT_NOT_FOUND` | O `recipientId` não existe para seu cliente. | | `404` | `PAYMENT_CUSTOMER_NOT_FOUND` | O `customerId` não existe para seu cliente. | ## 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](/docs/payments/pix-biometric-enrollments).