# Gerenciando contas vinculadas Quando um pagador vincula uma conta na página de pagamento, a Pluggy armazena uma **inscrição**: o link entre sua conta em uma instituição e o dispositivo e navegador onde ele criou a chave de acesso. As inscrições são criadas apenas pelo pagador, durante um pagamento. Através da API, você pode listá-las, lê-las, ver os pagamentos feitos com elas e revogá-las. Cada endpoint nesta página retorna apenas as inscrições do seu próprio cliente. ## A inscrição ```json title="Inscrição" { "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" } }, "cpf": "***.456.789-**", "cnpj": null, "customerId": "a2d4c1e8-5b7f-4c3a-9e2d-1f6b8c0d7e55", "limits": { "transaction": 1000, "daily": 3000, "dailyUsed": 149.9 }, "expiresAt": "2027-10-28T13:05:00.000Z", "dataConsent": null, "revokedBy": null, "errorDetail": null, "createdAt": "2026-10-28T13:02:00.000Z", "updatedAt": "2026-10-28T13:05:00.000Z" } ``` | Campo | Descrição | |---|---| | `id` | O id da inscrição. As intenções de pagamento referenciam como `enrollmentId`. | | `status` | Veja a tabela abaixo. | | `connector` | A instituição onde a conta está mantida. | | `debtor` | A conta vinculada, conforme a instituição relatou. O número do CPF e o número da conta estão mascarados. | | `cpf` / `cnpj` | O número do CPF do pagador, mascarado. Use o valor não mascarado para [filtrar a lista](#list-enrollments). | | `customerId` | O Cliente de Pagamento da solicitação de pagamento onde o link foi criado, ou `null` quando o pagador digitou seu CPF. | | `limits` | Os limites por pagamento (`transaction`) e `daily` que o pagador definiu no banco, e quanto do limite de hoje foi utilizado (`dailyUsed`), em BRL. Qualquer um deles pode ser `null` quando a instituição não o reporta. | | `expiresAt` | Quando o link expira, conforme definido pela instituição. | | `dataConsent` | A permissão de compartilhamento de saldo, ou `null` quando não foi solicitada. Veja [Compartilhando saldo](#sharing-balance). | | `revokedBy` | Quem revogou o link: `BANK` (o pagador ou a instituição, no banco) ou `CLIENT` (você, através da API). `null` a menos que `status` seja `REVOKED`. | | `errorDetail` | `{ code, description }` com o motivo que a instituição deu quando o link foi rejeitado, por exemplo, porque o pagador não o completou a tempo. Caso contrário, `null`. | | `status` | Significado | |---|---| | `CREATED` | O pagador começou a vincular e não terminou: ele está no banco ou criando a chave de acesso. | | `AUTHORIZED` | O link está ativo. Pagamentos nesse dispositivo precisam apenas de biometria. | | `REJECTED` | O link não foi completado: a instituição ou o pagador o rejeitaram, ou o pagador não terminou a tempo. `errorDetail` diz qual. | | `REVOKED` | O link foi revogado no banco ou através da API. | | `EXPIRED` | O link atingiu sua data de expiração ou se tornou inativo na instituição. | `REJECTED`, `REVOKED` e `EXPIRED` são finais. Para pagar com biometria novamente, o pagador precisa vincular novamente, o que cria uma nova inscrição. ## Listar inscrições ``` GET /pix-biometric/enrollments?customerId={customerId}&status=AUTHORIZED ``` | Parâmetro de consulta | Descrição | |---|---| | `customerId` | Inscrições criadas em solicitações de pagamento para este Cliente de Pagamento. | | `cpf` | O CPF do pagador, apenas dígitos. | | `cnpj` | O CNPJ do pagador, apenas dígitos. | | `status` | Um dos status acima. | | `page` / `pageSize` | Paginação. `pageSize` é no máximo `500`. | A resposta utiliza a paginação usual: ```json title="GET /pix-biometric/enrollments (resposta)" { "total": 1, "totalPages": 1, "page": 1, "results": [ { "id": "c91a5e2b-7d0f-4f3e-9a51-2f6b8e1d4c77", "status": "AUTHORIZED" } ] } ``` Um pagador pode ter várias inscrições: uma por dispositivo e navegador, e uma por instituição que ele vinculou. Veja a [referência da API](/reference/pix-por-biometria/pix-biometric-enrollments-list). ## Recuperar uma inscrição ``` GET /pix-biometric/enrollments/{id} ``` Retorna a inscrição, atualizada pela instituição, de modo que um link revogado no banco apareça como `REVOKED` aqui mesmo antes que o webhook chegue. Um id que não existe para seu cliente responde `404` com `PIX_BIOMETRIC_ENROLLMENT_NOT_FOUND`. Veja a [referência da API](/reference/pix-por-biometria/pix-biometric-enrollment-retrieve). ## Pagamentos feitos com uma inscrição ``` GET /payments/intents?enrollmentId={id} ``` Lista as intenções de pagamento feitas com aquele link, com a paginação usual. Cada uma carrega sua `paymentRequest`, para que você possa identificar quais compras o pagador fez com ela. Veja a [referência da API](/reference/payment-intent/payment-intents-list). ## Revogar uma inscrição ``` POST /pix-biometric/enrollments/{id}/revoke ``` Sem corpo. O link é revogado na instituição e a inscrição é retornada com `status: "REVOKED"` e `revokedBy: "CLIENT"`. Você também recebe um webhook `pix_biometric_enrollment/revoked`. Se o pagador ainda estava completando seu primeiro pagamento com aquele link, essa intenção de pagamento falha. Revogar não pode ser desfeito: o pagador precisa vincular novamente para pagar com biometria. Revogar uma inscrição que já está `REJECTED`, `REVOKED` ou `EXPIRED` a retorna inalterada, então tentar novamente é seguro. Veja a [referência da API](/reference/pix-por-biometria/pix-biometric-enrollment-revoke). O pagador também pode desfazer o link a qualquer momento no aplicativo do banco. Você toma conhecimento disso através do webhook `pix_biometric_enrollment/revoked`, e a inscrição então mostra `revokedBy: "BANK"`. ## Compartilhando saldo Quando a solicitação de pagamento foi criada com `linkedJourney: true`, o pagador também pode compartilhar seu saldo de conta e limite de cheque especial com você, na mesma aprovação no banco. É opcional para o pagador e dura enquanto o link estiver ativo. Leia o saldo logo antes de cobrar, para evitar um pagamento rejeitado por fundos insuficientes. A inscrição carrega a permissão em `dataConsent`: ```json { "status": "AUTHORISED", "rejectionReason": null, "updatedAt": "2026-10-28T13:05:00.000Z" } ``` | `dataConsent.status` | Significado | |---|---| | `AWAITING_AUTHORISATION` | O pagador ainda não aprovou. | | `AUTHORISED` | O saldo pode ser lido. | | `REJECTED` | O pagador ou a instituição rejeitaram. `rejectionReason` diz o porquê. | | `REVOKED` | A permissão foi cancelada. | `dataConsent` é `null` quando a solicitação não pediu por isso, ou o pagador optou por não compartilhar. ### Ler o saldo ``` GET /pix-biometric/enrollments/{id}/balance ``` Lê o saldo em tempo real da instituição. Os valores estão em BRL. Veja a [referência da API](/reference/pix-por-biometria/pix-biometric-enrollment-balance-retrieve). ```json { "balance": 5.48, "overdraft": { "contracted": 1000, "used": 0, "available": 1000 } } ``` `overdraft` é o limite de cheque especial da conta: quanto foi contratado, quanto está em uso e quanto ainda está disponível. É `null` quando a instituição não o compartilha. | Status | `codeDescription` | Significado | |---|---|---| | `200` | | Saldo lido. | | `403` | `PIX_BIOMETRIC_DATA_CONSENT_NOT_AVAILABLE` | O link não está `AUTHORIZED`, ou o pagador não compartilhou o saldo, ou a permissão foi cancelada. | | `429` | `PIX_BIOMETRIC_RATE_LIMITED` | O limite de taxa da instituição foi atingido, por exemplo, a cota mensal de saldo da conta. | Cada chamada lê o saldo da instituição, sem cache. O Open Finance limita as leituras de saldo por conta por mês (veja [Limites de Taxa Operacional](/docs/open-finance/rate-limits)). Leia o saldo logo antes de um pagamento, não em um cronograma. ### Parar de compartilhar o saldo ``` DELETE /pix-biometric/enrollments/{id}/data-consent ``` Cancela apenas a permissão de saldo: o link permanece `AUTHORIZED` e os pagamentos continuam funcionando. Retorna a inscrição com `dataConsent.status` definido como `REVOKED`. Cancelar uma permissão que já terminou retorna a inscrição inalterada, então tentar novamente é seguro. Um link criado sem a permissão responde `403` com `PIX_BIOMETRIC_DATA_CONSENT_NOT_AVAILABLE`. Veja a [referência da API](/reference/pix-por-biometria/pix-biometric-enrollment-data-consent-delete). Revogar o link também encerra a permissão de saldo. Uma permissão não pode ser adicionada a um link existente: o pagador precisa vincular novamente a partir de uma solicitação de pagamento criada com `linkedJourney: true`. ## Webhooks | Evento | Quando | |---|---| | `pix_biometric_enrollment/authorized` | O pagador completou um link. | | `pix_biometric_enrollment/revoked` | O link foi revogado, no banco ou através da API. | | `pix_biometric_enrollment/error` | O link não foi completado: foi rejeitado ou terminou antes que o pagador o finalizasse. | ```json title="pix_biometric_enrollment/authorized" { "event": "pix_biometric_enrollment/authorized", "eventId": "8013240b-7c0a-409e-bf00-7fc586cc9196", "enrollmentId": "c91a5e2b-7d0f-4f3e-9a51-2f6b8e1d4c77", "customerId": "a2d4c1e8-5b7f-4c3a-9e2d-1f6b8c0d7e55", "paymentRequestId": "5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e" } ``` `paymentRequestId` é a solicitação de pagamento onde o link foi criado, e `customerId` é `null` quando não havia cliente. Cada evento é enviado uma vez, quando a inscrição entra nesse status. Recupere a inscrição para os detalhes. Um link que foi `AUTHORIZED` e depois atinge seu `expiresAt` não envia evento: verifique `expiresAt`, ou recupere a inscrição, para saber que terminou.