Skip to main content

​
Buenas prácticas de integración

​
Flujo de integración recomendado

1. Comercio crea QR  →  POST /transfers/qr  (con Idempotency-Key)
2. Mostrar qrImageUrl al usuario final (o qrImageBase64 como fallback)
3. Esperar webhook de confirmación en endpoint propio del comercio
4. Si no llega webhook en X segundos  →  GET /transfers/qr/{id}  (polling)
5. Al recibir status PAID  →  confirmar orden en sistema del comercio

​
Uso de la imagen QR

<!-- Preferir URL CDN: se puede almacenar en caché y no satura el servidor -->
<img src="{{ transaction.qrImageUrl }}" alt="QR de pago CUCU" />

<!-- Fallback con Base64 si qrImageUrl es null -->
<img src="data:image/png;base64,{{ transaction.qrImageBase64 }}" alt="QR de pago CUCU" />

​
Conciliación

  • Usar externalReference para mapear cada transacción CUCU a la orden interna del comercio.
  • El campo metadata es libre — úsarlo para pasar datos de contexto (canal, SKU, sesión) que serán devueltos en la consulta de estado y en los webhooks.
  • No usar el transactionId de CUCU como clave primaria en la base de datos del comercio — usar externalReference como llave de conciliación.

​
Ambientes

AmbienteBase URL
Staging (pruebas)https://pay-staging.cucu.bo/api/v1
Producciónhttps://qrsimple.cucu.bo/api/v1
Los tokens de staging y producción son distintos. Nunca usar credenciales de producción en pruebas.