Crear link de pago único
Crea un link de pago único en dólares con la API de vexorpay.
El link es reutilizable: puedes compartirlo con varios clientes y, si quieres un cobro único por pedido, usar el checkout por compra.
Para cobrar de forma periódica (suscripciones/planes), usa la creación de link recurrente.
Canal de cobro (Polar)
El link se crea en Polar, el Merchant of Record: Polar cobra al comprador, calcula y
factura el impuesto y acredita la venta en tu saldo de Polar. Por eso
necesitas Polar conectado desde el dashboard (si no, la API
responde 400 account_not_connected). La respuesta trae checkoutUrl apuntando al checkout de Polar.
image_file_idse sube a Polar como imagen del producto (JPG, PNG, GIF o WebP de hasta 10 MB; si no, el link se crea sin foto).- Una clave de prueba (
vxp_test_...) no crea links en producción: responde400 polar_test_key_not_supported. - Si la organización de Polar todavía no puede cobrar (falta verificación), responde
409 polar_not_ready. Completa la verificación en Polar y vuelve a intentar.
Los links se editan con PATCH, se
archivan con DELETE y se cobran con
checkout, con las reglas que se explican en cada página.
Request
POST /api/v1/payment-links
Headers
| Header | Valor |
|---|---|
Authorization | Bearer vxp_live_tu_clave |
Content-Type | application/json |
Idempotency-Key | opcional — para repetir sin duplicar |
Vexor-Account | opcional — id del usuario conectado, para crear el link en su nombre (cuentas conectadas) |
Body
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
amount | number | sí | Monto en dólares. Mínimo USD 4. |
title | string | no | Título del cobro. |
description | string | no | Descripción del cobro. |
image_file_id | string | no | Foto del producto. Debe ser un archivo tuyo (subido desde el dashboard). Se sube a Polar y se muestra en el checkout. |
reference | string | no | Referencia tuya (n° de orden, SKU…). Se incluye en las ventas y los webhooks para reconciliar. |
metadata | object | no | Pares clave/valor libres que viajan con el link. |
type | string | no | one_time (default). Ver link recurrente. |
Ejemplo
curl https://api.vexorpay.com/api/v1/payment-links \
-X POST \
-H "Authorization: Bearer vxp_live_tu_clave" \
-H "Content-Type: application/json" \
-d '{
"amount": 19,
"title": "Ebook UX en 30 días",
"reference": "CATALOGO-UX",
"metadata": { "categoria": "ebook" }
}'Respuesta exitosa
201 Created
{
"id": "66f1c1e2c8a4b0d1f2e3a4b5",
"amountCents": 1900,
"currency": "usd",
"title": "Ebook UX en 30 días",
"description": null,
"image": null,
"reference": "CATALOGO-UX",
"metadata": { "categoria": "ebook" },
"status": "active",
"slug": "a1b2c3d4e5",
"sandbox": false,
"url": "https://www.vexorpay.com/p/a1b2c3d4e5",
"checkoutUrl": "https://buy.polar.sh/polar_cl_...",
"type": "one_time",
"createdAt": "2026-01-02T12:00:00.000Z",
"updatedAt": "2026-01-02T12:00:00.000Z"
}checkoutUrl es el checkout de Polar del link: compártelo o redirige al comprador ahí. Para una sesión de checkout por compra (con reference, email precargado o un plan puntual) usa POST /v1/payment-links/{id}/checkout.
Errores
| Error | HTTP | Causa |
|---|---|---|
unauthorized | 401 | Falta el header Authorization. |
invalid_key | 401 | La API key es inválida o fue revocada. |
invalid_amount | 400 | El monto es menor a USD 4 o no es un número válido. |
account_not_connected | 400 | No conectaste Polar (o la conexión se revocó): conéctalo desde el dashboard. |
polar_test_key_not_supported | 400 | Una clave de prueba (vxp_test_...) no puede crear links en producción. Usa una clave de producción. |
polar_not_ready | 409 | La organización de Polar todavía no puede cobrar: completá su verificación en Polar y reintentá. |
idempotency_conflict | 409 | La Idempotency-Key ya se usó con un body distinto. |
polar_provisioning_failed | 500 | Polar rechazó la creación del link. No quedó nada publicado: reintentá. |
rate_limited | 429 | Superaste el límite de 100 requests por minuto. |