Registro de claves
Los usuarios pueden registrar una clave Pix de los siguientes tipos:- Correo electrónico
- Número de teléfono
- CPF
- CNPJ
- EVP (clave aleatoria)
Confirmación de titularidad
Para claves de correo electrónico y teléfono, el usuario debe confirmar la titularidad usando un código de un solo uso con límite de tiempo. Este paso garantiza que la persona que registra la clave realmente controla el correo electrónico o teléfono que se está vinculando. Si el código expira o no es válido, el flujo de registro debe reiniciarse.La confirmación de titularidad tiene un límite de tiempo. Asegúrate de que tu interfaz informe claramente al usuario cuándo se requiere una confirmación y cuándo expira.
Listado de claves
El plugin permite que tu sistema recupere todas las claves Pix asociadas con una cuenta determinada. Esto es útil para mostrar identificadores vinculados a los usuarios o gestionar el estado de las claves. Solo las claves confirmadas se consideran activas y disponibles para usar en transacciones Pix.Eliminación de claves
Las claves Pix pueden eliminarse de la capa DICT en cualquier momento. Cuando se elimina, la clave se disocia de la cuenta del usuario y queda disponible para registro en otro lugar, sujeto a las reglas de liberación estándar de BACEN. La eliminación es idempotente: intentar eliminar una clave ya eliminada o inexistente no causará errores.Portabilidad y reclamación de claves
Si un usuario intenta registrar una clave Pix que ya está asociada con otra institución, el plugin Pix admite iniciar una solicitud de portabilidad o reclamación. Esto sigue el flujo oficial de BACEN:1
La solicitud se envía a la red Pix.
2
Si es elegible, la clave se marca como
claim_requested.3
Se notifica a la institución externa y, si aprueban, la clave se transfiere a tu sistema.
4
Si la clave no es elegible (por ejemplo, en disputa o bloqueada), la solicitud se rechaza.
La reclamación es un proceso asíncrono. La transferencia final depende de la respuesta de la institución que actualmente posee la clave.
Cancelar una solicitud de reclamación
Si un usuario cambia de opinión durante el proceso de portabilidad, la solicitud de reclamación puede cancelarse antes de que se finalice. Una vez cancelada, la clave permanecerá registrada en la institución original.Manejo de errores
El plugin Pix estandariza tipos de error comunes y garantiza degradación elegante. Algunos escenarios comunes incluyen:- Formato de clave inválido: La clave no sigue el formato esperado para su tipo.
- Clave ya registrada: Un flujo de reclamación puede activarse automáticamente.
- Confirmación expirada: La validación de titularidad no se completó a tiempo.
- Clave no encontrada: Intentar interactuar con una clave que no existe.