Buenas prácticas

Pagos y confirmaciones

• Nunca confirmes un pago solo por crear el QR — espera siempre el webhook payin.completed
• Guarda el txId de cada transacción en tu base de datos junto a tu referencia interna (txIdSource)
• Monitorea todos los eventos: payin.failed y payin.reversed además de payin.completed

Idempotencia

• Usa x-idempotency-key en todos los reintentos de Pay-In para evitar QRs duplicados
• Genera el UUID antes del loop de reintentos y reutiliza el mismo key

Webhooks

• Responde 200 siempre en tu webhookUrl, incluso si tuvieras un error interno
• Procesa de forma asíncrona: responde rápido, encola el procesamiento
• Sé idempotente: el mismo webhook puede llegar más de una vez (usa txId como clave)

Expiración de QR

• Valida el expirationInSeconds según tu flujo:
  • Órdenes con tiempo límite corto: 15-30 minutos (900-1800)
  • Suscripciones o facturas: hasta 24 horas (86400)

Pay-Outs

• Verifica availableBalance antes de enviar un pay-out si quieres dar un mensaje de error proactivo al usuario
• Usa payout.failed para detectar rechazos del banco y notificar al usuario

Seguridad

• Guarda private.pem fuera del repositorio — usa variables de entorno o un secrets manager
• Rota tus claves si sospechas que fueron comprometidas — contacta a soporte
• Valida los timestamps de los webhooks recibidos para evitar replay attacks

Manejo de errores

Error	Acción
401	Regenerar timestamp + nonce + firma (no reutilizar)
402	Verificar saldo disponible antes de reintentar
409	Verificar el estado actual de la transacción
502 / 503	Reintentar con backoff exponencial (2s, 4s, 8s)
500	Reintentar máx 3 veces; si persiste, contactar soporte

Soporte

Para onboarding, credenciales o soporte técnico contacta al equipo de Rivopay.