POST /charges — Crear Cobro

curl -X POST https://crypto.cucu.ai/api/v1/merchants/me/charges \
  -H "X-API-Key: sk_live_xxxx" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "currency": "USDT",
    "name": "Suscripción Pro",
    "description": "Plan mensual",
    "expiration_minutes": 15,
    "metadata": {"user_id": "usr_abc123"}
  }'

const response = await fetch(
  'https://crypto.cucu.ai/api/v1/merchants/me/charges',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_live_xxxx',
      'Idempotency-Key': crypto.randomUUID(),
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 50.00,
      currency: 'USDT',
      name: 'Suscripción Pro',
      description: 'Plan mensual',
      expiration_minutes: 15,
      metadata: { user_id: 'usr_abc123' }
    })
  }
);
const data = await response.json();

import uuid, requests

response = requests.post(
    'https://crypto.cucu.ai/api/v1/merchants/me/charges',
    headers={
        'X-API-Key': 'sk_live_xxxx',
        'Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'amount': 50.00,
        'currency': 'USDT',
        'name': 'Suscripción Pro',
        'description': 'Plan mensual',
        'expiration_minutes': 15,
        'metadata': {'user_id': 'usr_abc123'}
    }
)
print(response.json())

{
  "charge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CHG-20260125-00042",
  "provider": "cucu_pay",
  "provider_reference": "24572098437",
  "name": "Suscripción Pro",
  "description": "Plan mensual",
  "amount": 50.00,
  "currency": "USDT",
  "status": "created",
  "checkout_url": "https://crypto.cucu.ai/checkout/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payment_url": "https://pay.cucu.ai/p/a1b2c3d4",
  "qrcode_link": null,
  "qr_content": null,
  "deeplink": null,
  "universal_url": null,
  "expires_at": "2026-01-25T15:30:00Z",
  "metadata": {"user_id": "usr_abc123"},
  "created_at": "2026-01-25T15:15:00Z",
  "updated_at": "2026-01-25T15:15:00Z"
}

{
  "detail": "Invalid API Key"
}

{
  "detail": "unsupported currency: XYZ"
}

POST

api

merchants

charges

curl -X POST https://crypto.cucu.ai/api/v1/merchants/me/charges \
  -H "X-API-Key: sk_live_xxxx" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "currency": "USDT",
    "name": "Suscripción Pro",
    "description": "Plan mensual",
    "expiration_minutes": 15,
    "metadata": {"user_id": "usr_abc123"}
  }'

const response = await fetch(
  'https://crypto.cucu.ai/api/v1/merchants/me/charges',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_live_xxxx',
      'Idempotency-Key': crypto.randomUUID(),
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 50.00,
      currency: 'USDT',
      name: 'Suscripción Pro',
      description: 'Plan mensual',
      expiration_minutes: 15,
      metadata: { user_id: 'usr_abc123' }
    })
  }
);
const data = await response.json();

import uuid, requests

response = requests.post(
    'https://crypto.cucu.ai/api/v1/merchants/me/charges',
    headers={
        'X-API-Key': 'sk_live_xxxx',
        'Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'amount': 50.00,
        'currency': 'USDT',
        'name': 'Suscripción Pro',
        'description': 'Plan mensual',
        'expiration_minutes': 15,
        'metadata': {'user_id': 'usr_abc123'}
    }
)
print(response.json())

{
  "charge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CHG-20260125-00042",
  "provider": "cucu_pay",
  "provider_reference": "24572098437",
  "name": "Suscripción Pro",
  "description": "Plan mensual",
  "amount": 50.00,
  "currency": "USDT",
  "status": "created",
  "checkout_url": "https://crypto.cucu.ai/checkout/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payment_url": "https://pay.cucu.ai/p/a1b2c3d4",
  "qrcode_link": null,
  "qr_content": null,
  "deeplink": null,
  "universal_url": null,
  "expires_at": "2026-01-25T15:30:00Z",
  "metadata": {"user_id": "usr_abc123"},
  "created_at": "2026-01-25T15:15:00Z",
  "updated_at": "2026-01-25T15:15:00Z"
}

{
  "detail": "Invalid API Key"
}

{
  "detail": "unsupported currency: XYZ"
}

Genera un cobro crypto. Devuelve la URL de pago y (para CUCU Direct B2B) el QR de Binance listo para mostrar.

Headers

Header	Tipo	Req	Descripción
`X-API-Key`	string	Sí	API Key del merchant
`Content-Type`	string	Sí	`application/json`
`Idempotency-Key`	string	No	String único (UUID recomendado). Evita cobros duplicados en reintentos. Máx. 255 chars.

Request Body

Campo	Tipo	Req	Descripción
`amount`	float	Sí	Monto del cobro. Mayor que 0, máximo 1,000,000.
`currency`	string	Sí	Moneda del cobro. Recomendado: `USDT` o `USDC`. Ver criptomonedas soportadas.
`name`	string	Sí	Nombre del producto o servicio. Máx. 255 chars.
`description`	string	No	Descripción del cobro. Máx. 1024 chars.
`expiration_minutes`	int	No	Minutos hasta expiración. Default: `15`. Rango: 1–60.
`metadata`	object	No	Datos arbitrarios de tu sistema. No se procesan, solo se almacenan y retornan.

Response

Campo	Tipo	Descripción
`charge_id`	string	UUID interno CUCU — úsalo para consultar estado y en tus logs.
`external_id`	string	Referencia legible por humanos.
`provider`	string	Proveedor que procesó el cobro: `cucu_pay` o `binance`.
`status`	string	Estado inicial. Siempre `created`.
`checkout_url`	string	URL de la página de pago CUCU (útil para redirección web).
`payment_url`	string \| null	URL alternativa del proveedor, cuando disponible.
`qrcode_link`	string \| null	URL imagen PNG del QR (CUCU Direct B2B / Binance).
`qr_content`	string \| null	Texto raw del QR — para generarlo en tu frontend.
`deeplink`	string \| null	Deep link para app móvil nativa.
`universal_url`	string \| null	Universal link web — funciona en móvil y desktop.
`expires_at`	string (ISO 8601)	Timestamp de expiración del cobro.
`metadata`	object	Los datos enviados en el request.

curl -X POST https://crypto.cucu.ai/api/v1/merchants/me/charges \
  -H "X-API-Key: sk_live_xxxx" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "currency": "USDT",
    "name": "Suscripción Pro",
    "description": "Plan mensual",
    "expiration_minutes": 15,
    "metadata": {"user_id": "usr_abc123"}
  }'

const response = await fetch(
  'https://crypto.cucu.ai/api/v1/merchants/me/charges',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_live_xxxx',
      'Idempotency-Key': crypto.randomUUID(),
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 50.00,
      currency: 'USDT',
      name: 'Suscripción Pro',
      description: 'Plan mensual',
      expiration_minutes: 15,
      metadata: { user_id: 'usr_abc123' }
    })
  }
);
const data = await response.json();

import uuid, requests

response = requests.post(
    'https://crypto.cucu.ai/api/v1/merchants/me/charges',
    headers={
        'X-API-Key': 'sk_live_xxxx',
        'Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'amount': 50.00,
        'currency': 'USDT',
        'name': 'Suscripción Pro',
        'description': 'Plan mensual',
        'expiration_minutes': 15,
        'metadata': {'user_id': 'usr_abc123'}
    }
)
print(response.json())

{
  "charge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CHG-20260125-00042",
  "provider": "cucu_pay",
  "provider_reference": "24572098437",
  "name": "Suscripción Pro",
  "description": "Plan mensual",
  "amount": 50.00,
  "currency": "USDT",
  "status": "created",
  "checkout_url": "https://crypto.cucu.ai/checkout/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payment_url": "https://pay.cucu.ai/p/a1b2c3d4",
  "qrcode_link": null,
  "qr_content": null,
  "deeplink": null,
  "universal_url": null,
  "expires_at": "2026-01-25T15:30:00Z",
  "metadata": {"user_id": "usr_abc123"},
  "created_at": "2026-01-25T15:15:00Z",
  "updated_at": "2026-01-25T15:15:00Z"
}

{
  "detail": "Invalid API Key"
}

{
  "detail": "unsupported currency: XYZ"
}

Autenticación GET /charges/{id} — Consultar cobro

​Headers

​Request Body

​Response

Headers

Request Body

Response