Checkout por compra
Genera una sesión de checkout de Polar por cada pedido sobre un link existente.
Genera una sesión de checkout de Polar sobre un link existente y te devuelve un checkoutUrl listo para redirigir al cliente.
Es el caso de uso "link reutilizable que se paga N veces": cada llamada crea una sesión nueva, con el email del comprador precargado y tu referencia del pedido. Polar es el Merchant of Record: cobra, calcula el impuesto y le manda el comprobante al comprador. La venta aparece como orden cuando el comprador paga, y se dispara el webhook payment.completed.
En un link one_time el checkout cobra el monto del link. En un link recurring lleva directo al plan indicado con price_id (o al default), sin pasar por el selector de planes de la página pública url (/p/{slug}). Ver Suscripciones.
Request
POST /api/v1/payment-links/{id}/checkout
Headers
| Header | Valor |
|---|---|
Authorization | Bearer vxp_live_tu_clave |
Content-Type | application/json |
Vexor-Account | opcional — id del usuario conectado, para cobrar un link suyo (cuentas conectadas) |
Idempotency-Key no aplica: cada llamada crea una sesión de checkout nueva.
Body
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
reference | string | no | Tu referencia del pedido (p. ej. ORD-1001, hasta 200 caracteres). Si se omite, se genera una única (VXP-…). Vuelve en la respuesta, en la venta (reference de GET /orders), en sus webhooks y en /events. |
customer_email | string | no | Email del comprador (precarga el checkout). |
metadata | object | no | Pares clave/valor del pedido. Sólo valores planos: texto, número o booleano. Vuelven en la metadata de la venta. |
price_id | string | no | Solo para links recurring: id del plan (prices[].id) al que se suscribe el comprador. Ausente = plan default (isDefault o el primero). En un link one_time responde 400 validation_error. |
seats | integer | no | Solo para planes per_seat: cuántos asientos compra el comprador. Si se omite, se compran los minSeats del plan. |
Ejemplo
curl https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5/checkout \
-X POST \
-H "Authorization: Bearer vxp_live_tu_clave" \
-H "Content-Type: application/json" \
-d '{
"reference": "ORD-1001",
"customer_email": "cliente@mail.com",
"metadata": { "userId": "u_42" }
}'Respuesta exitosa
200 OK
{
"provider": "polar",
"polarCheckoutId": "8f6c1d2e-...",
"price_id": null,
"seats": null,
"checkoutUrl": "https://buy.polar.sh/polar_c_...",
"expiresAt": "2026-01-02T13:00:00.000Z"
}Redirige al cliente a checkoutUrl antes de expiresAt. La venta llega como orden de Polar (GET /api/v1/orders). price_id es null en links de pago único y seats es null salvo en planes por asiento.
Links recurrentes: checkout directo a un plan
En un link recurring, manda el price_id del plan (o nada para el default):
curl https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5/checkout \
-X POST \
-H "Authorization: Bearer vxp_live_tu_clave" \
-H "Content-Type: application/json" \
-d '{ "price_id": "66f1c1e2c8a4b0d1f2e3a4c1" }'{
"provider": "polar",
"polarCheckoutId": "8f6c1d2e-...",
"price_id": "66f1c1e2c8a4b0d1f2e3a4c1",
"seats": null,
"checkoutUrl": "https://buy.polar.sh/polar_c_...",
"expiresAt": "2026-01-02T13:00:00.000Z"
}Cuando el comprador paga, Polar crea la suscripción y la cobra cada ciclo (webhooks subscription.created y subscription.payment.completed; ver Suscripciones).
Errores
| Error | HTTP | Causa |
|---|---|---|
link_not_found | 404 | No existe ese link de pago, no está activo o es de otro modo (prueba/producción). |
price_not_found | 404 | price_id no existe o no pertenece a ese link recurrente. |
validation_error | 400 | price_id en un link de pago único, u otro dato inválido. |
invalid_request | 400 | El body no es JSON válido. |
invalid_seats | 400 | seats fuera de minSeats/maxSeats del plan, o seats en un plan de precio fijo. |
prices_required | 400 | El link recurrente no tiene planes. |
polar_link_not_editable_yet | 409 | El link todavía se está creando en Polar: reintenta en unos segundos. |
polar_reconnect_required | 409 | La conexión con Polar es anterior al checkout por API: el creador tiene que volver a conectar Polar desde el dashboard. |
polar_checkout_failed | 502 | Polar no creó el checkout. Reintenta en unos minutos. |