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#

{
  "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"
}

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

A resposta utiliza a paginação usual:

{
  "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 APIAPI.

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 APIAPI.

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 APIAPI.

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 APIAPI.

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:

{
  "status": "AUTHORISED",
  "rejectionReason": null,
  "updatedAt": "2026-10-28T13:05:00.000Z"
}

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 APIAPI.

{
  "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.

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 APIAPI.

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#

{
  "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.