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

# Checkout Bookable

> Como convertir un slot en hold, checkout, booking pending y confirmacion final por pago en Bookable Payments.

El checkout Bookable conecta inventario y pago. El objetivo es que un cliente no pueda pagar por un slot que ya no existe, y que un slot no quede confirmado si el pago falla.

## Opcion A: booking checkout atomico

Usa esta opcion para la mayoria de integraciones.

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://api.simplepay.mx/v1/bookable-payments/bookings" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking_checkout_cart_789_v1" \
  -d '{
    "event_type_slug": "experiencia-isla",
    "starts_at": "2026-07-10T15:00:00.000Z",
    "quantity": 2,
    "success_url": "https://merchant.example.com/bookings/success",
    "cancel_url": "https://merchant.example.com/bookings/cancel",
    "customer": {
      "external_provider": "customer_platform",
      "external_id": "user_123",
      "email": "guest@example.com",
      "name": "Guest One"
    },
    "form_responses": {
      "dietary_notes": "vegetarian"
    },
    "metadata": {
      "cart_id": "cart_789"
    }
  }'
```

Respuesta esperada:

```json response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "booking": {
    "id": "00000000-0000-4000-8000-000000000010",
    "status": "pending",
    "paymentStatus": "unpaid",
    "quantity": 2
  },
  "checkout_session": {
    "id": "spcs_0123456789abcdef0123456789abcdef",
    "url": "https://checkout.simplepay.mx/checkout/spcs_0123456789abcdef0123456789abcdef"
  }
}
```

## Opcion B: hold y checkout separados

Usa esta opcion si tu UX separa seleccion, formulario y pago.

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
HOLD_ID="$(
  curl -sS -X POST "https://api.simplepay.mx/v1/bookable-payments/holds" \
    -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: hold_cart_789_v1" \
    -d '{
      "event_type_slug": "experiencia-isla",
      "starts_at": "2026-07-10T15:00:00.000Z",
      "quantity": 2,
      "hold_minutes": 15,
      "customer": {
        "external_provider": "customer_platform",
        "external_id": "user_123"
      }
    }' | jq -r '.id'
)"
```

Convertir a pago:

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://api.simplepay.mx/v1/bookable-payments/holds/$HOLD_ID/payment" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hold_cart_789_payment_v1" \
  -d '{
    "success_url": "https://merchant.example.com/bookings/success",
    "cancel_url": "https://merchant.example.com/bookings/cancel",
    "metadata": {
      "cart_id": "cart_789"
    }
  }'
```

## Confirmacion de pago

| Resultado de pago     | Booking     | Hold        | Accion merchant                         |
| --------------------- | ----------- | ----------- | --------------------------------------- |
| Checkout completado   | `confirmed` | `converted` | Entrega confirmacion, voucher o acceso. |
| Checkout expirado     | `expired`   | `expired`   | Libera UI local e invita a reintentar.  |
| Pago async fallido    | `cancelled` | `released`  | No entregues acceso.                    |
| PaymentIntent fallido | `cancelled` | `released`  | No entregues acceso.                    |

## Leer booking

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS "https://api.simplepay.mx/v1/bookable-payments/bookings/00000000-0000-4000-8000-000000000010" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY"
```

## Mutaciones operativas

| Accion         | Endpoint                                              |
| -------------- | ----------------------------------------------------- |
| Cancelar       | `POST /v1/bookable-payments/bookings/{id}/cancel`     |
| Reprogramar    | `POST /v1/bookable-payments/bookings/{id}/reschedule` |
| Marcar no-show | `POST /v1/bookable-payments/bookings/{id}/no_show`    |
| Reembolsar     | `POST /v1/bookable-payments/bookings/{id}/refund`     |

## Reprogramar

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://api.simplepay.mx/v1/bookable-payments/bookings/00000000-0000-4000-8000-000000000010/reschedule" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bkg_10_reschedule_20260711_v1" \
  -d '{
    "starts_at": "2026-07-11T15:00:00.000Z",
    "reason": "customer_requested"
  }'
```

## Reembolso de booking

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://api.simplepay.mx/v1/bookable-payments/bookings/00000000-0000-4000-8000-000000000010/refund" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bkg_10_refund_v1" \
  -d '{
    "amount_minor": 90000,
    "metadata": {
      "support_ticket": "SUP-1001"
    }
  }'
```

<Check>
  El flujo correcto es: slot disponible, hold, checkout, booking pending,
  webhook de confirmacion, booking confirmed.
</Check>