POST /transfers/qr — Crear transacción 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"
    }
  ]
}

POST

api

transfers

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"
    }
  ]
}

Idempotencia GET /transfers/qr/{id} — Consultar estado

​Headers

​Request Body

​Response

Headers

Request Body

Response