Crear link de pago único

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.

Antes de empezar

El link cobra en tu cuenta de cobro: necesitas activarla desde el dashboard (si no, la API responde 409 payment_account_not_ready). Los links se pueden crear con la verificación de identidad pendiente; para retirar el dinero hace falta completarla.

El precio se fija en USD (mínimo USD 4). En el checkout, el comprador puede pagar en su moneda local o en USD.
Cada venta paga la comisión de vexorpay, desde 2,7 % + USD 1 con el procesamiento incluido (ver Cómo funcionan los cobros).
Con una clave de prueba (vxp_test_...) contra api.sandbox.vexorpay.com el link se crea en sandbox y se paga con tarjetas de prueba.

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	sí	Título del producto: lo ve el comprador en el checkout y en el recibo.
`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 muestra en la página del link (`url`) y 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.
`success_url`	string	no	URL https a la que va el comprador después de pagar (admite `{ORDER_ID}` y `{REFERENCE}`). Ver Redirección después del pago.

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://…",
  "type": "one_time",
  "createdAt": "2026-01-02T12:00:00.000Z",
  "updatedAt": "2026-01-02T12:00:00.000Z"
}

url es la página pública del link: compártela (cada visita genera una referencia única para esa compra). checkoutUrl es el checkout alojado del link, sin referencia propia. Para una sesión de checkout por compra (con reference, email precargado o un plan puntual) usa POST /v1/payment-links/{id}/checkout.

Redirección después del pago

Con success_url, una vez confirmado el pago vexorpay lleva al comprador a tu sitio (a los pocos segundos, o antes si toca Continuar). La URL tiene que ser https y admite dos marcadores que se reemplazan en cada venta:

Marcador	Se reemplaza por
`{ORDER_ID}`	El id de la venta (el de `GET /api/v1/orders/{id}`).
`{REFERENCE}`	La referencia de esa compra.

{ "success_url": "https://tu-sitio.com/gracias?orden={ORDER_ID}" }

Se edita con PATCH /api/v1/payment-links/{id} (null la quita) y también desde el dashboard, en el detalle del link. No des por pagada una compra porque alguien llegó a tu success_url (cualquiera puede escribir esa URL): confírmala con el webhook payment.completed o con GET /api/v1/orders/{ORDER_ID}.

Errores

Error	HTTP	Causa
`unauthorized`	401	Falta el header `Authorization`.
`invalid_key`	401	La API key es inválida o fue revocada.
`livemode_mismatch`	403	La clave no corresponde al host (clave de prueba contra producción o al revés).
`invalid_amount`	400	El monto es menor a USD 4 o no es un número válido.
`validation_error`	400	Falta el `title` (o está vacío).
`payment_account_not_ready`	409	Tu cuenta de cobro no está activada, fue rechazada o todavía no verificaste tu identidad: complétalo desde el dashboard.
`payment_account_suspended`	403	Tu cuenta de cobro está suspendida (por el procesador de pagos o por vexorpay): no se pueden crear links hasta que se reactive.
`invalid_idempotency_key`	400	El header `Idempotency-Key` vino vacío o tiene más de 255 bytes.
`idempotency_conflict`	409	La `Idempotency-Key` ya se usó con un body distinto.
`rate_limited`	429	Superaste el límite de 100 requests por minuto.
`payment_link_failed`	502	El procesador de pagos rechazó la creación del link. No quedó nada publicado: reintenta.

Crear link de pago único

En esta página