Referencia de API

Referencia general de la API de Vexorpay: base URL, autenticación, formato, paginación, idempotencia, rate limit y errores.

Base URL

https://api.vexorpay.com/api/v1

Formato de respuesta

Los recursos (links, cobros, suscripciones) se devuelven como objeto plano (GET /api/v1/payment-links/{id}, GET /api/v1/charges/{id} o GET /api/v1/charges/{id}/receipt según el caso).
Los listados se devuelven en un envoltorio con paginación:

{
  "data": [ { "...": "recurso" } ],
  "has_more": false,
  "total_count": 12,
  "url": "/v1/charges?limit=10"
}

Paginación

Los listados usan paginación por cursor estilo Stripe (6.8):

Parámetro	Descripción
`limit`	Cantidad por página (default 10, máximo 100).
`starting_after`	ID del último elemento de la página anterior; devuelve los siguientes.
`ending_before`	ID del primer elemento de la página anterior; devuelve los anteriores.

Los POST que crean recursos aceptan el header Idempotency-Key. Si repetís la misma clave con el mismo body, no se crea nada nuevo: se devuelve el recurso original (replay 200). Con la misma clave y un body distinto, recibís un error idempotency_conflict (409).

Recomendado para checkout: usar una clave por pedido (p. ej. el UUID del pedido) para evitar cobros duplicados si el cliente repite el request.

Rate limit

La API tiene un límite de 100 requests por minuto por clave. Cada respuesta incluye los headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Al superarlo recibís 429 Too Many Requests con Retry-After.

Errores

Los errores usan el formato:

{
  "error": "invalid_amount",
  "message": "El monto mínimo por cobro es de USD 4.",
  "detail": "Detalle opcional del error"
}

`error`	HTTP	Causa
`unauthorized`	401	Falta el header `Authorization`.
`invalid_key`	401	La API key es inválida o fue revocada.
`validation_error`	400	Algún parámetro tiene un valor inválido.
`invalid_request`	400	El body es inválido o falta un dato requerido.
`invalid_amount`	400	El monto no es válido o es menor a USD 4.
`minimum_amount`	400	El precio de un plan recurrente es menor a USD 4.
`prices_required`	400	Un link `recurring` necesita al menos un precio.
`too_many_prices`	400	Se superó el máximo de precios por link.
`invalid_interval`	400	El `interval` del precio no es `day`, `week`, `month` o `year`.
`invalid_interval_count`	400	El `interval_count` está fuera de rango.
`invalid_trial`	400	El `trial_period_days` está fuera de rango (1–90).
`link_not_found`	404	No existe ese link de pago.
`charge_not_found`	404	No existe ese cobro.
`subscription_not_found`	404	No existe esa suscripción.
`account_not_connected`	400	La cuenta Stripe Express no está conectada.
`account_not_ready`	400	La cuenta Express no completó la verificación.
`sandbox_account_not_ready`	400	La cuenta Express de prueba no está conectada. Leé Modo sandbox.
`kyc_required`	400	La verificación KYC está pendiente.
`payment_link_inactive`	400	El link de pago no está activo.
`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.
`unexpected_error`	500	Error interno inesperado.

Endpoints

Crear link de pago único — POST /api/v1/payment-links
Crear link de pago recurrente — POST /api/v1/payment-links con type: "recurring"
Listar y gestionar links — GET /api/v1/payment-links, GET / PATCH / DELETE /api/v1/payment-links/{id}
Checkout por compra — POST /api/v1/payment-links/{id}/checkout
Cobros — GET /api/v1/charges, GET /api/v1/charges/{id}, GET /api/v1/charges/{id}/receipt
Suscripciones — GET /api/v1/subscriptions, GET /api/v1/subscriptions/{id}, POST /api/v1/subscriptions/{id}/cancel, POST /api/v1/subscriptions/{id}/portal
Saldo — GET /api/v1/balance
Retiros — GET /api/v1/payouts
Acreditaciones — GET /api/v1/acreditaciones
Eventos de reconciliación — GET /api/v1/events
Webhooks salientes — configurar y verificar notificaciones
Autenticación — claves, rotación y seguridad
Modo sandbox — probá tu integración sin mover dinero real

Base URL

https://api.vexorpay.com/api/v1

Autenticación

Todos los endpoints requieren tu clave de API, enviada en el header Authorization:

Authorization: Bearer vxp_u_tu_clave

Aprendé más en Autenticación.

Formato de respuesta

Los recursos (links, cobros, suscripciones) se devuelven como objeto plano (GET /api/v1/payment-links/{id}, GET /api/v1/charges/{id} o GET /api/v1/charges/{id}/receipt según el caso).
Los listados se devuelven en un envoltorio con paginación:

{
  "data": [ { "...": "recurso" } ],
  "has_more": false,
  "total_count": 12,
  "url": "/v1/charges?limit=10"
}

Paginación

Los listados usan paginación por cursor estilo Stripe (6.8):

Parámetro	Descripción
`limit`	Cantidad por página (default 10, máximo 100).
`starting_after`	ID del último elemento de la página anterior; devuelve los siguientes.
`ending_before`	ID del primer elemento de la página anterior; devuelve los anteriores.

{
  "error": "invalid_amount",
  "message": "El monto mínimo por cobro es de USD 4.",
  "detail": "Detalle opcional del error"
}

`error`	HTTP	Causa
`unauthorized`	401	Falta el header `Authorization`.
`invalid_key`	401	La API key es inválida o fue revocada.
`validation_error`	400	Algún parámetro tiene un valor inválido.
`invalid_request`	400	El body es inválido o falta un dato requerido.
`invalid_amount`	400	El monto no es válido o es menor a USD 4.
`minimum_amount`	400	El precio de un plan recurrente es menor a USD 4.
`prices_required`	400	Un link `recurring` necesita al menos un precio.
`too_many_prices`	400	Se superó el máximo de precios por link.
`invalid_interval`	400	El `interval` del precio no es `day`, `week`, `month` o `year`.
`invalid_interval_count`	400	El `interval_count` está fuera de rango.
`invalid_trial`	400	El `trial_period_days` está fuera de rango (1–90).
`link_not_found`	404	No existe ese link de pago.
`charge_not_found`	404	No existe ese cobro.
`subscription_not_found`	404	No existe esa suscripción.
`account_not_connected`	400	La cuenta Stripe Express no está conectada.
`account_not_ready`	400	La cuenta Express no completó la verificación.
`sandbox_account_not_ready`	400	La cuenta Express de prueba no está conectada. Leé Modo sandbox.
`kyc_required`	400	La verificación KYC está pendiente.
`payment_link_inactive`	400	El link de pago no está activo.
`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.
`unexpected_error`	500	Error interno inesperado.

Endpoints

Crear link de pago único — POST /api/v1/payment-links
Crear link de pago recurrente — POST /api/v1/payment-links con type: "recurring"
Listar y gestionar links — GET /api/v1/payment-links, GET / PATCH / DELETE /api/v1/payment-links/{id}
Checkout por compra — POST /api/v1/payment-links/{id}/checkout
Cobros — GET /api/v1/charges, GET /api/v1/charges/{id}, GET /api/v1/charges/{id}/receipt
Suscripciones — GET /api/v1/subscriptions, GET /api/v1/subscriptions/{id}, POST /api/v1/subscriptions/{id}/cancel, POST /api/v1/subscriptions/{id}/portal
Saldo — GET /api/v1/balance
Retiros — GET /api/v1/payouts
Acreditaciones — GET /api/v1/acreditaciones
Eventos de reconciliación — GET /api/v1/events
Webhooks salientes — configurar y verificar notificaciones
Autenticación — claves, rotación y seguridad
Modo sandbox — probá tu integración sin mover dinero real

Referencia de API

Base URL

Autenticación

Formato de respuesta

Paginación

Idempotencia

Rate limit

Errores

Endpoints

On this page

Referencia de API

Base URL

Autenticación

Formato de respuesta

Paginación

Idempotencia

Rate limit

Errores

Endpoints

On this page