Ventas

Lista, consulta y reembolsa las ventas que cobras con tus links, con la comisión y el neto de cada una.

Cada venta (un pago único, el alta de una suscripción o una renovación) es una order. El cobro se hace en tu cuenta de cobro: de cada venta se descuenta la comisión de vexorpay (desde 2,7 % + USD 1, con el procesamiento incluido) y el resto se acredita en tu saldo (ver Saldo).

El objeto Order

{
  "id": "67f1c1e2c8a4b0d1f2e3a4b5",
  "paymentLinkId": "66f1c1e2c8a4b0d1f2e3a4b5",
  "subscriptionId": null,
  "checkoutId": "ch_4f8a2c9d1e7b",
  "reference": "ORD-1001",
  "metadata": { "utm_source": "instagram" },
  "status": "paid",
  "billingReason": "one_time",
  "currency": "usd",
  "subtotalCents": 2500,
  "taxCents": 0,
  "totalCents": 2500,
  "feeCents": 232,
  "feeBreakdown": {
    "vexorpay": { "amountCents": 168, "percent": 2.7, "fixedCents": 100 },
    "extras": [
      { "type": "cross_border", "amountCents": 38, "percent": 1.5 },
      { "type": "processing", "amountCents": 19, "percent": null },
      { "type": "fraud_prevention", "amountCents": 7, "percent": null }
    ]
  },
  "netCents": 2268,
  "refundedCents": 0,
  "refundableCents": 2500,
  "customerEmail": "cliente@ejemplo.com",
  "customerName": "Ana Pérez",
  "productName": "Curso de fotografía",
  "sandbox": false,
  "createdAt": "2026-10-24T07:55:33.971Z"
}

Todos los montos van en centavos de USD, aunque el comprador haya pagado en su moneda local.

Campo	Qué es
`totalCents`	Lo que pagó el comprador (impuesto incluido, si se cobró).
`subtotalCents`	El precio antes de impuestos.
`taxCents`	El impuesto cobrado. Es `0` si te encargas de tus impuestos (la opción por defecto); con el impuesto automático activado, el impuesto calculado. Ver Cómo funcionan los cobros.
`feeCents`	La comisión de vexorpay de la venta, con el procesamiento del pago incluido (desde 2,7 % + USD 1). `0` en una venta de USD 0; `null` mientras no se conozca.
`feeBreakdown`	El desglose de `feeCents` (`null` mientras no se conozca). `vexorpay` es la comisión general: `percent` % del total + `fixedCents` (p. ej. 2,7 % + USD 1, con los valores reales de la venta: el porcentaje cambia con el país de la tarjeta). `extras` son los adicionales de esa venta, cada uno con su `type`, `amountCents` y `percent` (`null` si es un monto fijo o no tiene un porcentaje publicado). Ver abajo.
`netCents`	Lo que te queda: el total menos el impuesto y la comisión.
`refundedCents` / `refundableCents`	Lo reembolsado y lo que todavía se puede reembolsar.
`status`	`paid`, `partially_refunded`, `refunded`, `pending` o `failed`.
`billingReason`	Motivo del cobro: `one_time` (pago único), `subscription_create` (alta de suscripción) o `subscription_cycle` (renovación).
`subscriptionId`	La suscripción a la que pertenece el cobro (`null` en un pago único).
`checkoutId`	La sesión de checkout que generó la venta (la que devuelve `POST /checkout`).
`reference` / `metadata`	Tu referencia de la venta y tu metadata. Ver abajo.

Al empezar una prueba gratis se registra una venta de USD 0 (billingReason: "subscription_create", sin comisión). El primer cobro real llega como otra venta al terminar la prueba.

Los adicionales de la comisión

Además de la comisión general (feeBreakdown.vexorpay), algunas ventas suman cargos según cómo se pagó. Cada uno llega en feeBreakdown.extras con uno de estos type:

`type`	Cuándo aparece
`cross_border`	Tarjeta de fuera de la región del comprador (1,5 %).
`currency_conversion`	El comprador pagó en otra moneda (1 %).
`subscription`	Cobros de suscripciones (0,5 %).
`processing`	Procesamiento adicional del pago.
`fraud_prevention`	Prevención de fraude (unos centavos por pago).
`authentication`	Verificación 3D Secure de la tarjeta.
`other`	Otros cargos del procesamiento.

La suma de feeBreakdown.vexorpay.amountCents y de los extras es feeCents. Pueden aparecer tipos nuevos: tratá un type desconocido como other.

Identificar cada venta con tu referencia

Toda venta trae una referencia única en el campo reference, en sus webhooks (data.object.reference) y en /events:

Con el link público (https://www.vexorpay.com/p/a1b2c3d4e5): cada visita genera una referencia nueva (VXP- + 12 caracteres, p. ej. VXP-7KQ4M9TZ2HXA). Puedes compartir el mismo link con toda tu audiencia: cada compra sale con la suya, nunca dos ventas con la misma.
Con tu propio id: agrega ?reference=<tu-id> al link (/p/a1b2c3d4e5?reference=ORD-1001) o manda reference en POST /api/v1/payment-links/{id}/checkout, y se usa la tuya en vez de la generada. El checkout por API sin reference también genera una, y la respuesta la devuelve en reference (junto con checkoutId, que vuelve en la venta).
El link también acepta utm_source, utm_medium, utm_campaign, utm_content y utm_term, que quedan en metadata.

En una suscripción, la referencia queda en la suscripción y cada renovación la hereda. Para buscar una venta por referencia: GET /api/v1/orders?reference=VXP-7KQ4M9TZ2HXA. La referencia admite hasta 200 caracteres.

Listar ventas

GET /api/v1/orders

Parámetro	Descripción
`status`	Filtra por estado.
`payment_link_id`	Ventas de un link.
`reference`	Ventas con esa referencia tuya (coincidencia exacta).
`limit` / `starting_after` / `ending_before`	Paginación por cursor (default 10, máximo 100).

curl "https://api.vexorpay.com/api/v1/orders?status=paid" \
  -H "Authorization: Bearer vxp_live_tu_clave"

Ver una venta

GET /api/v1/orders/{id}

Devuelve la venta o 404 order_not_found.

Reembolsar una venta

POST /api/v1/orders/{id}/refund

Reembolsa una venta paid o partially_refunded, total o parcialmente. El dinero sale de tu saldo. Es irreversible. Soporta Idempotency-Key: un replay devuelve la venta sin volver a reembolsar.

Campo	Tipo	Requerido	Descripción
`amount`	number	no	Dólares a reembolsar (hasta `refundableCents`). Si se omite, se reembolsa todo lo reembolsable.

curl -X POST https://api.vexorpay.com/api/v1/orders/67f1c1e2c8a4b0d1f2e3a4b5/refund \
  -H "Authorization: Bearer vxp_live_tu_clave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-ORD-1001" \
  -d '{ "amount": 10 }'

Devuelve la venta actualizada (refundedCents, refundableCents y status) y se dispara el webhook payment.refunded.

Errores

Error	HTTP	Causa
`validation_error`	400	`status` inválido, campo desconocido, `amount` fuera de rango o la venta no está pagada.
`order_not_found`	404	No existe esa venta en tu cuenta (o es de otro modo).
`idempotency_conflict`	409	La `Idempotency-Key` ya se usó con un body distinto.
`upstream_error`	502	El procesador de pagos no procesó el reembolso. No se cambió nada: reintenta.

El objeto Order

{
  "id": "67f1c1e2c8a4b0d1f2e3a4b5",
  "paymentLinkId": "66f1c1e2c8a4b0d1f2e3a4b5",
  "subscriptionId": null,
  "checkoutId": "ch_4f8a2c9d1e7b",
  "reference": "ORD-1001",
  "metadata": { "utm_source": "instagram" },
  "status": "paid",
  "billingReason": "one_time",
  "currency": "usd",
  "subtotalCents": 2500,
  "taxCents": 0,
  "totalCents": 2500,
  "feeCents": 232,
  "feeBreakdown": {
    "vexorpay": { "amountCents": 168, "percent": 2.7, "fixedCents": 100 },
    "extras": [
      { "type": "cross_border", "amountCents": 38, "percent": 1.5 },
      { "type": "processing", "amountCents": 19, "percent": null },
      { "type": "fraud_prevention", "amountCents": 7, "percent": null }
    ]
  },
  "netCents": 2268,
  "refundedCents": 0,
  "refundableCents": 2500,
  "customerEmail": "cliente@ejemplo.com",
  "customerName": "Ana Pérez",
  "productName": "Curso de fotografía",
  "sandbox": false,
  "createdAt": "2026-10-24T07:55:33.971Z"
}

Todos los montos van en centavos de USD, aunque el comprador haya pagado en su moneda local.

Campo	Qué es
`totalCents`	Lo que pagó el comprador (impuesto incluido, si se cobró).
`subtotalCents`	El precio antes de impuestos.
`taxCents`	El impuesto cobrado. Es `0` si te encargas de tus impuestos (la opción por defecto); con el impuesto automático activado, el impuesto calculado. Ver Cómo funcionan los cobros.
`feeCents`	La comisión de vexorpay de la venta, con el procesamiento del pago incluido (desde 2,7 % + USD 1). `0` en una venta de USD 0; `null` mientras no se conozca.
`feeBreakdown`	El desglose de `feeCents` (`null` mientras no se conozca). `vexorpay` es la comisión general: `percent` % del total + `fixedCents` (p. ej. 2,7 % + USD 1, con los valores reales de la venta: el porcentaje cambia con el país de la tarjeta). `extras` son los adicionales de esa venta, cada uno con su `type`, `amountCents` y `percent` (`null` si es un monto fijo o no tiene un porcentaje publicado). Ver abajo.
`netCents`	Lo que te queda: el total menos el impuesto y la comisión.
`refundedCents` / `refundableCents`	Lo reembolsado y lo que todavía se puede reembolsar.
`status`	`paid`, `partially_refunded`, `refunded`, `pending` o `failed`.
`billingReason`	Motivo del cobro: `one_time` (pago único), `subscription_create` (alta de suscripción) o `subscription_cycle` (renovación).
`subscriptionId`	La suscripción a la que pertenece el cobro (`null` en un pago único).
`checkoutId`	La sesión de checkout que generó la venta (la que devuelve `POST /checkout`).
`reference` / `metadata`	Tu referencia de la venta y tu metadata. Ver abajo.

Al empezar una prueba gratis se registra una venta de USD 0 (billingReason: "subscription_create", sin comisión). El primer cobro real llega como otra venta al terminar la prueba.

Los adicionales de la comisión

Además de la comisión general (feeBreakdown.vexorpay), algunas ventas suman cargos según cómo se pagó. Cada uno llega en feeBreakdown.extras con uno de estos type:

`type`	Cuándo aparece
`cross_border`	Tarjeta de fuera de la región del comprador (1,5 %).
`currency_conversion`	El comprador pagó en otra moneda (1 %).
`subscription`	Cobros de suscripciones (0,5 %).
`processing`	Procesamiento adicional del pago.
`fraud_prevention`	Prevención de fraude (unos centavos por pago).
`authentication`	Verificación 3D Secure de la tarjeta.
`other`	Otros cargos del procesamiento.

La suma de feeBreakdown.vexorpay.amountCents y de los extras es feeCents. Pueden aparecer tipos nuevos: tratá un type desconocido como other.

Identificar cada venta con tu referencia

Toda venta trae una referencia única en el campo reference, en sus webhooks (data.object.reference) y en /events:

Con el link público (https://www.vexorpay.com/p/a1b2c3d4e5): cada visita genera una referencia nueva (VXP- + 12 caracteres, p. ej. VXP-7KQ4M9TZ2HXA). Puedes compartir el mismo link con toda tu audiencia: cada compra sale con la suya, nunca dos ventas con la misma.
Con tu propio id: agrega ?reference=<tu-id> al link (/p/a1b2c3d4e5?reference=ORD-1001) o manda reference en POST /api/v1/payment-links/{id}/checkout, y se usa la tuya en vez de la generada. El checkout por API sin reference también genera una, y la respuesta la devuelve en reference (junto con checkoutId, que vuelve en la venta).
El link también acepta utm_source, utm_medium, utm_campaign, utm_content y utm_term, que quedan en metadata.

Listar ventas

GET /api/v1/orders

Parámetro	Descripción
`status`	Filtra por estado.
`payment_link_id`	Ventas de un link.
`reference`	Ventas con esa referencia tuya (coincidencia exacta).
`limit` / `starting_after` / `ending_before`	Paginación por cursor (default 10, máximo 100).

curl "https://api.vexorpay.com/api/v1/orders?status=paid" \
  -H "Authorization: Bearer vxp_live_tu_clave"

Ver una venta

GET /api/v1/orders/{id}

Devuelve la venta o 404 order_not_found.

Reembolsar una venta

POST /api/v1/orders/{id}/refund

Campo	Tipo	Requerido	Descripción
`amount`	number	no	Dólares a reembolsar (hasta `refundableCents`). Si se omite, se reembolsa todo lo reembolsable.

curl -X POST https://api.vexorpay.com/api/v1/orders/67f1c1e2c8a4b0d1f2e3a4b5/refund \
  -H "Authorization: Bearer vxp_live_tu_clave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-ORD-1001" \
  -d '{ "amount": 10 }'

Devuelve la venta actualizada (refundedCents, refundableCents y status) y se dispara el webhook payment.refunded.

Errores

Error	HTTP	Causa
`validation_error`	400	`status` inválido, campo desconocido, `amount` fuera de rango o la venta no está pagada.
`order_not_found`	404	No existe esa venta en tu cuenta (o es de otro modo).
`idempotency_conflict`	409	La `Idempotency-Key` ya se usó con un body distinto.
`upstream_error`	502	El procesador de pagos no procesó el reembolso. No se cambió nada: reintenta.

Ventas

El objeto Order

Los adicionales de la comisión

Identificar cada venta con tu referencia

Listar ventas

Ver una venta

Reembolsar una venta

Errores

On this page

Ventas

El objeto Order

Los adicionales de la comisión

Identificar cada venta con tu referencia

Listar ventas

Ver una venta

Reembolsar una venta

Errores

On this page