> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /charges — Crear Cobro

> Genera un cobro crypto. Devuelve la URL de pago y el QR listo para mostrar.

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](/payments/crypto/criptomonedas). |
| `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.                              |

<RequestExample>
  ```bash cURL theme={"system"}
  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"}
    }'
  ```

  ```javascript JavaScript theme={"system"}
  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();
  ```

  ```python Python theme={"system"}
  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())
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={"system"}
  {
    "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"
  }
  ```

  ```json 401 Unauthorized theme={"system"}
  {
    "detail": "Invalid API Key"
  }
  ```

  ```json 422 Unprocessable Entity theme={"system"}
  {
    "detail": "unsupported currency: XYZ"
  }
  ```
</ResponseExample>