> ## 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.

# Introducción

> Gestiona los débitos y cargos autorizados de tus clientes.

## ¿Qué es un Cargo (Charge)?

Un cargo es un **débito directo** a un método de pago que el cliente ya autorizó previamente (tarjeta o cuenta bancaria). El cobro se ejecuta automáticamente sin que el cliente tenga que interactuar.

<Note>
  Si necesitas que el cliente abra un link y elija cómo pagar, usa [Cobros (Payments)](/client/payments/index) en su lugar.
</Note>

## ¿Cuándo usar Cargos?

* Cobros recurrentes a tarjetas o cuentas autorizadas
* Suscripciones y membresías
* Débitos automáticos programados
* Pagos donde ya tienes un método de pago registrado

## Cobros vs Cargos

|                             | Cobro (Payment)         | Cargo (Charge)                                |
| --------------------------- | ----------------------- | --------------------------------------------- |
| **Interacción del cliente** | Abre un link y paga     | Ninguna, es automático                        |
| **Requiere**                | Solo `amount` y `title` | `customer_id` + `card_id` o `account_id`      |
| **Autorización previa**     | No                      | Sí (`authorization: true` al crear el método) |
| **Ideal para**              | Pagos únicos, facturas  | Cobros recurrentes, suscripciones             |

## Flujo de un cargo

1. **Crear un cliente** - [POST /customers](/client/customers/create)
2. **Registrar un método de pago con autorización** - [POST /cards](/client/cards/create) o [POST /accounts](/client/accounts/create) con `authorization: true`
3. **Crear el cargo** - `POST /charges` con el `customer_id` y `card_id` o `account_id`

## Ejemplo rápido

```bash theme={null}
curl https://api.onepay.la/v1/charges \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: cargo-001" \
  -d '{
    "title": "Mensualidad Enero",
    "customer_id": "CUSTOMER_ID",
    "amount": 85000,
    "card_id": "CARD_ID"
  }'
```

## Estados del cargo

| Estado      | Descripción                                                     |
| ----------- | --------------------------------------------------------------- |
| `succeeded` | Cargo procesado exitosamente                                    |
| `declined`  | Cargo rechazado (fondos insuficientes, tarjeta bloqueada, etc.) |
| `pending`   | Cargo en proceso de verificación                                |

## Probar con escenarios

En ambiente test, usa el campo `test_scenario` para simular diferentes resultados:

```json theme={null}
{
  "test_scenario": "INSUFFICIENT_FUNDS"
}
```

Consulta todos los [escenarios de prueba](scenarios) disponibles.

## Casos de uso detallados

Consulta los [casos de uso de débitos automáticos](/client/use-cases/charges) para ver el flujo completo de captura, tokenización y cobro con cada método de pago (tarjetas, cuentas bancarias, Nequi y Daviplata).

## Endpoints

| Método | Endpoint                         | Descripción                   |
| ------ | -------------------------------- | ----------------------------- |
| `POST` | [/charges](create)               | Crear cargo                   |
| `GET`  | [/charges](list)                 | Listar cargos                 |
| `GET`  | [/charges/{id}](detail)          | Detalle de un cargo           |
| `POST` | [/charges/pse](link)             | Crear link de pago PSE        |
| `POST` | [/charges/breb](bre-b)           | Crear cargo Bre-B             |
| `POST` | [/charges/{id}/refund](refund)   | Reembolsar cargo              |
| `POST` | [/charges/{id}/resolve](resolve) | Resolver cargo (solo testing) |