Buenas prácticas de integración

Flujo de integración recomendado

Comercio crea QR  →  POST /transfers/qr  (con Idempotency-Key)
Mostrar qrImageUrl al usuario final (o qrImageBase64 como fallback)
Esperar webhook de confirmación en endpoint propio del comercio
Si no llega webhook en X segundos  →  GET /transfers/qr/{id}  (polling)
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

Ambiente	Base URL
Staging (pruebas)	`https://pay-staging.cucu.bo/api/v1`
Producción	`https://qrsimple.cucu.bo/api/v1`

Los tokens de staging y producción son distintos. Nunca usar credenciales de producción en pruebas.

​Buenas prácticas de integración

​Flujo de integración recomendado

​Uso de la imagen QR

​Conciliación

​Ambientes

Buenas prácticas de integración

Flujo de integración recomendado

Uso de la imagen QR

Conciliación

Ambientes