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

# Ambientes y keys

> Diferencias entre sandbox y live, como preparar credenciales, como pensar en tenant environments y que validar antes de procesar dinero real.

SimplePay separa integraciones por tenant y ambiente. Para developers, eso se traduce en una regla simple: todo se prueba con sandbox antes de procesar live.

## Modelo mental

| Capa        | Que representa                                     | Ejemplo                            |
| ----------- | -------------------------------------------------- | ---------------------------------- |
| Tenant      | La cuenta o comercio dentro de SimplePay.          | `Acme Tours MX`                    |
| Environment | El modo operativo del tenant.                      | `sandbox`, `live`                  |
| API key     | Credencial con scopes para un environment.         | `spk_sandbox_...`                  |
| Policy      | Reglas de elegibilidad, limites y metodos de pago. | MXN, cards, installments, velocity |

## Sandbox

Usa sandbox para:

* Probar request bodies.
* Conectar `success_url` y `cancel_url`.
* Crear webhooks y verificar idempotencia.
* Probar Bookable holds, slots y checkouts.
* Validar policy preflight antes de habilitar live.

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

## Live

Live requiere que tu integracion tenga:

* API key live emitida para el tenant correcto.
* Webhooks configurados en HTTPS.
* Manejo idempotente de eventos.
* Politicas de pago habilitadas para los productos y metodos que vas a usar.
* Observabilidad suficiente para rastrear orden, checkout, payment intent y booking.

<Warning>
  No cambies a live solo reemplazando la key en una app que no ha pasado por
  webhooks. El pago puede completarse aunque tu redirect falle.
</Warning>

## Checklist antes de live

<Steps>
  <Step title="Revisa scopes">
    La key debe tener exactamente los scopes necesarios. Si la app solo crea
    checkouts, no necesita escribir schedules Bookable.
  </Step>

  <Step title="Prueba idempotencia">
    Repite la misma solicitud con el mismo `Idempotency-Key` y verifica que no
    duplica orden, hold, booking o refund.
  </Step>

  <Step title="Prueba webhooks duplicados">
    Tu handler debe aceptar el mismo event ID mas de una vez sin repetir side
    effects.
  </Step>

  <Step title="Guarda referencias">
    Persiste `client_reference_id`, IDs SimplePay, IDs de booking y event IDs.
  </Step>

  <Step title="Corre policy preflight">
    Para flujos Bookable o productos regulados, usa
    `/v1/payment-policy/evaluate` o preflight Bookable.
  </Step>
</Steps>

## Variables recomendadas

```bash .env theme={"theme":{"light":"github-light","dark":"github-dark"}}
SIMPLEPAY_API_BASE=https://api.simplepay.mx
SIMPLEPAY_API_KEY=spk_sandbox_...
SIMPLEPAY_WEBHOOK_SECRET=whsec_...
SIMPLEPAY_CHECKOUT_SUCCESS_URL=https://app.example.com/payments/success
SIMPLEPAY_CHECKOUT_CANCEL_URL=https://app.example.com/payments/cancel
```

<Tip>
  Nombra tus idempotency keys con el ID de tu sistema: `order_123_checkout_v1`,
  `booking_456_refund_v1`, `customer_platform_abc_sync_v1`.
</Tip>