Refunds

Refunds devuelven dinero total o parcialmente. En SimplePay, los refunds deben estar anclados a objetos administrados por SimplePay y a tu razon de negocio.

Crear refund

terminal

curl -sS -X POST "https://api.simplepay.mx/v1/refunds" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_3001_refund_partial_v1" \
  -d '{
    "payment_intent": "sppi_0123456789abcdef0123456789abcdef",
    "amount": 50000,
    "reason": "requested_by_customer",
    "metadata": {
      "order_id": "order_3001",
      "support_ticket": "SUP-9001"
    }
  }'

Campos:

Campo	Uso
`payment_intent`	ID SimplePay del pago a reembolsar.
`amount`	Monto parcial en minor units. Omitelo si el flujo permite full refund.
`reason`	`duplicate`, `fraudulent` o `requested_by_customer`.
`metadata`	Referencias no secretas para soporte y reconciliacion.

No construyas refunds publicos con IDs externos no documentados. Usa referencias SimplePay y deja que la API aplique tenant scope, policy y reconciliacion.

Listar refunds

terminal

curl -sS "https://api.simplepay.mx/v1/refunds?limit=25" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY"

Refunds de Bookable Payments

Para una reserva confirmada, usa el endpoint de booking:

terminal

curl -sS -X POST "https://api.simplepay.mx/v1/bookable-payments/bookings/bkg_123/refund" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bkg_123_refund_v1" \
  -d '{
    "amount_minor": 50000,
    "metadata": {
      "reason": "customer_requested"
    }
  }'

Ese flujo actualiza el lifecycle de la reserva y emite eventos Bookable como booking.refunded o booking.partially_refunded.

Checklist

Autoriza internamente

Tu sistema debe decidir si el agente, merchant o usuario tiene permiso para reembolsar.

Usa idempotencia

Una pantalla de soporte puede hacer doble click. Tu refund no debe duplicarse.

Guarda el resultado

Persiste refund ID, amount, payment intent, booking ID si aplica y soporte ticket.

Reconcila con webhook

Trata el webhook o read API como fuente de verdad para estado final.

Quickstarts

Fundamentos

Aceptar pagos

Bookable Payments

Webhooks

LLMs y DX

Crear refund

Listar refunds

Refunds de Bookable Payments

Checklist

​Crear refund

​Listar refunds

​Refunds de Bookable Payments

​Checklist

Crear refund

Listar refunds

Refunds de Bookable Payments

Checklist