Suscripciones y cobros recurrentes

Qué obtienes

Con las suscripciones conviertes una venta única en ingresos recurrentes sin construir un sistema de facturación. Defines el plan una sola vez; VEX Pay genera una factura en cada período, se la envía a tu cliente a tu nombre, la cobra, hace seguimiento cuando no se paga y le avisa a tu servidor de cada paso con webhooks.

• Precios en dólares, pagos en bolívares. Un plan cuesta 10.00 USD y el cliente paga el equivalente en Bs a la tasa vigente de tu cuenta (BCV o mercado, según la que uses) en el momento en que paga, así tus ingresos no pierden valor de un período a otro.
• Dos formas de cobrar. send_invoice envía por correo un enlace de pago en cada período (Pago Móvil, Débito Inmediato, tarjeta, stablecoins o pesos colombianos: lo que acepte tu cuenta). charge_automatically debita la cuenta bancaria del cliente por domiciliación: autoriza una sola vez y no vuelve a pagar a mano. Ver Débito automático.
• Página de pago para cada factura. Cada factura tiene su propia página de pago; no tienes que construir pantallas de pago para las renovaciones.
• Correos en español, a tu nombre. Facturas, recordatorios, recibos y avisos de cobro salen como “<tu negocio> vía VEX Pay”, y las respuestas llegan al correo de tu negocio.
• Cobranza incluida. Cada factura tiene intentos de cobro diarios: el primero al emitirse y luego uno por día (3 en total por defecto, hasta 15). Si sigue sin pagar después del último, la suscripción se cancela… y se reactiva sola si el cliente paga esa factura tarde.
• Períodos de prueba, cancelación al final del período, metadata y paginación por cursor, con una API parecida a las APIs de facturación que ya conoces.

Cómo funciona

1. 01
   Creas la suscripción

   El primer período empieza ahora (o al terminar la prueba). VEX Pay emite la primera factura de inmediato.

2. 02
   Se cobra la factura

   Con send_invoice el cliente recibe un correo con el enlace de pago. Con charge_automatically VEX Pay debita su cuenta.

3. 03
   Se paga

   La factura pasa a paid, el dinero entra a tu saldo como cualquier otro pago, el cliente recibe su recibo y tú recibes invoice.paid.

4. 04
   Empieza el siguiente período

   Al terminar cada período empieza el siguiente y se emite una factura nueva. Los períodos se cuentan desde la fecha de inicio: una suscripción que empieza un día 31 se renueva el último día de los meses más cortos.

Inicio rápido: tu primera suscripción

Usa tu clave de prueba: no se cobra nada y los correos solo se entregan al correo de tu perfil de negocio (ver Modo de prueba más abajo). Llama a la API desde tu servidor con curl o con uno de los SDK.

curl --request POST "${API_URL}/v1/products" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "name": "Plan Pro", "priceUsd": "25.00" }'
# → { "id": "PRODUCT_ID", ... }

curl --request POST "${API_URL}/v1/prices" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "product": "PRODUCT_ID",
    "unitAmountUsd": 25,
    "recurring": { "interval": "month", "intervalCount": 1 },
    "nickname": "Pro mensual"
  }'
# → { "id": "price_…", "unitAmountUsd": "25.00", "currency": "USD", ... }

curl --request POST "${API_URL}/v1/customers" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "name": "Ana Pérez",
    "email": "ana@example.com",
    "phone": "04141234567",
    "idNumber": "V12345678",
    "metadata": { "userId": "u_981" }
  }'
# → { "id": "cus_…", ... }

curl --request POST "${API_URL}/v1/subscriptions" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "customer": "cus_…",
    "price": "price_…",
    "collectionMethod": "send_invoice"
  }'

const product = await vexpay.products.create({ name: 'Plan Pro', priceUsd: '25.00' });

const price = await vexpay.prices.create({
  product: product.id,
  unitAmountUsd: 25,
  recurring: { interval: 'month', intervalCount: 1 },
  nickname: 'Pro mensual',
});

const customer = await vexpay.customers.create({
  name: 'Ana Pérez',
  email: 'ana@example.com',
  metadata: { userId: 'u_981' },
});

const subscription = await vexpay.subscriptions.create({
  customer: customer.id,
  price: price.id,
  collectionMethod: 'send_invoice',
});

product = vexpay.products.create({"name": "Plan Pro", "priceUsd": "25.00"})

price = vexpay.prices.create({
    "product": product.id,
    "unitAmountUsd": 25,
    "recurring": {"interval": "month", "intervalCount": 1},
    "nickname": "Pro mensual",
})

customer = vexpay.customers.create({
    "name": "Ana Pérez",
    "email": "ana@example.com",
    "metadata": {"userId": "u_981"},
})

subscription = vexpay.subscriptions.create({
    "customer": customer.id,
    "price": price.id,
    "collectionMethod": "send_invoice",
})

$product = $vexpay->products->create(['name' => 'Plan Pro', 'priceUsd' => '25.00']);

$price = $vexpay->prices->create([
    'product' => $product->id,
    'unitAmountUsd' => 25,
    'recurring' => ['interval' => 'month', 'intervalCount' => 1],
    'nickname' => 'Pro mensual',
]);

$customer = $vexpay->customers->create([
    'name' => 'Ana Pérez',
    'email' => 'ana@example.com',
    'metadata' => ['userId' => 'u_981'],
]);

$subscription = $vexpay->subscriptions->create([
    'customer' => $customer->id,
    'price' => $price->id,
    'collectionMethod' => 'send_invoice',
]);

{
  "id": "sub_3fd84b2d9ad14f74a2d90f2f56984db5",
  "object": "subscription",
  "customer": "cus_…",
  "price": { "id": "price_…", "unitAmountUsd": "25.00", "currency": "USD", "recurring": { "interval": "month", "intervalCount": 1 }, ... },
  "status": "active",
  "collectionMethod": "send_invoice",
  "collectionAttempts": null,
  "paymentMethod": null,
  "currentPeriodStart": "2026-10-21T14:00:00.000Z",
  "currentPeriodEnd": "2026-11-21T14:00:00.000Z",
  "trialStart": null,
  "trialEnd": null,
  "cancelAtPeriodEnd": false,
  "canceledAt": null,
  "cancellationReason": null,
  "latestInvoice": "in_…",
  "methods": [],
  "metadata": {},
  "createdAt": "2026-10-21T14:00:00.000Z",
  "livemode": false
}

La primera factura ya existe: consúltala con GET /v1/invoices?subscription=sub_… y abre su hostedInvoiceUrl para ver lo mismo que ve tu cliente. En producción Ana también la recibe por correo; en modo de prueba el correo solo se entrega si el del cliente es el correo de tu perfil de negocio.

Precios

Un precio pertenece a un producto y fija el monto y el ciclo. Un mismo producto puede tener varios precios, por ejemplo mensual y anual.

El monto, el ciclo y el producto no cambian una vez creado el precio: intentar cambiarlos responde 400. Para subir un precio, crea uno nuevo y archiva el anterior con POST /v1/prices/:id y { "active": false }. Las suscripciones existentes conservan su precio; las nuevas no pueden usar un precio archivado (price_inactive).

Clientes

Actualiza con POST /v1/customers/:id (envía null para borrar un campo). DELETE /v1/customers/:id elimina a un cliente sin suscripciones vigentes; si las tiene, responde 409 customer_has_active_subscriptions. Busca un cliente por correo con GET /v1/customers?email=ana@example.com.

Suscripciones

Facturas y su página de pago

Cada período tiene una factura, numerada por cuenta y sin saltos (K7Q2M9XA-0001, -0002, …). Vence al emitirse. Su hostedInvoiceUrl es una página de pago a tu nombre: el cliente elige el método y paga el monto en Bs a la tasa de ese momento. Los correos muestran el monto solo en dólares, porque el monto en bolívares depende del día en que se pague.

• attemptsTotal, attemptCount y nextPaymentAttempt indican en qué intento de cobro va la factura.
• Cuando la factura se paga a través de VEX Pay, payment.completed incluye invoice: { id, number, subscription }, así tu manejador de pagos actual sabe a qué suscripción corresponde.

Cobro, reintentos y cancelación

Cada factura tiene N intentos de cobro, uno por día: el intento 1 en el momento en que se emite, el 2 un día después, y así sucesivamente. N es el collectionAttempts de la suscripción (de 1 a 15) o, si no lo tiene, el valor por defecto de tu cuenta (3, salvo que lo cambies). N queda fijo en la factura al emitirse (attemptsTotal), así que un cambio posterior aplica desde la próxima factura. En cada intento se envía la factura por correo (send_invoice) o se debita al cliente (charge_automatically; si no se puede hacer el débito, ese intento envía la factura por correo).

Con el valor por defecto N = 3: intentos los días 0, 1 y 2, past_due el día 1 y cancelación el día 3. Con N = 1 la factura vence y la suscripción se cancela al mismo tiempo, un día después de la emisión. Si el cliente paga en cualquier momento, se detienen los intentos restantes, recibe su recibo y una suscripción past_due vuelve a active. Una suscripción past_due sigue renovándose: si el período termina con una factura pendiente, igual se emite la siguiente.

Cómo elegir N: 3 funciona bien para planes mensuales. Usa más (hasta 15) si tus clientes suelen pagar tarde, y menos para planes diarios o semanales. Configura el valor de tu cuenta en Portal → Billing → Settings, o por suscripción con collectionAttempts.

Correos a tus clientes

Todos los correos van en español, con el nombre y el logo de tu perfil de negocio, salen de facturas@mail.vexwallet.co como “<tu negocio> vía VEX Pay”, y las respuestas llegan al correo de tu negocio. Cada correo se envía una sola vez: los reintentos nunca generan duplicados.

Los correos de factura y de recordatorio muestran el monto en dólares, el número de factura, la fecha en que se cancelará la suscripción si no se paga y el botón hacia la página de pago. Nunca muestran un monto fijo en Bs, porque se calcula cuando el cliente paga.

Períodos de prueba y avisos

• Una prueba empieza con estado trialing y sin factura. Al terminar, empieza el primer período pagado y se emite su factura.
• customer.subscription.trial_will_end llega 3 días antes de que termine la prueba (en pruebas de más de 3 días): buen momento para recordárselo al cliente.
• invoice.upcoming llega 3 días antes de cada renovación que vaya a ocurrir, con el monto y el próximo período. Los clientes con débito automático reciben en ese momento el correo “Aviso de cobro”.

Comisiones y tu saldo

Una factura pagada a través de VEX Pay es un pago normal: aplica la comisión de su método (ver Precios) y el dinero sigue la retención habitual del saldo (ver Saldos y retenciones). Además, VEX Pay cobra una comisión de facturación del 0,5% de cada factura pagada (salvo que tu acuerdo diga otra cosa), en la moneda en que pagó el cliente. Aparece en la factura como billingFee y en los movimientos de tu saldo.

Un débito automático (domiciliación) paga tu tarifa de cobros en bolívares, la misma de Débito Inmediato (ver Precios), más la comisión de facturación. Las facturas marcadas como pagadas fuera de VEX Pay (paidOutOfBand: true) no mueven dinero ni pagan comisión.

Webhooks

Suscribe tu endpoint a los eventos de facturación que necesites (ver Webhooks para el registro y la verificación de firmas). Salvo que se indique otra cosa, data es el objeto completo, el mismo JSON que devuelve la API, más livemode.

curl --request POST "${API_URL}/v1/webhooks" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "url": "https://example.com/webhooks/vexpay",
    "events": [
      "customer.subscription.created", "customer.subscription.updated",
      "customer.subscription.deleted", "customer.subscription.reactivated",
      "invoice.paid", "invoice.payment_failed", "invoice.overdue",
      "payment_method.attached", "payment_method.updated"
    ]
  }'

{
  "event": "invoice.paid",
  "data": {
    "id": "in_3fd84b2d9ad14f74a2d90f2f56984db5",
    "object": "invoice",
    "number": "K7Q2M9XA-0001",
    "status": "paid",
    "customer": "cus_…",
    "subscription": "sub_…",
    "collectionMethod": "send_invoice",
    "amountDueUsd": "25.00",
    "amountPaidUsd": "25.00",
    "currency": "USD",
    "periodStart": "2026-10-21T14:00:00.000Z",
    "periodEnd": "2026-11-21T14:00:00.000Z",
    "dueDate": "2026-10-21T14:00:00.000Z",
    "attemptsTotal": 3,
    "attemptCount": 1,
    "nextPaymentAttempt": null,
    "paidAt": "2026-10-21T15:12:40.000Z",
    "paidOutOfBand": false,
    "paymentId": "9b2c…",
    "billingFee": { "amount": "12.50", "currency": "VES", "percent": "0.5" },
    "hostedInvoiceUrl": "https://pay.vexwallet.co/pay/in-…",
    "createdAt": "2026-10-21T14:00:00.000Z",
    "livemode": true
  },
  "timestamp": "2026-10-21T15:12:41.000Z"
}

Modo de prueba

• Todo lo anterior funciona con tu clave de prueba, con los mismos webhooks. Los objetos de prueba y de producción son independientes.
• Los correos solo van al correo de tu perfil de negocio. En modo de prueba un correo solo se entrega si el correo del cliente es el de tu perfil de negocio; cualquier otra dirección se suprime. Usa esa dirección en tus clientes de prueba para ver exactamente lo que reciben tus clientes.
• Paga las facturas de prueba en su página con los métodos de prueba.
• El débito automático funciona en modo de prueba sin pedirle nada a VEX Pay: un simulador hace las veces del banco. Ver Débito automático para los teléfonos que simulan cada resultado.
• Los relojes de prueba (test clocks) llegarán pronto. Mientras tanto, prueba renovaciones y cobranza con un precio diario ("recurring": { "interval": "day" }): una factura nueva cada 24 horas, y una sin pagar llega a past_due en un día y a la cancelación en N días.

Errores

Los errores tienen la forma habitual: { "error": "<código>", "message": "…" }, más field cuando un dato es inválido.

Los esquemas completos de solicitud y respuesta de cada endpoint de facturación están en la referencia de la API (Referencia de la API).