- Creación de transacciones Pix
- Gestión de claves (DICT)
- Generación de códigos QR
- Configuración de límites
- Manejo de webhooks
- Recuperación de fallos
¿Por qué usarlo?
El plugin de Pix existe para simplificar las partes de Pix que son dolorosas de construir y riesgosas de hacer mal. Ya sea que sea una fintech, banco digital, proveedor de ERP o plataforma de finanzas integradas, este plugin le brinda:- Orquestación confiable: Gestionamos todo el ciclo de vida de la transacción, desde la validación de saldo hasta reintentos, actualizaciones de estado y compensación en caso de fallo.
- Integración fluida: Su aplicación solo necesita interactuar con la API del plugin de Pix. Nosotros manejamos operaciones de Core Bank, PSTI, DICT y códigos QR detrás de escena.
- Diseño impulsado por webhooks: El plugin envía y recibe eventos Pix de forma asíncrona, por lo que su sistema se mantiene sincronizado sin sondeos ni conjeturas.
- Cumplimiento incorporado: Toda la lógica sigue las regulaciones de BACEN, incluidas las reglas DICT, validación de claves Pix y flujos de confirmación de propiedad.
- Flujos listos para auditoría: Cada transacción se registra con estado, marcas de tiempo y enlaces de eventos, lo que facilita el seguimiento y la depuración.
Cuándo usarlo
El plugin de Pix es ideal para casos de uso como:- Billeteras digitales o aplicaciones bancarias
- Plataformas B2B que necesitan pagos masivos o cobros Pix
- Sistemas de gestión financiera y ERP
- Mercados con flujos de pago automatizados
- Instituciones que manejan grandes volúmenes de transacciones y reversiones Pix
Conceptos clave
Estas son las ideas y términos principales que verá en el plugin de Pix:| Término | Descripción |
|---|---|
| PSTI | Un “Prestador de Serviços de Tecnologia da Informação” (Proveedor de servicios de tecnología de la información) que se conecta a la infraestructura Pix del Banco Central Brasileño. |
| DICT | El directorio del Banco Central para claves Pix. Valida, almacena y gestiona registros de claves. |
| Pix Key | Identificadores como CPF/CNPJ, número de teléfono, correo electrónico o EVP utilizados para enviar/recibir transferencias Pix. |
| Webhook | Notificaciones enviadas o recibidas por el Authorizer para mantener los sistemas sincronizados. Por ejemplo, actualizaciones de estado o depósitos Pix externos. |
| Cash-in | Cuando su usuario recibe una transferencia Pix de otra institución. |
| Reversal | Una operación de reembolso o reversión que deshace una transacción Pix. |
| Pending | Una transacción que ha sido enviada pero aún no confirmada por el PSTI. |
| Confirmed | Una transacción que fue procesada con éxito. |
| Failed | Una transacción que no pudo ser procesada, a menudo debido a saldo insuficiente o rechazo del PSTI. |
Especificaciones técnicas
Formato de API
- Protocolo: Solo HTTPS
- Autenticación: Bearer Token
- Payload: JSON
- Códigos de estado: REST estándar (200, 201, 400, 422, 500)
Entorno requerido
- Debe exponer endpoints HTTPS públicamente accesibles para recibir webhooks.
- Todas las solicitudes salientes de Lerian usan TLS 1.2+ y certificados verificados.
- La lógica de reintento en webhooks usa backoff exponencial con TTL.
Dependencias
- Core Bank (para validación de cuenta, verificaciones de saldo, débitos y créditos)
- PSTI (para envío de transacciones Pix e interacción con DICT)
Reglas de validación internas
- CPF/CNPJ debe ser válido y coincidir con el formato brasileño.
- El correo electrónico y el teléfono deben pasar verificaciones básicas de formato.
- Los montos Pix deben ser mayores que cero y estar por debajo de los límites configurados.
- Las transacciones deben identificarse de forma única mediante un ID proporcionado por el cliente.
Variables configurables
| Variable | Descripción |
|---|---|
MAX_TRANSACTION_RETRIES | Cuántas veces se reintentará una transacción en caso de fallo. |
WEBHOOK_SIGNATURE_SECRET | Utilizado para verificar la autenticidad del webhook entrante/saliente. |
PENDING_JOB_INTERVAL | Frecuencia (en segundos) para verificar transacciones pendientes. |
MAX_PIX_AMOUNT | Un límite opcional para cualquier transferencia Pix individual. |
Mejores prácticas
Para aprovechar al máximo el plugin de Pix y evitar problemas comunes, tenga en cuenta lo siguiente:Usar IDs de transacción idempotentes
Siempre envíe untransactionId único generado por su sistema. Esto asegura que los reintentos no resulten en transferencias duplicadas.
Manejar webhooks antes de mostrar el estado final
No asuma que un Pix fue exitoso solo porque la API devolvió200. En su lugar, espere la confirmación del webhook para reflejar el estado real de la transacción.