Saltar al contenido principal
  • Crear transacciones Pix
  • Gestionar claves (DICT)
  • Generar códigos QR
  • Establecer límites
  • Manejar webhooks
  • Recuperarse de fallos
Todo esto está disponible a través de una API segura y fácil de integrar. No necesitas preocuparte por las complejidades de trabajar directamente con PSTIs, servicios DICT o coordinación con Core Banking. El plugin Pix abstrae estas preocupaciones, ofreciendo una capa confiable que garantiza operaciones atómicas, reintentos automáticos y trazabilidad completa. Fue construido para servir a empresas que necesitan operaciones Pix rápidas, conformes y personalizables, sin requerir que reinventen su infraestructura.

​
¿Por qué usarlo?

El plugin Pix existe para simplificar las partes de Pix que son dolorosas de construir y riesgosas de hacer mal. Ya seas una fintech, banco digital, proveedor de ERP o plataforma de finanzas embebidas, este plugin te da:
  • Orquestación confiable: Gestionamos todo el ciclo de vida de la transacción, desde validación de saldo hasta reintentos, actualizaciones de estado y compensación en caso de fallo.
  • Integración perfecta: Tu aplicación solo necesita interactuar con la API del plugin Pix. Nosotros manejamos operaciones de Core Bank, PSTI, DICT y Código QR detrás de escena.
  • Diseño basado en webhooks: El plugin envía y recibe eventos Pix de forma asíncrona, para que tu sistema se mantenga sincronizado sin sondeo ni conjeturas.
  • Cumplimiento incorporado: Toda la lógica sigue las regulaciones del BACEN, incluyendo 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, facilitando el seguimiento y la depuración.

​
Cuándo usarlo

El plugin Pix es ideal para casos de uso como:
  • Billeteras digitales o aplicaciones bancarias.
  • Plataformas B2B que necesitan pagos o cobros Pix masivos.
  • Sistemas ERP y de gestión financiera.
  • Marketplaces con flujos de pago automatizados.
  • Instituciones que manejan grandes volúmenes de transacciones y reversiones Pix.

​
Conceptos clave

Aquí están las ideas y términos principales que verás en el plugin Pix:
TérminoDescripción
PSTIUn “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.
DICTEl directorio del Banco Central para claves Pix. Valida, almacena y gestiona registros de claves.
Pix KeyIdentificadores como CPF/CNPJ, número de teléfono, correo electrónico o EVP usados para enviar/recibir transferencias Pix.
WebhookNotificaciones enviadas o recibidas por el Autorizador para mantener los sistemas sincronizados. Por ejemplo, actualizaciones de estado o depósitos Pix externos.
Cash-inCuando tu usuario recibe una transferencia Pix de otra institución.
ReversalUna operación de reembolso o rollback que deshace una transacción Pix.
PendingUna transacción que ha sido enviada pero aún no confirmada por el PSTI.
ConfirmedUna transacción que fue procesada exitosamente.
FailedUna 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 reintentos en webhooks usa backoff exponencial con TTL.

​
Dependencias

  • Core Bank (para validación de cuentas, verificación de saldos, 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.
  • Correo electrónico y teléfono deben pasar verificaciones básicas de formato.
  • Los montos Pix deben ser mayores que cero y estar debajo de los límites configurados.
  • Las transacciones deben estar identificadas únicamente por ID proporcionado por el cliente.

​
Variables configurables

VariableDescripción
MAX_TRANSACTION_RETRIESCuántas veces se reintentará una transacción en caso de fallo.
WEBHOOK_SIGNATURE_SECRETUsado para verificar la autenticidad de webhooks entrantes/salientes.
PENDING_JOB_INTERVALFrecuencia (en segundos) para verificar transacciones pendientes.
MAX_PIX_AMOUNTUn límite opcional para cualquier transferencia Pix individual.

​
Mejores prácticas

Para aprovechar al máximo el plugin Pix y evitar problemas comunes, ten en cuenta lo siguiente:

​
Usa IDs de transacción idempotentes

Siempre envía un transactionId único generado por tu sistema. Esto asegura que los reintentos no resulten en transferencias duplicadas.

​
Maneja webhooks antes de mostrar el estado final

No asumas que un Pix fue exitoso solo porque la API devolvió 200. En su lugar, espera la confirmación del webhook para reflejar el estado real de la transacción.

​
Valida la autenticidad del webhook

Usa el encabezado X-Signature y tu secreto para verificar que los webhooks entrantes fueron realmente enviados por Lerian.

​
Diseña para el fallo

Las transacciones pueden fallar debido a saldo insuficiente, caída del PSTI u otros casos extremos. Maneja errores y reintentos con gracia, incluyendo mensajes al usuario.

​
Monitorea trabajos pendientes

Si se pierde un webhook o falla un callback del PSTI, el sistema marcará la transacción como pendiente. Los trabajos se reintentarán automáticamente, pero puedes monitorear logs o recibir alertas si los reintentos exceden los umbrales.

​
Mantén tus claves actualizadas

Si un usuario cambia su número de teléfono o correo electrónico, considera eliminar y volver a registrar la clave Pix antigua para evitar conflictos inesperados.