Hosted Checkout

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

terminal

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.

No guardes secrets, tokens, PANs, credenciales externas ni datos sensibles en metadata.

Redireccion

route-handler.ts

const session = await createSimplePayCheckout(order);

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

En frontend:

checkout-button.ts

window.location.assign(checkoutUrl);

Confirmacion

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

terminal

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:

request

{
  "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"
  }
}

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.

Patron de orden

Crea tu orden local

status=pending_payment, monto calculado y carrito congelado.

Crea Checkout Session

Usa una idempotency key derivada de la orden.

Guarda `spcs_...`

Persiste session.id, session.url, client_reference_id y monto esperado.

Redirige

Manda al cliente a la URL de SimplePay.

Confirma por webhook

Actualiza la orden solo cuando recibas el evento de exito o una lectura confirmada.

Referencia

Consulta POST /v1/hosted-checkout/sessions y GET /v1/hosted-checkout/sessions/{id} en la API Reference.

Quickstarts

Fundamentos

Aceptar pagos

Bookable Payments

Webhooks

LLMs y DX

Cuando usarlo

Crear una sesion

Redireccion

Confirmacion

Installments y pricing

Patron de orden

Referencia

​Cuando usarlo

​Crear una sesion

​Redireccion

​Confirmacion

​Installments y pricing

​Patron de orden

​Referencia

Cuando usarlo

Crear una sesion

Redireccion

Confirmacion

Installments y pricing

Patron de orden

Referencia