Venflow API
V1SuscripcionesPor IDCobros

Crear un cobro

POST
/v1/subscriptions/{id}/charges

Authorization

Api-Key<token>

Tu clave API privada (comienza con pvk_)

In: header

Organization<token>

Tu ID de organización

In: header

Path Parameters

idstring
Formatuuid

Header Parameters

Idempotency-Keystring

Clave de idempotencia (OBLIGATORIA). Repetir una llamada con la misma clave devuelve la solicitud creada la primera vez, sin generar un segundo débito: es la protección contra dobles cobros por reintentos de red o timeouts.

La clave es única por organización, así que dos organizaciones pueden usar el mismo valor sin interferir. Usa un valor distinto por cada cobro que quieras generar (por ejemplo, un UUID por cada factura de tu sistema)

Request Body

amount?number

Monto a cobrar, con un máximo de 2 decimales. La moneda la define currency.

Con currency: "USD" (predeterminado) es un monto en dólares (no centavos) y NETO, antes de IVA e impuestos: significa exactamente lo mismo que el precio del plan (price) y ocupa su lugar en esta solicitud. El IVA y las banderas de impuesto del plan se calculan encima, igual que en cualquier ciclo de cobro normal, así que el total de la factura puede ser mayor que este número, y los bolívares que se debitan salen de convertirlo a la tasa BCV del día del cobro.

Con currency: "VES" es el monto EXACTO en bolívares que se debita ese día, IVA incluido. En ese caso el campo es obligatorio: el plan tiene precio en dólares, no en bolívares, así que no hay un valor por defecto que tomar.

Predeterminado (solo en USD): el precio actual del plan principal de la suscripción. Debe ser mayor que 0 y menor o igual a 99999999.99 (el máximo que admite la columna). No existe un tope de negocio relativo al precio del plan: la organización es dueña de su calendario y de sus montos

Formatdouble
Range0.01 <= value <= 99999999.99
charge_date?string

Día en que debe ejecutarse el cobro, en formato ISO YYYY-MM-DD (zona America/Caracas).

Predeterminado: hoy, es decir que el cobro se ejecuta en la próxima corrida del motor. Una fecha futura deja la solicitud en estado scheduled hasta ese día. Una fecha anterior a hoy se rechaza: para cobrar de una vez, omite el campo

Formatdate
currency?string

Moneda en la que va expresado amount. Predeterminado: USD. - USD: monto neto en dólares, con la misma semántica que el precio del plan. Venflow le suma el IVA que corresponda y lo convierte a bolívares a la tasa BCV del día en que se ejecuta el cobro, así que el débito exacto solo se conoce ese día. - VES: los bolívares exactos que quieres debitar ese día, impuestos incluidos. El monto se respeta al céntimo y el equivalente en dólares de la factura se deriva dividiendo entre la tasa BCV del día del cobro. Requiere enviar amount

Value in"USD" | "VES"
metadata?

Pares clave-valor propios de tu sistema (por ejemplo, el número de factura que originó el cobro). Venflow los guarda tal cual y los devuelve en la solicitud y en los webhooks

Propertiesproperties <= 50
retry_policy?string

Qué hacer si el banco RECHAZA el débito. Predeterminado: none. - none: un solo intento. Si el banco rechaza, la solicitud queda failed, recibes un webhook, y reintentar es tu decisión: creas una solicitud nueva con otra clave de idempotencia cuando quieras. Venflow no reintenta por su cuenta. Es el comportamiento histórico, así que una integración escrita antes de que existiera este campo no cambia. - automatic: si el banco rechaza, la factura de este cobro entra a la cola de reintentos (dunning) de Venflow, con la MISMA cantidad de reintentos y los MISMOS días de separación que tu organización ya tiene configurados. La solicitud permanece processing mientras quedan reintentos y termina una sola vez: completed si un reintento se cobra, o failed si se agotan. El webhook final llega una sola vez, al terminar

Value in"none" | "automatic"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.venflow.app/v1/subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/charges" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "amount": 47.5,    "metadata": {      "invoice_number": "F-2026-0154"    }  }'
{
  "amount": 0.1,
  "charge_date": "string",
  "created": 0.1,
  "currency": "USD",
  "failure_reason": "string",
  "id": "string",
  "invoice": "string",
  "livemode": true,
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "object": "charge",
  "payment": "string",
  "retry_policy": "none",
  "status": "scheduled",
  "subscription": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}
{
  "code": "not_found",
  "details": {},
  "message": "string"
}

Listar los cobros de una suscripción GET

Devuelve las solicitudes de cobro de una suscripción, ordenadas por fecha de creación con las más recientes primero. Incluye las canceladas y las fallidas, para que puedas auditar todo lo que pediste sobre esa suscripción.

Reactivar una suscripción cancelada POST

Revive una suscripción cancelada. - Solo aplica a suscripciones en estado `cancelled`. En cualquier otro estado responde 400. - La próxima fecha de cobro se recalcula **desde hoy** según la frecuencia del plan: el cobro se reanuda a partir de ahora, no desde la fecha en que se canceló. - En planes con cuotas limitadas, `reset_billing_cycles: true` reinicia el contador en cero y se vuelve a cobrar la serie completa. El valor por defecto (`false`) conserva las cuotas ya cobradas y solo cobra las que faltaban. Solo aplica a suscripciones canceladas. La próxima fecha de cobro se recalcula desde hoy según la frecuencia del plan, así que el cobro se reanuda a partir de ahora y no desde la fecha en que se canceló.