Listar y obtener links

Consulta, actualiza y cancela los links de pago de tu cuenta con filtros y paginación.

Los links eliminados nunca aparecen en los listados.

Listar

GET /api/v1/payment-links

Parámetros

Parámetro	Descripción
`status`	Filtro: `active`, `canceled` o `archived`. Sin filtro se excluyen solo los eliminados.
`type`	Filtro: `one_time` o `recurring`. Sin filtro devuelve ambos.
`limit`	Cantidad por página (default 10, máximo 100).
`starting_after` / `ending_before`	Cursor de paginación por `id`.

Ejemplo

curl "https://api.vexorpay.com/api/v1/payment-links?status=active&type=one_time&limit=10" \
  -H "Authorization: Bearer vxp_live_tu_clave"

Respuesta exitosa

200 OK

{
  "data": [
    {
      "id": "66f1c1e2c8a4b0d1f2e3a4b5",
      "amountCents": 1900,
      "currency": "usd",
      "title": "Ebook UX en 30 días",
      "description": null,
      "image": "https://.../product/66f1c1e2c8a4b0d1f2e3a4c9",
      "reference": "CATALOGO-UX",
      "metadata": null,
      "status": "active",
      "slug": "a1b2c3d4e5",
      "sandbox": false,
      "type": "one_time",
      "checkoutUrl": "https://…",
      "url": "https://www.vexorpay.com/p/a1b2c3d4e5",
      "createdAt": "2026-01-02T12:00:00.000Z",
      "updatedAt": "2026-01-02T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "total_count": 1,
  "url": "/v1/payment-links?limit=10"
}

En un link recurring el amountCents es 0 (el precio lo definen los planes) y se agrega el array prices:

{
  "id": "66f1c1e2c8a4b0d1f2e3a4b7",
  "amountCents": 0,
  "currency": "usd",
  "type": "recurring",
  "prices": [
    {
      "id": "66f1c1e2c8a4b0d1f2e3a4c1",
      "amountCents": 900,
      "currency": "usd",
      "interval": "month",
      "intervalCount": 1,
      "trialPeriodDays": 7,
      "description": "Plan mensual",
      "isDefault": true
    }
  ]
}

Obtener un link

GET /api/v1/payment-links/{id}

El entorno lo define la API key: una clave vxp_test_... opera sobre links de prueba.

curl https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5 \
  -H "Authorization: Bearer vxp_live_tu_clave"

Devuelve el link completo de tu cuenta o 404 link_not_found si no existe. checkoutUrl es el checkout alojado del link.

url es el link público para compartir: cada visita genera una referencia única para esa compra, que vuelve en reference de la venta, sus webhooks y /events. Si quieres usar tu propio id, agrega ?reference=<tu-id> (por ejemplo https://www.vexorpay.com/p/a1b2c3d4e5?reference=ORD-1001). Ver Identificar cada venta. Comparte url, no checkoutUrl: la referencia única de cada compra se genera desde url.

Métricas de un link

GET /api/v1/payment-links/{id}/stats

Las mismas métricas que ves en el detalle del link en el dashboard. Los montos van en centavos de USD y son netos: sin impuestos, sin comisiones (la de vexorpay y las de procesamiento) y sin lo reembolsado. Se calculan sobre las ventas del link.

Link de pago único (type: "one_time"):

{
  "paymentLinkId": "68f1c1e2c8a4b0d1f2e3a4b5",
  "type": "one_time",
  "salesCount": 12,
  "grossCents": 66000,
  "netCents": 52740,
  "avgTicketCents": 4395,
  "customers": 11,
  "repeatCustomers": 1,
  "refunds": { "count": 1, "cents": 5000 },
  "disputes": { "count": 0, "cents": 0 },
  "topCountries": [{ "country": "US", "count": 5 }, { "country": "ES", "count": 3 }],
  "weekly": [{ "weekStart": "2026-10-20T00:00:00.000Z", "netCents": 8790, "count": 2 }]
}

Link recurrente (type: "recurring"):

{
  "paymentLinkId": "68f1c1e2c8a4b0d1f2e3a4b6",
  "type": "recurring",
  "activeSubscribers": 18,
  "mrrCents": 36000,
  "trialing": { "count": 3, "mrrCents": 6000 },
  "atRisk": { "count": 1, "mrrCents": 2000 },
  "newThisMonth": 4,
  "canceledThisMonth": 1,
  "churnRate": 0.056,
  "trialConversion": { "converted": 7, "total": 9 },
  "netThisMonthCents": 31200,
  "netTotalCents": 214500,
  "ltvCents": 9750,
  "monthly": [{ "month": "2026-10", "netCents": 31200 }]
}

salesCount, customers y avgTicketCents cuentan las ventas vigentes: las reembolsadas por completo van en refunds. netCents ya descuenta todos los reembolsos.
mrrCents cuenta sólo las suscripciones active: las que están en prueba van en trialing (MRR potencial) y las de pago fallido en atRisk.
churnRate = bajas del mes / suscriptores al empezar el mes (null sin base).
weekly trae las últimas 12 semanas y monthly los últimos 12 meses.

Si el link no existe (o es de otro modo, prueba/producción) responde 404 link_not_found.

Actualizar un link

PATCH /api/v1/payment-links/{id}

Puedes cambiar title, description, image_file_id (null quita la foto), reference, amount (en dólares, sólo pago único) y, en cada plan de un link recurring, su nombre (description).

Pago único: el amount nuevo aplica a las compras nuevas. El url no cambia.
Recurrente: cada plan va con su id y la lista de planes tiene que ser la misma. Cambiar el amount, el interval/interval_count o la prueba gratis de un plan, o agregar o quitar planes, responde 400 unsupported_plan: crea un link nuevo. Sin prices, los planes quedan como están. Las suscripciones vigentes siguen con su precio.
El title no se puede vaciar y el type no se puede editar (400 validation_error). El amount no aplica a links recurrentes ni prices a links de pago único (validation_error).
status acepta active o archived: archived lo saca de venta, igual que DELETE. Otro valor responde 400 validation_error. Un link archivado no se edita ni se reactiva (400 payment_link_inactive).

curl https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5 \
  -X PATCH \
  -H "Authorization: Bearer vxp_live_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Membresía Vexor (2027)",
    "prices": [
      { "id": "66f1c1e2c8a4b0d1f2e3a4c1", "amount": 9, "interval": "month", "description": "Plan mensual" },
      { "id": "66f1c1e2c8a4b0d1f2e3a4c2", "amount": 90, "interval": "year", "trial_period_days": 7, "description": "Plan anual" }
    ]
  }'

Items de prices:

Campo	Tipo	Necesario	Notas
`id`	string	sí	Id del plan existente (debe pertenecer a este link).
`amount`	number	sí	El mismo monto por ciclo en dólares (no se puede cambiar).
`currency`	string	no	Solo `usd` (default).
`interval`	string	sí	El mismo intervalo: `day`, `week`, `month` o `year`.
`interval_count`	number	no	El mismo `interval_count` (default `1`).
`trial_period_days`	number	no	La misma prueba gratis (`1` a `90`); ausente o `null` = sin prueba.
`description`	string	no	Nombre nuevo del plan ("Mensual", "Anual"...).

Devuelve 200 con el link actualizado y sus prices.

El entorno de GET, PATCH y DELETE lo define la API key, no un parámetro del request.

Errores

Error	HTTP	Causa
`validation_error`	400	Mandaste un `title` vacío, intentaste cambiar `type`, mandaste `prices` en un link `one_time`, `amount` en un link `recurring`, `id` de un plan de otro link, un plan repetido, `currency` que no es USD, `interval` inválido o un `status` distinto de `active`/`archived`.
`invalid_amount`	400	El nuevo `amount` es menor a USD 4.
`minimum_amount`	400	Algún plan con `amount` menor a USD 4.
`invalid_interval_count`	400	`interval_count` inválido (entero 1–12; `year` solo cada 1).
`invalid_trial`	400	`trial_period_days` fuera de 1–90.
`prices_required`	400	`prices` vacío o no es un array.
`too_many_prices`	400	Más de 5 planes.
`unsupported_plan`	400	Cambio de planes en un link recurrente (precio, intervalo, prueba o cantidad de planes). Crea un link nuevo.
`payment_link_inactive`	400	El link está archivado: no se edita ni se reactiva.
`invalid_request`	400	El body del PATCH está vacío.
`link_not_found`	404	No existe un link con ese id en tu cuenta (o es de otro modo).
`payment_link_failed`	502	El procesador de pagos rechazó o no respondió el cambio. No se cambió nada: reintenta.

Eliminar un link

DELETE /api/v1/payment-links/{id}

Alineado con la acción Eliminar del dashboard: saca el link de venta y nunca borra ventas ya realizadas.

curl -X DELETE https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5 \
  -H "Authorization: Bearer vxp_live_tu_clave"

Situación	HTTP	Respuesta
Link activo	`200`	El link con `status: "archived"`: deja de venderse (`url` y `checkoutUrl` dejan de funcionar). Las suscripciones vigentes siguen cobrándose hasta que se cancelen.
Link ya `deleted` o `archived`	`409`	`already_processed`.
No existe, es de otro usuario o de otro modo	`404`	`link_not_found`.

Para que dejen de cobrarse las suscripciones de un link archivado, cancela cada una con POST /api/v1/subscriptions/{id}/cancel.

{
  "id": "66f1c1e2c8a4b0d1f2e3a4b5",
  "amountCents": 499,
  "currency": "usd",
  "title": "Pack de presets",
  "description": null,
  "image": null,
  "reference": null,
  "metadata": {},
  "status": "archived",
  "slug": "a1b2c3d4e5",
  "sandbox": false,
  "url": "https://www.vexorpay.com/p/a1b2c3d4e5",
  "type": "one_time",
  "createdAt": "2026-01-02T12:00:00.000Z",
  "updatedAt": "2026-02-02T09:30:00.000Z"
}

Errores:

Error	HTTP	Causa
`already_processed`	409	El link ya fue eliminado o archivado.
`link_not_found`	404	No existe un link con ese id en tu cuenta (o es de otro modo).

Los links eliminados nunca aparecen en los listados.

Listar

GET /api/v1/payment-links

Parámetros

Parámetro	Descripción
`status`	Filtro: `active`, `canceled` o `archived`. Sin filtro se excluyen solo los eliminados.
`type`	Filtro: `one_time` o `recurring`. Sin filtro devuelve ambos.
`limit`	Cantidad por página (default 10, máximo 100).
`starting_after` / `ending_before`	Cursor de paginación por `id`.

Ejemplo

curl "https://api.vexorpay.com/api/v1/payment-links?status=active&type=one_time&limit=10" \
  -H "Authorization: Bearer vxp_live_tu_clave"

Respuesta exitosa

200 OK

{
  "data": [
    {
      "id": "66f1c1e2c8a4b0d1f2e3a4b5",
      "amountCents": 1900,
      "currency": "usd",
      "title": "Ebook UX en 30 días",
      "description": null,
      "image": "https://.../product/66f1c1e2c8a4b0d1f2e3a4c9",
      "reference": "CATALOGO-UX",
      "metadata": null,
      "status": "active",
      "slug": "a1b2c3d4e5",
      "sandbox": false,
      "type": "one_time",
      "checkoutUrl": "https://…",
      "url": "https://www.vexorpay.com/p/a1b2c3d4e5",
      "createdAt": "2026-01-02T12:00:00.000Z",
      "updatedAt": "2026-01-02T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "total_count": 1,
  "url": "/v1/payment-links?limit=10"
}

En un link recurring el amountCents es 0 (el precio lo definen los planes) y se agrega el array prices:

{
  "id": "66f1c1e2c8a4b0d1f2e3a4b7",
  "amountCents": 0,
  "currency": "usd",
  "type": "recurring",
  "prices": [
    {
      "id": "66f1c1e2c8a4b0d1f2e3a4c1",
      "amountCents": 900,
      "currency": "usd",
      "interval": "month",
      "intervalCount": 1,
      "trialPeriodDays": 7,
      "description": "Plan mensual",
      "isDefault": true
    }
  ]
}

Obtener un link

GET /api/v1/payment-links/{id}

El entorno lo define la API key: una clave vxp_test_... opera sobre links de prueba.

curl https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5 \
  -H "Authorization: Bearer vxp_live_tu_clave"

Devuelve el link completo de tu cuenta o 404 link_not_found si no existe. checkoutUrl es el checkout alojado del link.

Métricas de un link

GET /api/v1/payment-links/{id}/stats

Link de pago único (type: "one_time"):

{
  "paymentLinkId": "68f1c1e2c8a4b0d1f2e3a4b5",
  "type": "one_time",
  "salesCount": 12,
  "grossCents": 66000,
  "netCents": 52740,
  "avgTicketCents": 4395,
  "customers": 11,
  "repeatCustomers": 1,
  "refunds": { "count": 1, "cents": 5000 },
  "disputes": { "count": 0, "cents": 0 },
  "topCountries": [{ "country": "US", "count": 5 }, { "country": "ES", "count": 3 }],
  "weekly": [{ "weekStart": "2026-10-20T00:00:00.000Z", "netCents": 8790, "count": 2 }]
}

Link recurrente (type: "recurring"):

{
  "paymentLinkId": "68f1c1e2c8a4b0d1f2e3a4b6",
  "type": "recurring",
  "activeSubscribers": 18,
  "mrrCents": 36000,
  "trialing": { "count": 3, "mrrCents": 6000 },
  "atRisk": { "count": 1, "mrrCents": 2000 },
  "newThisMonth": 4,
  "canceledThisMonth": 1,
  "churnRate": 0.056,
  "trialConversion": { "converted": 7, "total": 9 },
  "netThisMonthCents": 31200,
  "netTotalCents": 214500,
  "ltvCents": 9750,
  "monthly": [{ "month": "2026-10", "netCents": 31200 }]
}

salesCount, customers y avgTicketCents cuentan las ventas vigentes: las reembolsadas por completo van en refunds. netCents ya descuenta todos los reembolsos.
mrrCents cuenta sólo las suscripciones active: las que están en prueba van en trialing (MRR potencial) y las de pago fallido en atRisk.
churnRate = bajas del mes / suscriptores al empezar el mes (null sin base).
weekly trae las últimas 12 semanas y monthly los últimos 12 meses.

Si el link no existe (o es de otro modo, prueba/producción) responde 404 link_not_found.

Actualizar un link

PATCH /api/v1/payment-links/{id}

Pago único: el amount nuevo aplica a las compras nuevas. El url no cambia.
Recurrente: cada plan va con su id y la lista de planes tiene que ser la misma. Cambiar el amount, el interval/interval_count o la prueba gratis de un plan, o agregar o quitar planes, responde 400 unsupported_plan: crea un link nuevo. Sin prices, los planes quedan como están. Las suscripciones vigentes siguen con su precio.
El title no se puede vaciar y el type no se puede editar (400 validation_error). El amount no aplica a links recurrentes ni prices a links de pago único (validation_error).
status acepta active o archived: archived lo saca de venta, igual que DELETE. Otro valor responde 400 validation_error. Un link archivado no se edita ni se reactiva (400 payment_link_inactive).

curl https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5 \
  -X PATCH \
  -H "Authorization: Bearer vxp_live_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Membresía Vexor (2027)",
    "prices": [
      { "id": "66f1c1e2c8a4b0d1f2e3a4c1", "amount": 9, "interval": "month", "description": "Plan mensual" },
      { "id": "66f1c1e2c8a4b0d1f2e3a4c2", "amount": 90, "interval": "year", "trial_period_days": 7, "description": "Plan anual" }
    ]
  }'

Items de prices:

Campo	Tipo	Necesario	Notas
`id`	string	sí	Id del plan existente (debe pertenecer a este link).
`amount`	number	sí	El mismo monto por ciclo en dólares (no se puede cambiar).
`currency`	string	no	Solo `usd` (default).
`interval`	string	sí	El mismo intervalo: `day`, `week`, `month` o `year`.
`interval_count`	number	no	El mismo `interval_count` (default `1`).
`trial_period_days`	number	no	La misma prueba gratis (`1` a `90`); ausente o `null` = sin prueba.
`description`	string	no	Nombre nuevo del plan ("Mensual", "Anual"...).

Devuelve 200 con el link actualizado y sus prices.

El entorno de GET, PATCH y DELETE lo define la API key, no un parámetro del request.

Errores

Error	HTTP	Causa
`validation_error`	400	Mandaste un `title` vacío, intentaste cambiar `type`, mandaste `prices` en un link `one_time`, `amount` en un link `recurring`, `id` de un plan de otro link, un plan repetido, `currency` que no es USD, `interval` inválido o un `status` distinto de `active`/`archived`.
`invalid_amount`	400	El nuevo `amount` es menor a USD 4.
`minimum_amount`	400	Algún plan con `amount` menor a USD 4.
`invalid_interval_count`	400	`interval_count` inválido (entero 1–12; `year` solo cada 1).
`invalid_trial`	400	`trial_period_days` fuera de 1–90.
`prices_required`	400	`prices` vacío o no es un array.
`too_many_prices`	400	Más de 5 planes.
`unsupported_plan`	400	Cambio de planes en un link recurrente (precio, intervalo, prueba o cantidad de planes). Crea un link nuevo.
`payment_link_inactive`	400	El link está archivado: no se edita ni se reactiva.
`invalid_request`	400	El body del PATCH está vacío.
`link_not_found`	404	No existe un link con ese id en tu cuenta (o es de otro modo).
`payment_link_failed`	502	El procesador de pagos rechazó o no respondió el cambio. No se cambió nada: reintenta.

Eliminar un link

DELETE /api/v1/payment-links/{id}

Alineado con la acción Eliminar del dashboard: saca el link de venta y nunca borra ventas ya realizadas.

curl -X DELETE https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5 \
  -H "Authorization: Bearer vxp_live_tu_clave"

Situación	HTTP	Respuesta
Link activo	`200`	El link con `status: "archived"`: deja de venderse (`url` y `checkoutUrl` dejan de funcionar). Las suscripciones vigentes siguen cobrándose hasta que se cancelen.
Link ya `deleted` o `archived`	`409`	`already_processed`.
No existe, es de otro usuario o de otro modo	`404`	`link_not_found`.

Para que dejen de cobrarse las suscripciones de un link archivado, cancela cada una con POST /api/v1/subscriptions/{id}/cancel.

{
  "id": "66f1c1e2c8a4b0d1f2e3a4b5",
  "amountCents": 499,
  "currency": "usd",
  "title": "Pack de presets",
  "description": null,
  "image": null,
  "reference": null,
  "metadata": {},
  "status": "archived",
  "slug": "a1b2c3d4e5",
  "sandbox": false,
  "url": "https://www.vexorpay.com/p/a1b2c3d4e5",
  "type": "one_time",
  "createdAt": "2026-01-02T12:00:00.000Z",
  "updatedAt": "2026-02-02T09:30:00.000Z"
}

Errores:

Error	HTTP	Causa
`already_processed`	409	El link ya fue eliminado o archivado.
`link_not_found`	404	No existe un link con ese id en tu cuenta (o es de otro modo).

Listar y obtener links

Listar

Parámetros

Ejemplo

Respuesta exitosa

Obtener un link

Métricas de un link

Actualizar un link

Errores

Eliminar un link

On this page

Listar y obtener links

Listar

Parámetros

Ejemplo

Respuesta exitosa

Obtener un link

Métricas de un link

Actualizar un link

Errores

Eliminar un link

On this page