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

# Bookable Payments

> Bookable Payments combina inventario reservable, disponibilidad, holds, checkout hospedado, confirmacion por pago y lifecycle de reservas.

Bookable Payments es el producto de SimplePay para plataformas que venden inventario reservado y necesitan pago para confirmar la reserva.

No es un calendario completo ni un clon de Cal.com. Tu plataforma conserva login, discovery, UI de calendario y experiencia comercial. SimplePay se encarga de la primitiva critica: disponibilidad, hold temporal, checkout, confirmacion por pago y eventos.

## Cuando usarlo

Usa Bookable Payments para:

* Citas y servicios con staff.
* Clases con cupo.
* Tours y experiencias con horarios.
* Rentals por unidad o ventana.
* Ofertas programadas con capacidad.
* Reservas donde el pago decide si el inventario queda confirmado.

## Flujo canonico

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
  participant App as Merchant app
  participant API as SimplePay API
  participant Checkout as SimplePay Checkout
  participant Webhook as Merchant webhook

  App->>API: Sync customer/product/availability
  App->>API: List slots
  App->>API: Create hold
  App->>API: Convert hold to checkout
  API-->>App: booking pending + checkout URL
  App->>Checkout: Redirect customer
  Checkout-->>API: Payment result
  API-->>Webhook: booking.confirmed or booking.expired
  Webhook-->>App: Persist final booking state
```

## Objetos principales

| Objeto                  | Que representa                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------- |
| `product`               | Lo que vendes en el catalogo del tenant.                                                    |
| `booking_resource`      | Staff, espacio, inventario, unidad, vehiculo, equipo o pool de capacidad.                   |
| `availability_schedule` | Horario recurrente.                                                                         |
| `availability_rule`     | Regla por weekday y ventana horaria.                                                        |
| `availability_override` | Apertura, cierre o capacidad especial en fechas concretas.                                  |
| `booking_blackout`      | Bloqueo de disponibilidad por producto, event type, recurso o schedule.                     |
| `booking_event_type`    | Superficie reservable canonica: duracion, capacidad, slug, recursos, schedules, pago.       |
| `booking_hold`          | Reserva temporal que protege inventario mientras el cliente paga.                           |
| `booking`               | Reserva creada y confirmada, expirada, cancelada, reprogramada o reembolsada por lifecycle. |

## Estados importantes

| Estado        | Significado                                               |
| ------------- | --------------------------------------------------------- |
| `held`        | Inventario protegido temporalmente.                       |
| `pending`     | Booking creado con checkout, esperando resultado de pago. |
| `confirmed`   | Pago confirmado, inventario finalizado.                   |
| `expired`     | Checkout o hold expiro.                                   |
| `cancelled`   | Reserva cancelada o pago fallo.                           |
| `rescheduled` | Reserva movida a otro horario.                            |
| `no_show`     | Cliente no llego, marcado por API.                        |
| `refunded`    | Pago devuelto.                                            |

<Info>
  El browser redirect no confirma una reserva. Tu app debe esperar
  `booking.confirmed` o leer el booking hasta `status=confirmed`.
</Info>

## Dos maneras de integrar

<Columns cols={2}>
  <Card title="Shortcut setup" icon="wand-sparkles" href="/bookable-payments/quickstart">
    Crea product, price, resource, schedule y event type con `POST
            /v1/bookable-payments/setup`.
  </Card>

  <Card title="Setup manual" icon="settings-2" href="/bookable-payments/model">
    Controla cada objeto por separado para marketplaces, imports o
    configuradores avanzados.
  </Card>
</Columns>

## Scopes minimos

Para un flujo completo de Scheduled Offer en sandbox:

```txt scopes theme={"theme":{"light":"github-light","dark":"github-dark"}}
products:read
products:write
customer_hub:write
availability:read
availability:write
bookings:read
bookings:write
webhooks:write
```

## Preflight

Antes de construir la UI, pide a SimplePay el plan del tenant:

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS "https://api.simplepay.mx/v1/bookable-payments/preflight?use_case=scheduled_offer" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY"
```

Preflight detecta readiness de API key, tenant environment, cuentas de pago, webhooks y pasos faltantes.