Checkout por compra
Genera una sesión de checkout por cada pedido sobre un link existente.
Genera una sesión de checkout 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. El cobro se hace en tu cuenta de cobro y el comprador recibe el recibo por email. 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. |
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
{
"checkoutId": "ch_4f8a2c9d1e7b",
"reference": "ORD-1001",
"price_id": null,
"checkoutUrl": "https://…",
"expiresAt": null
}Redirige al cliente a checkoutUrl (si expiresAt no es null, antes de esa fecha). reference es la tuya o la generada; checkoutId vuelve en la venta (checkoutId de GET /api/v1/orders). price_id es null en links de pago único. En los pagos únicos el comprador puede pagar en su moneda local o en USD.
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" }'{
"checkoutId": "ch_9b3e7a1c5d2f",
"reference": "VXP-7KQ4M9TZ2HXA",
"price_id": "66f1c1e2c8a4b0d1f2e3a4c1",
"checkoutUrl": "https://…",
"expiresAt": null
}Cuando el comprador paga, se crea la suscripción y se cobra cada ciclo en USD (webhooks subscription.created y payment.completed por cada cobro; 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. |
prices_required | 400 | El link recurrente no tiene planes. |
payment_account_not_ready | 409 | La cuenta de cobro del dueño del link no está activada (o fue rechazada). |
upstream_error | 502 | El procesador de pagos no creó el checkout. Reintenta en unos minutos. |