Ciclo de vida de la orden
Desde la creación hasta la captura, la secuencia de llamadas que hacen tu backend y el widget.
Una orden AAPD pasa por cuatro pasos mediados por backend. Tu backend es dueño del paso 1; el widget es dueño de los pasos 2–4 (lo embebes pero no llamas a esos endpoints directo — son internos del widget).
Tu backend SkipPay Widget Financiamiento
│ │ │ │
│ POST /orders │ │ │
│──────────────────►│ │ │
│◄──────────────────│ │ │
│ { hash } │ │ │
│ │ │ │
│ (mintea widget, │ │ │
│ embebe iframe) │ │ │
│ │ │ │
│ │ (valida identidad) │ │
│ │◄────────────────────│ │
│ │ (setup de tarjeta) │ │
│ │◄────────────────────│ │
│ │ │ (setup tarjeta) │
│ │───────────────────────────────────────►│
│ │ (inicio de pago) │ │
│ │◄────────────────────│ │
│ │ │ (flujo préstamo) │
│ │───────────────────────────────────────►│
│ │ │ webhooks │
│ │◄───────────────────────────────────────│
│ │ │ │
│◄──────────────────│ │ │
│ order.changed │ │ │
│ (status paid) │ │ │Paso a paso
| Paso | Qué hace | Auth | Llamador | Doc |
|---|---|---|---|---|
| 1 | Crear la orden (POST /orders) | client_secret | Tu backend | Crear una orden |
| 2 | Validar identidad del cliente | client_id | Widget (interno) | — |
| 3 | Agregar método de pago | client_id | Widget (interno) | — |
| 4 | Iniciar el pago / préstamo | client_id | Widget (interno) | — |
Solo implementas el paso 1 (más el receptor de webhooks). Los pasos 2–4 son trabajo del widget — los gestiona solo cuando lo embebes. Puedes consultar el estado en cualquier momento con GET /orders/{hash}.
Límites de monto
Skip valida el total_amount al crear la orden, antes de que el paciente llegue al widget:
| Límite | Regla | Con el plan 30/70 | Error (400) |
|---|---|---|---|
| Mínimo | La cuota más chica del plan tiene que ser mayor a $1.000 | total_amount ≥ 3.334 | order_installment_amount_below_min |
| Máximo | total_amount ≤ 500.000 | ≤ 500.000 | order_total_amount_above_max |
La cuota se calcula sobre el total_amount que envías, sin la comisión. Las cuotas de muy bajo monto no se pueden financiar, así que una orden bajo el mínimo fallaría al momento del pago. Por eso la rechazamos al crearla: no queda ninguna orden creada.
Pruebas de integración: usa montos de 3.334 o más. Una orden de prueba de $1.000 se rechaza con order_installment_amount_below_min.
Después del pago: envía el gasto (obligatorio)
El pago del 30% no cierra el flujo. Una vez emitida la boleta de la prestación, tu backend debe enviársela a Skip para que presente el reembolso ante la ISAPRE/seguro — es lo que habilita el eventual cobro del 70%. Manda la boleta (obligatoria) con su metadata, y la orden médica si aplica o está disponible, vía POST /api/spot/gastos con skip_pay_order_id = el hash de la orden. Ver Enviar el gasto a Skip.
Ciclo de vida del estado de la orden
pending → paid → refunded| Estado | Cuándo |
|---|---|
pending | Orden creada, sin pago todavía |
paid | Checkout completo: 30% capturado + préstamo del 70% autorizado. La orden queda 100% pagada en los libros de Skip |
refunded | Reembolso total procesado — la hora se canceló después del pago y llamaste a PUT /orders/{hash}/refund |
El schema define además partially_paid, partially_refunded y cancelled, pero hoy las órdenes AAPD no pasan por esos estados. Recibes un webhook en cada cambio de estado — el paid llega exactamente una vez. Ver Webhooks → Catálogo de eventos.
URL base
https://pay.getskip.aiStaging: https://staging.pay.getskip.ai. Ver Conceptos → Ambientes.