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

# Sesión de cliente

> Permite a tus clientes autenticarse con OTP y operar con sus métodos de pago de forma segura.

## ¿Qué es la Sesión de Cliente?

La sesión de cliente permite que tus usuarios finales se autentiquen directamente desde tu aplicación usando su número de teléfono (OTP vía WhatsApp). Una vez autenticados, obtienen un **token temporal** con el que pueden:

* Consultar sus métodos de pago (tarjetas, billeteras, PSE)
* Registrar nuevas tarjetas (tokenización)
* Autorizar cargos con aprobación vía WhatsApp

<Warning>
  Este flujo está diseñado para que el **cliente final** opere directamente. La autenticación es con OTP, no con las API keys de tu empresa.
</Warning>

## Flujo de autenticació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/login/request {phone}
    API->>WA: Envía OTP
    WA->>User: Código de verificación
    User->>App: Ingresa OTP
    App->>API: POST /customers/login/verify {phone, otp}
    API-->>App: {token, expires_at, customer}
    App->>API: GET /customers/session/payment-methods
    Note over App,API: Header: X-Customer-Token
```

## Autenticación dual

Los endpoints de sesión requieren **dos tokens** en los headers:

| Header             | Descripción                                                |
| ------------------ | ---------------------------------------------------------- |
| `Authorization`    | Bearer token de tu empresa (`sk_test_xxx` o `sk_live_xxx`) |
| `X-Customer-Token` | Token del cliente obtenido en `/customers/login/verify`    |

## Modo test vs live

* Usa `sk_test_xxx` para modo test. El OTP se retorna directamente en la respuesta.
* Usa `sk_live_xxx` para modo live. El OTP se envía por WhatsApp al cliente.
* Los métodos de pago y cargos se filtran automáticamente según el modo.

## Endpoints

| Método | Endpoint                                                    | Descripción                   |
| ------ | ----------------------------------------------------------- | ----------------------------- |
| `POST` | [/customers/login/request](request-otp)                     | Solicitar OTP                 |
| `POST` | [/customers/login/verify](verify-otp)                       | Verificar OTP y obtener token |
| `GET`  | [/customers/session/payment-methods](list-payment-methods)  | Listar métodos de pago        |
| `POST` | [/customers/session/payment-methods](create-payment-method) | Tokenizar tarjeta             |
| `POST` | [/customers/session/charges](create-charge)                 | Crear cargo con aprobación    |
| `GET`  | [/customers/session/charges/{id}](show-charge)              | Consultar estado de un cargo  |