Idempotencia

La idempotencia permite reintentar una operacion cuando hay timeouts, errores de red o procesos duplicados sin crear multiples objetos de negocio. SimplePay acepta el header Idempotency-Key en operaciones write.

request

Idempotency-Key: order_1001_checkout_v1

Cuando usarlo

Usalo en:

POST /v1/hosted-checkout/sessions
POST /v1/payment-links
POST /v1/refunds
POST /v1/products
POST /v1/customer-hub/customers y demas writes /v1/customer-hub/*
POST /v1/bookable-payments/setup
POST /v1/bookable-payments/holds
POST /v1/bookable-payments/holds/{id}/payment
POST /v1/bookable-payments/bookings
Cualquier create, update o lifecycle mutation Bookable.

Buenas keys

Operacion	Ejemplo
Checkout de orden	`order_1001_checkout_v1`
Link de pago	`invoice_2026_0007_payment_link_v1`
Sync de customer	`customer_platform_user_abc_sync_v1`
Hold Bookable	`tour_2026_07_10_0900_hold_user_abc_v1`
Booking refund	`booking_bkg_123_refund_full_v1`

Malas keys

Evita keys aleatorias si tu backend puede reintentar el mismo trabajo desde cero.

bad

random_uuid_each_retry
Date.now()
Math.random()

Usa keys deterministicas derivadas de tu entidad de negocio.

Patron recomendado

Crea una entidad local pendiente

Por ejemplo orders.status = pending_payment.

Genera una key deterministica

Usa el ID local y una version de operacion: order_1001_checkout_v1.

Llama SimplePay

Incluye Idempotency-Key y guarda el ID que responde SimplePay.

Reintenta con la misma key

Si hay timeout, repite exactamente la misma operacion con la misma key.

idempotent-checkout.ts

const idempotencyKey = `${order.id}_checkout_v1`;

const response = await fetch("https://api.simplepay.mx/v1/hosted-checkout/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIMPLEPAY_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify({
    currency: "mxn",
    success_url: order.successUrl,
    cancel_url: order.cancelUrl,
    client_reference_id: order.id,
    line_items: order.items.map((item) => ({
      name: item.name,
      amount: item.amountMinor,
      quantity: item.quantity,
    })),
  }),
});

No reutilices la misma key para operaciones semanticamente distintas. Si cambias monto, producto o cliente, incrementa la version de la key.

Quickstarts

Fundamentos

Aceptar pagos

Bookable Payments

Webhooks

LLMs y DX

Cuando usarlo

Buenas keys

Malas keys

Patron recomendado

​Cuando usarlo

​Buenas keys

​Malas keys

​Patron recomendado

Cuando usarlo

Buenas keys

Malas keys

Patron recomendado