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

# Crear cargo

> Crea un cargo a una tarjeta del cliente autenticado. Requiere aprobación del cliente vía WhatsApp.

Crea un cargo (débito) a una tarjeta del cliente autenticado. Se envía una solicitud de aprobación al cliente vía WhatsApp. El cargo se ejecuta cuando el cliente aprueba, o expira automáticamente en **5 minutos**.

Usa [GET /customers/session/charges/{id}](show-charge) para consultar el estado del cargo mientras esperas la aprobación.

<Warning>
  Solo se permite **un cargo pendiente** por tarjeta. Si ya existe un cargo en estado `created`, el endpoint retornará error 422.
</Warning>

### Headers

<ParamField header="x-idempotency" type="string" required placeholder="550e8400-e29b-41d4-a716-446655440000">
  Token de idempotencia único (UUID) para evitar cargos duplicados. **Obligatorio** en este endpoint.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token de tu empresa.
</ParamField>

<ParamField header="X-Customer-Token" type="string" required>
  Token de sesión del cliente obtenido en [/customers/login/verify](verify-otp).
</ParamField>

### Body

<ParamField body="payment_method_id" type="string" required placeholder="bb02b2fd-154c-4c90-9fdf-cec3a0b25cf5">
  ID de la tarjeta del cliente. Debe pertenecer al cliente autenticado y coincidir con el modo (test/live).
</ParamField>

<ParamField body="amount" type="integer" required placeholder="50000">
  Monto del cargo en **centavos**. Mínimo: `100` (equivale a \$1 COP).
</ParamField>

<ParamField body="currency" type="string" required placeholder="COP">
  Moneda del cargo. Valores válidos: `COP`, `USD`.
</ParamField>

<ParamField body="description" type="string" required placeholder="Pago mensualidad marzo">
  Descripción del cargo. Máximo 255 caracteres.
</ParamField>

### Flujo de aprobación

```mermaid theme={null}
sequenceDiagram
    participant App as Tu App
    participant API as OnePay API
    participant WA as WhatsApp
    participant User as Cliente

    App->>API: POST /customers/session/charges
    API-->>App: {charge_id, status: "created", expires_at}
    API->>WA: Solicitud de aprobación
    WA->>User: "¿Aprobar cobro de $500 con Visa ····4242?"
    alt Cliente aprueba
        User->>WA: Aprobar
        WA->>API: Aprobación recibida
        API->>API: Procesa el cargo
    else Cliente rechaza
        User->>WA: Rechazar
        WA->>API: Rechazo recibido
        API->>API: Marca como fallido
    else Expira (5 min)
        API->>API: Job marca como fallido
    end
```

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/customers/session/charges \
    -X POST \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "x-customer-token: 12|a1b2c3d4e5f6..." \
    -H "x-idempotency: 550e8400-e29b-41d4-a716-446655440000" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_method_id": "bb02b2fd-154c-4c90-9fdf-cec3a0b25cf5",
      "amount": 50000,
      "currency": "COP",
      "description": "Pago mensualidad marzo"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onepay.la/v1/customers/session/charges', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'X-Customer-Token': '12|a1b2c3d4e5f6...',
      'X-Idempotency': '550e8400-e29b-41d4-a716-446655440000',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      payment_method_id: 'bb02b2fd-154c-4c90-9fdf-cec3a0b25cf5',
      amount: 50000,
      currency: 'COP',
      description: 'Pago mensualidad marzo'
    })
  });

  const charge = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.onepay.la/v1/customers/session/charges',
      headers={
          'Authorization': 'Bearer sk_test_xxx',
          'X-Customer-Token': '12|a1b2c3d4e5f6...',
          'X-Idempotency': '550e8400-e29b-41d4-a716-446655440000',
          'Content-Type': 'application/json'
      },
      json={
          'payment_method_id': 'bb02b2fd-154c-4c90-9fdf-cec3a0b25cf5',
          'amount': 50000,
          'currency': 'COP',
          'description': 'Pago mensualidad marzo'
      }
  )

  charge = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Pendiente de aprobación theme={null}
  {
    "charge_id": "9e02966f-2ddf-4ee7-a391-5b5b7653e232",
    "status": "created",
    "message": "Solicitud de aprobación enviada al cliente vía WhatsApp.",
    "expires_at": "2026-03-16T22:35:00+00:00"
  }
  ```

  ```json 422 - Cargo pendiente existente theme={null}
  {
    "message": "Ya existe un cobro pendiente para este método de pago."
  }
  ```

  ```json 422 - Tarjeta expirada theme={null}
  {
    "message": "El método de pago está expirado."
  }
  ```
</ResponseExample>