curl -X POST https://qrsimple.cucu.bo/api/v1/transfers/qr \
-H "Authorization: Bearer <tu_api_token>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"amount": "150.00",
"currency": "BOB",
"gloss": "Pedido #ORD-2026-00871",
"expiration": "30m",
"singleUse": true,
"externalReference": "ORD-2026-00871",
"metadata": {
"orderId": "ORD-2026-00871",
"channel": "web"
}
}'
const response = await fetch('https://qrsimple.cucu.bo/api/v1/transfers/qr', {
method: 'POST',
headers: {
'Authorization': 'Bearer <tu_api_token>',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
amount: '150.00',
currency: 'BOB',
gloss: 'Pedido #ORD-2026-00871',
expiration: '30m',
singleUse: true,
externalReference: 'ORD-2026-00871',
metadata: { orderId: 'ORD-2026-00871', channel: 'web' }
})
});
const data = await response.json();
import uuid, requests
response = requests.post(
'https://qrsimple.cucu.bo/api/v1/transfers/qr',
headers={
'Authorization': 'Bearer <tu_api_token>',
'Content-Type': 'application/json',
'Idempotency-Key': str(uuid.uuid4())
},
json={
'amount': '150.00',
'currency': 'BOB',
'gloss': 'Pedido #ORD-2026-00871',
'expiration': '30m',
'singleUse': True,
'externalReference': 'ORD-2026-00871',
'metadata': {'orderId': 'ORD-2026-00871', 'channel': 'web'}
}
)
print(response.json())
{
"transactionId": "QR2026061500001",
"qrImageUrl": "https://cdn.cucu.bo/qr/cucu-pay/QR2026061500001.png",
"qrImageBase64": "<base64-png>",
"expiresAt": "2026-06-15T14:30:00Z",
"amount": "150.00",
"currency": "BOB",
"status": "PENDING",
"commerceCode": "mi-comercio",
"externalReference": "ORD-2026-00871"
}
{
"detail": "El campo gloss es requerido"
}
{
"detail": "concurrent request"
}
{
"detail": [
{
"type": "greater_than_equal",
"loc": ["body", "amount"],
"msg": "Input should be greater than or equal to 0",
"input": "-5.00"
}
]
}
Endpoints
POST /transfers/qr — Crear transacción QR
Genera un código QR de cobro inmediato escaneable por cualquier usuario de banca móvil en Bolivia.
POST
/
api
/
v1
/
transfers
/
qr
curl -X POST https://qrsimple.cucu.bo/api/v1/transfers/qr \
-H "Authorization: Bearer <tu_api_token>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"amount": "150.00",
"currency": "BOB",
"gloss": "Pedido #ORD-2026-00871",
"expiration": "30m",
"singleUse": true,
"externalReference": "ORD-2026-00871",
"metadata": {
"orderId": "ORD-2026-00871",
"channel": "web"
}
}'
const response = await fetch('https://qrsimple.cucu.bo/api/v1/transfers/qr', {
method: 'POST',
headers: {
'Authorization': 'Bearer <tu_api_token>',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
amount: '150.00',
currency: 'BOB',
gloss: 'Pedido #ORD-2026-00871',
expiration: '30m',
singleUse: true,
externalReference: 'ORD-2026-00871',
metadata: { orderId: 'ORD-2026-00871', channel: 'web' }
})
});
const data = await response.json();
import uuid, requests
response = requests.post(
'https://qrsimple.cucu.bo/api/v1/transfers/qr',
headers={
'Authorization': 'Bearer <tu_api_token>',
'Content-Type': 'application/json',
'Idempotency-Key': str(uuid.uuid4())
},
json={
'amount': '150.00',
'currency': 'BOB',
'gloss': 'Pedido #ORD-2026-00871',
'expiration': '30m',
'singleUse': True,
'externalReference': 'ORD-2026-00871',
'metadata': {'orderId': 'ORD-2026-00871', 'channel': 'web'}
}
)
print(response.json())
{
"transactionId": "QR2026061500001",
"qrImageUrl": "https://cdn.cucu.bo/qr/cucu-pay/QR2026061500001.png",
"qrImageBase64": "<base64-png>",
"expiresAt": "2026-06-15T14:30:00Z",
"amount": "150.00",
"currency": "BOB",
"status": "PENDING",
"commerceCode": "mi-comercio",
"externalReference": "ORD-2026-00871"
}
{
"detail": "El campo gloss es requerido"
}
{
"detail": "concurrent request"
}
{
"detail": [
{
"type": "greater_than_equal",
"loc": ["body", "amount"],
"msg": "Input should be greater than or equal to 0",
"input": "-5.00"
}
]
}
Genera un código QR de cobro inmediato. El QR puede ser escaneado por cualquier usuario de banca móvil en Bolivia.
Headers
| Header | Tipo | Req | Descripción |
|---|---|---|---|
Authorization | string | Sí | Bearer <tu_api_token> |
Content-Type | string | Sí | application/json |
Idempotency-Key | string | No | UUID v4. Evita cobros duplicados en reintentos. Ventana de 24 h. |
Request Body
| Campo | Tipo | Req | Descripción |
|---|---|---|---|
amount | string (Decimal) | Sí | Monto del cobro. Hasta 12 dígitos con 2 decimales. Mínimo 0.00. |
currency | string | No | Moneda. Solo "BOB". Default: "BOB". |
gloss | string | Sí | Descripción visible del cobro. Entre 3 y 100 caracteres. |
expiration | string | Sí | Vencimiento del QR. Ej: "30m", "2h", "7d", "2026-12-31T23:59:59Z". |
singleUse | boolean | No | Si true, el QR se invalida tras el primer pago. Default: true. |
serviceCode | string | No | Código de clasificación del servicio. Default: "001". Máx. 10 caracteres. |
payerDocument | string | null | No | CI/NIT del pagador esperado. Restringe el QR a ese pagador. Máx. 20 caracteres. |
externalReference | string | null | No | ID interno del comercio (orden, carrito). Devuelto en respuesta y webhooks. Máx. 64 caracteres. |
distribution | object | null | No | Split de fondos {"cuenta": monto}. Solo en CUCU Direct multi-destino. |
metadata | object | null | No | Datos libres del comercio. Devueltos en consulta de estado y webhooks. |
Response
| Campo | Tipo | Descripción |
|---|---|---|
transactionId | string | ID único de la transacción en CUCU. Usar para consultas de estado. |
qrImageUrl | string | null | URL pública CDN de la imagen PNG. null si el CDN falló (usar qrImageBase64). |
qrImageBase64 | string | Imagen del QR como Base64 (PNG). Siempre presente. |
expiresAt | string (ISO 8601) | Fecha y hora de vencimiento en UTC. |
amount | string | Monto confirmado del cobro. |
currency | string | Moneda del cobro. |
status | string | Estado inicial. Siempre "PENDING" al crear. |
commerceCode | string | Slug identificador del comercio en CUCU. |
externalReference | string | null | La referencia externa enviada en el request. |
curl -X POST https://qrsimple.cucu.bo/api/v1/transfers/qr \
-H "Authorization: Bearer <tu_api_token>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"amount": "150.00",
"currency": "BOB",
"gloss": "Pedido #ORD-2026-00871",
"expiration": "30m",
"singleUse": true,
"externalReference": "ORD-2026-00871",
"metadata": {
"orderId": "ORD-2026-00871",
"channel": "web"
}
}'
const response = await fetch('https://qrsimple.cucu.bo/api/v1/transfers/qr', {
method: 'POST',
headers: {
'Authorization': 'Bearer <tu_api_token>',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
amount: '150.00',
currency: 'BOB',
gloss: 'Pedido #ORD-2026-00871',
expiration: '30m',
singleUse: true,
externalReference: 'ORD-2026-00871',
metadata: { orderId: 'ORD-2026-00871', channel: 'web' }
})
});
const data = await response.json();
import uuid, requests
response = requests.post(
'https://qrsimple.cucu.bo/api/v1/transfers/qr',
headers={
'Authorization': 'Bearer <tu_api_token>',
'Content-Type': 'application/json',
'Idempotency-Key': str(uuid.uuid4())
},
json={
'amount': '150.00',
'currency': 'BOB',
'gloss': 'Pedido #ORD-2026-00871',
'expiration': '30m',
'singleUse': True,
'externalReference': 'ORD-2026-00871',
'metadata': {'orderId': 'ORD-2026-00871', 'channel': 'web'}
}
)
print(response.json())
{
"transactionId": "QR2026061500001",
"qrImageUrl": "https://cdn.cucu.bo/qr/cucu-pay/QR2026061500001.png",
"qrImageBase64": "<base64-png>",
"expiresAt": "2026-06-15T14:30:00Z",
"amount": "150.00",
"currency": "BOB",
"status": "PENDING",
"commerceCode": "mi-comercio",
"externalReference": "ORD-2026-00871"
}
{
"detail": "El campo gloss es requerido"
}
{
"detail": "concurrent request"
}
{
"detail": [
{
"type": "greater_than_equal",
"loc": ["body", "amount"],
"msg": "Input should be greater than or equal to 0",
"input": "-5.00"
}
]
}
⌘I