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

# Consultar cargo

> Consulta el estado y detalle de un cargo creado en la sesión del cliente.

Consulta el estado actual de un cargo previamente creado con [POST /customers/session/charges](create-charge). Útil para hacer polling del estado del cargo mientras el cliente aprueba o rechaza vía WhatsApp.

<Note>
  Solo puedes consultar cargos que pertenezcan al cliente autenticado. Intentar consultar un cargo de otro cliente retorna 404.
</Note>

### Headers

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

### Path Parameters

<ParamField path="chargeId" type="string" required placeholder="9e02966f-2ddf-4ee7-a391-5b5b7653e232">
  ID del cargo a consultar. Retornado al crear el cargo con `POST /customers/session/charges`.
</ParamField>

### Response

<ResponseField name="charge_id" type="string">
  Identificador único del cargo.
</ResponseField>

<ResponseField name="status" type="string">
  Estado actual del cargo. Valores posibles:

  * `created` — Pendiente de aprobación
  * `paid` — Aprobado y cobrado exitosamente
  * `failed` — Rechazado o expirado
</ResponseField>

<ResponseField name="amount" type="integer">
  Monto del cargo en **centavos**.
</ResponseField>

<ResponseField name="currency" type="string">
  Moneda del cargo (`COP`, `USD`).
</ResponseField>

<ResponseField name="description" type="string">
  Descripción del cargo.
</ResponseField>

<ResponseField name="remarks" type="string | null">
  Motivo del fallo cuando `status` es `failed`. `null` en otros estados.
</ResponseField>

<ResponseField name="paid_at" type="string | null">
  Fecha y hora del pago en formato ISO 8601. `null` si aún no ha sido pagado.
</ResponseField>

<ResponseField name="created_at" type="string">
  Fecha y hora de creación del cargo en formato ISO 8601.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/customers/session/charges/9e02966f-2ddf-4ee7-a391-5b5b7653e232 \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "x-customer-token: 12|a1b2c3d4e5f6..."
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.onepay.la/v1/customers/session/charges/9e02966f-2ddf-4ee7-a391-5b5b7653e232',
    {
      headers: {
        'Authorization': 'Bearer sk_test_xxx',
        'X-Customer-Token': '12|a1b2c3d4e5f6...'
      }
    }
  );

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

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

  response = requests.get(
      'https://api.onepay.la/v1/customers/session/charges/9e02966f-2ddf-4ee7-a391-5b5b7653e232',
      headers={
          'Authorization': 'Bearer sk_test_xxx',
          'X-Customer-Token': '12|a1b2c3d4e5f6...'
      }
  )

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

<ResponseExample>
  ```json 200 - Cargo pendiente theme={null}
  {
    "charge_id": "9e02966f-2ddf-4ee7-a391-5b5b7653e232",
    "status": "created",
    "amount": 50000,
    "currency": "COP",
    "description": "Pago mensualidad marzo",
    "remarks": null,
    "paid_at": null,
    "created_at": "2026-03-17T21:30:00+00:00"
  }
  ```

  ```json 200 - Cargo aprobado theme={null}
  {
    "charge_id": "9e02966f-2ddf-4ee7-a391-5b5b7653e232",
    "status": "paid",
    "amount": 50000,
    "currency": "COP",
    "description": "Pago mensualidad marzo",
    "remarks": null,
    "paid_at": "2026-03-17T21:32:15+00:00",
    "created_at": "2026-03-17T21:30:00+00:00"
  }
  ```

  ```json 200 - Cargo fallido/expirado theme={null}
  {
    "charge_id": "9e02966f-2ddf-4ee7-a391-5b5b7653e232",
    "status": "failed",
    "amount": 50000,
    "currency": "COP",
    "description": "Pago mensualidad marzo",
    "remarks": "CUSTOMER_APPROVAL_EXPIRED",
    "paid_at": null,
    "created_at": "2026-03-17T21:30:00+00:00"
  }
  ```

  ```json 404 - Cargo no encontrado theme={null}
  {
    "message": "Cargo no encontrado."
  }
  ```
</ResponseExample>