Skip to main content

​
Guía de Integración Rápida

​
Paso 1 — Configuración inicial

  1. Solicita tu X-API-Key al equipo de CUCU.
  2. Registra tu URL de webhook:
curl -X POST https://crypto.cucu.ai/api/v1/merchants/me/webhook \
  -H "X-API-Key: sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-servidor.com/webhooks/cucu-crypto",
    "events": ["payment.confirmed", "payment.failed", "charge.expired"]
  }'
  1. Guarda el secret de la respuesta en tu sistema de secretos (no en código).
  2. Verifica la integración con el evento de prueba: 
curl -X POST https://crypto.cucu.ai/api/v1/merchants/me/webhook/test \
  -H "X-API-Key: sk_live_xxxx"

​
Paso 2 — Flujo de pago

Tu Backend                    CUCU Crypto                   Usuario
     │                              │                           │
     │  POST /merchants/me/charges  │                           │
     │─────────────────────────────►│                           │
     │                              │                           │
     │   { charge_id, checkout_url, │                           │
     │     qrcode_link, expires_at }│                           │
     │◄─────────────────────────────│                           │
     │                              │                           │
     │   Muestra QR / redirect      │                           │
     │──────────────────────────────────────────────────────────►
     │                              │                           │
     │                              │   Usuario paga en USDT    │
     │                              │◄──────────────────────────│
     │                              │                           │
     │   POST webhook               │                           │
     │   payment.confirmed          │                           │
     │◄─────────────────────────────│                           │
     │                              │                           │
     │   Acredita el pedido         │                           │
     │──────────────────────────────────────────────────────────►

​
Paso 3 — Implementa el receptor de webhooks

# FastAPI example
from fastapi import FastAPI, Request, Header, HTTPException
import hmac, hashlib, base64

app = FastAPI()
WEBHOOK_SECRET = "wh_sk_xxxxxxxxxxxxxxxxxxxx"  # desde variable de entorno

@app.post("/webhooks/cucu-crypto")
async def recibir_webhook(
    request: Request,
    webhook_id: str = Header(...),
    webhook_timestamp: str = Header(...),
    webhook_signature: str = Header(...),
    webhook_event: str = Header(...),
):
    body = await request.body()

    # 1. Verificar firma
    mensaje = f"{webhook_id}.{webhook_timestamp}.{body.decode()}"
    firma = base64.b64encode(
        hmac.new(WEBHOOK_SECRET.encode(), mensaje.encode(), hashlib.sha256).digest()
    ).decode()

    if not hmac.compare_digest(firma, webhook_signature.removeprefix("v1,")):
        raise HTTPException(status_code=401, detail="Firma inválida")

    # 2. Idempotencia por webhook_id
    if ya_procesado(webhook_id):
        return {"ok": True}  # 200 para que CUCU no reintente

    # 3. Procesar según el evento
    payload = await request.json()
    if webhook_event == "payment.confirmed":
        acreditar_pedido(payload["metadata"]["invoice_id"])
    elif webhook_event == "charge.expired":
        liberar_stock(payload["charge_id"])

    marcar_procesado(webhook_id)
    return {"ok": True}

​
Consideraciones importantes

  • Idempotencia obligatoria: CUCU puede entregar el mismo evento más de una vez en escenarios de red. Usa webhook-id como clave de deduplicación en tu base de datos.
  • Responde rápido: tu endpoint debe responder en menos de 30 segundos. Si necesitas procesamiento pesado, encola internamente y responde 200 de inmediato.
  • Siempre verifica la firma: nunca proceses un evento sin verificar la firma HMAC.
  • No uses expiration_minutes > 15 para pagos en caja (POS): el usuario debe completar el pago mientras está presente.

​
Ambientes

AmbienteBase URL
Producciónhttps://crypto.cucu.ai/api/v1
Contacta al equipo de CUCU para acceso a un ambiente de staging antes de pasar a producción.