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

# Quickstart

> Crea tu primer pago en SimplePay con una sandbox key, una Checkout Session, redireccion segura y verificacion basica del estado.

Este quickstart crea una Hosted Checkout Session y te da una URL de pago hospedada por SimplePay.

## Antes de empezar

Necesitas:

* Una cuenta en el dashboard de SimplePay.
* Una API key de sandbox con formato `spk_sandbox_...`.
* Un backend donde puedas guardar secrets y llamar a `https://api.simplepay.mx`.
* Una URL de exito y una URL de cancelacion en tu app.

<Warning>
  Nunca llames la API secreta de SimplePay desde el navegador ni desde apps
  moviles. Tu API key vive en el backend.
</Warning>

## 1. Configura variables

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
export SIMPLEPAY_API_BASE="https://api.simplepay.mx"
export SIMPLEPAY_API_KEY="spk_sandbox_..."
```

## 2. Crea la sesion

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "$SIMPLEPAY_API_BASE/v1/hosted-checkout/sessions" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart_order_001" \
  -d '{
    "currency": "mxn",
    "success_url": "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://example.com/cancel",
    "client_reference_id": "quickstart_order_001",
    "line_items": [
      {
        "name": "Producto demo",
        "amount": 50000,
        "quantity": 1
      }
    ],
    "customer_email": "cliente@example.com",
    "payment_method_types": ["card"],
    "metadata": {
      "order_id": "quickstart_order_001"
    }
  }'
```

La respuesta incluye un `id` de SimplePay y una `url`:

```json response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "spcs_0123456789abcdef0123456789abcdef",
  "object": "checkout.session",
  "status": "open",
  "amount_total": 50000,
  "url": "https://checkout.simplepay.mx/checkout/spcs_0123456789abcdef0123456789abcdef"
}
```

## 3. Redirige al cliente

En tu backend, devuelve `session.url` a tu frontend. En el navegador, redirige:

```js browser theme={"theme":{"light":"github-light","dark":"github-dark"}}
window.location.href = session.url;
```

## 4. Verifica el estado

Despues del pago, SimplePay puede redirigir al cliente a `success_url`, pero el redirect no debe ser tu fuente de verdad.

Usa una de estas opciones:

* Webhook de SimplePay para actualizar tu orden.
* Read API de la Checkout Session si necesitas mostrar un estado provisional.
* Reconciliacion por tus registros internos si el webhook llega despues del redirect.

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

<Check>
  Cuando pases a produccion, repite el flujo con una live key y webhooks activos
  antes de habilitar traffic real.
</Check>

## Siguiente paso

<Columns cols={2}>
  <Card title="Autenticacion" icon="key-round" href="/essentials/authentication">
    Como usar API keys, scopes y headers de forma segura.
  </Card>

  <Card title="Webhooks" icon="radio" href="/webhooks/overview">
    Confirma pagos y reservas desde eventos idempotentes.
  </Card>
</Columns>