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. |
sandbox | Filtro por modo: true (solo links de prueba) o false (solo producción). Sin filtro muestra 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_u_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",
"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",
"stripePriceId": "price_1P...",
"amountCents": 900,
"currency": "usd",
"interval": "month",
"intervalCount": 1,
"trialPeriodDays": 7,
"description": "Plan mensual",
"isDefault": true
}
]
}Obtener un link
GET /api/v1/payment-links/{id}
En sandbox, mandá ?sandbox=true.
curl https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5 \
-H "Authorization: Bearer vxp_u_tu_clave"Devuelve el link completo de tu cuenta o 404 link_not_found si no existe. Si el link tiene una sesión de Checkout abierta, la respuesta incluye checkoutUrl.
Actualizar un link
PATCH /api/v1/payment-links/{id}
Podés cambiar amount (en dólares), title, description, reference, status (a active, canceled o archived) e image_file_id (null quita la foto). Los cobros ya creados no cambian: la referencia y el estado aplican a las compras futuras. El type no se puede editar: creá un link nuevo.
En un link recurring además podés mandar prices para agregar, editar o quitar planes (se actualizan vivos, sin recrear el link). La semántica es: cada elemento con id actualiza ESE plan; sin id agrega un plan nuevo; los planes del link que no viajan en la lista se eliminan (salvo que tengan suscripciones → plan_in_use). El amount no aplica a links recurrentes (validation_error).
curl https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5 \
-X PATCH \
-H "Authorization: Bearer vxp_u_tu_clave" \
-H "Content-Type: application/json" \
-d '{
"prices": [
{ "id": "66f1c1e2c8a4b0d1f2e3a4c1", "amount": 1200, "currency": "usd", "interval": "month", "interval_count": 1, "description": "Mensual" },
{ "amount": 12000, "currency": "usd", "interval": "year", "interval_count": 1, "trial_period_days": 7, "description": "Anual" }
]
}'Items de prices:
| Campo | Tipo | Necesario | Notas |
|---|---|---|---|
id | string | no | Id del plan existente; ausente = plan nuevo. El id debe pertenecer a este link. |
amount | number | sí | Monto por ciclo en dólares (mínimo USD 4). amount * 100 es el amountCents. |
currency | string | no | Solo usd (default). |
interval | string | sí | day, week, month o year. |
interval_count | number | no | Cada N intervalos (default 1). |
trial_period_days | number | no | Trial gratuito en días (1 a 90); ausente o null = sin trial. |
description | string | no | Label del plan ("Mensual", "Anual"...). |
Devuelve 200 con el link actualizado y sus prices. Un link canceled solo puede volver a active.
En sandbox, mandá ?sandbox=true en el GET, PATCH y DELETE.
Errores
| Error | HTTP | Causa |
|---|---|---|
validation_error | 400 | status/type inválido, 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 o interval inválido. |
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. |
plan_in_use | 400 | Intentaste eliminar un plan que tiene suscripciones. |
payment_link_inactive | 400 | Un link cancelado solo puede volver a active. |
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). |
Cancelar un link
DELETE /api/v1/payment-links/{id}
Cancela el link (soft delete): deja de cobrar, pero no borra los pagos ya realizados. Es idempotente: cancelar un link ya cancelado vuelve a responder 200.
curl -X DELETE https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5 \
-H "Authorization: Bearer vxp_u_tu_clave"