Listar y obtener links

Los links eliminados nunca aparecen en los listados.

Listar

GET /api/v1/payment-links

Parámetros

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).
• success_url (URL https de redirección después del pago) se edita igual: null la quita. Ver Redirección después del pago.
• 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:

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

Archivar un link

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

Alineado con la acción Archivar 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"

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: