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"
}
Endpoints
POST /charges — Crear Cobro
Genera un cobro crypto. Devuelve la URL de pago y el QR listo para mostrar.
POST
/
api
/
v1
/
merchants
/
me
/
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"
}
⌘I