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

# Hosted Checkout

> Integra Checkout Sessions de SimplePay para redirigir clientes a una pagina de pago hospedada y confirmar el resultado con webhooks.

Hosted Checkout es la forma mas rapida y segura de aceptar pagos con SimplePay. Tu backend crea una Checkout Session, SimplePay devuelve una URL en `https://checkout.simplepay.mx`, y tu app redirige al cliente.

## Cuando usarlo

Usa Hosted Checkout cuando:

* Quieres salir a produccion rapido.
* No quieres manejar UI sensible de pago.
* Necesitas tarjetas, OXXO, SPEI o installments segun tu politica.
* Quieres que SimplePay conserve un registro claro de pricing, tenant policy y payment surface.

## Crear una sesion

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://api.simplepay.mx/v1/hosted-checkout/sessions" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_2001_checkout_v1" \
  -d '{
    "currency": "mxn",
    "success_url": "https://app.example.com/orders/2001/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://app.example.com/orders/2001",
    "client_reference_id": "order_2001",
    "customer_email": "buyer@example.com",
    "line_items": [
      {
        "name": "Plan Pro mensual",
        "amount": 149900,
        "quantity": 1
      }
    ],
    "payment_method_types": ["card"],
    "metadata": {
      "order_id": "order_2001",
      "tenant_cart_version": "v3"
    }
  }'
```

Campos clave:

| Campo                 | Requerido | Uso                                                               |
| --------------------- | --------- | ----------------------------------------------------------------- |
| `currency`            | Si        | Codigo ISO en minusculas. Para Mexico normalmente `mxn`.          |
| `line_items`          | Si        | Uno o mas items con `name`, `amount` en minor units y `quantity`. |
| `success_url`         | Si        | Donde regresa el cliente si completa el flujo de checkout.        |
| `cancel_url`          | No        | Donde regresa si abandona o cancela.                              |
| `client_reference_id` | No        | Tu ID de orden, invoice, booking o carrito.                       |
| `metadata`            | No        | Datos no secretos para reconciliacion.                            |

<Warning>
  No guardes secrets, tokens, PANs, credenciales externas ni datos sensibles en
  `metadata`.
</Warning>

## Redireccion

```ts route-handler.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const session = await createSimplePayCheckout(order);

return Response.json({
  checkoutUrl: session.url,
  checkoutSessionId: session.id,
});
```

En frontend:

```ts checkout-button.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
window.location.assign(checkoutUrl);
```

## Confirmacion

El `success_url` es solo UX. Tu backend debe confirmar con webhooks o read API.

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS "https://api.simplepay.mx/v1/hosted-checkout/sessions/spcs_0123456789abcdef0123456789abcdef" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY"
```

## Installments y pricing

Si tu tenant tiene installments habilitados, puedes pedir una estrategia compatible:

```json request theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "currency": "mxn",
  "success_url": "https://app.example.com/success",
  "line_items": [{ "name": "Curso", "amount": 600000, "quantity": 1 }],
  "payment_method_types": ["card"],
  "installments": {
    "enabled": true,
    "months": 6,
    "pricing_strategy": "payer_transparent"
  }
}
```

<Info>
  La politica del tenant decide si installments, montos, metodos y live mode
  estan permitidos. Si quieres predecir la decision antes de crear checkout, usa
  `/v1/payment-policy/evaluate`.
</Info>

## Patron de orden

<Steps>
  <Step title="Crea tu orden local">
    `status=pending_payment`, monto calculado y carrito congelado.
  </Step>

  <Step title="Crea Checkout Session">
    Usa una idempotency key derivada de la orden.
  </Step>

  <Step title="Guarda `spcs_...`">
    Persiste `session.id`, `session.url`, `client_reference_id` y monto
    esperado.
  </Step>

  <Step title="Redirige">Manda al cliente a la URL de SimplePay.</Step>

  <Step title="Confirma por webhook">
    Actualiza la orden solo cuando recibas el evento de exito o una lectura
    confirmada.
  </Step>
</Steps>

## Referencia

Consulta `POST /v1/hosted-checkout/sessions` y `GET /v1/hosted-checkout/sessions/{id}` en la [API Reference](/api-reference/overview).