Subscriptions and recurring billing

What you get

Subscriptions turn a one-time sale into recurring revenue without building a billing system. You define the plan once; VEX Pay creates an invoice every period, sends it to your customer in your name, collects it, follows up when it is not paid, and tells your server about every step with webhooks.

• Prices in dollars, paid in bolívares. A plan costs 10.00 USD; the customer pays the Bs equivalent at your account’s current rate (BCV or market, whichever your account uses) at the moment they pay, so your revenue does not lose value between periods.
• Two ways to collect. send_invoice emails a payment link every period (Pago Móvil, Débito Inmediato, card, stablecoins or Colombian pesos — whatever your account accepts). charge_automatically debits the customer’s bank account by domiciliación: they authorize once, then pay nothing by hand. See Automatic charging.
• A hosted invoice page. Every invoice has its own payment page; you never handle payment screens for renewals.
• Emails in Spanish, sent in your name. Invoices, reminders, receipts and charge notices go out as “<your business> vía VEX Pay”, with replies going to your business email.
• Dunning built in. Every invoice gets daily collection attempts: the first when it is issued, then one a day (3 in total by default, up to 15). If it is still unpaid after the last one, the subscription is canceled — and comes back on its own if the customer pays that invoice late.
• Trials, cancel at period end, metadata and cursor pagination, with an API shaped like the billing APIs you already know.

How it works

1. 01
   You create the subscription

   The first period starts now (or when the trial ends). VEX Pay issues the first invoice immediately.

2. 02
   The invoice is collected

   With send_invoice the customer receives an email with the payment link. With charge_automatically VEX Pay debits their account.

3. 03
   It is paid

   The invoice becomes paid, the money lands in your balance like any other payment, the customer gets a receipt, and you get invoice.paid.

4. 04
   The next period starts

   At the end of each period the next one starts and a new invoice is issued. Periods are counted from the start date, so a subscription that starts on the 31st renews on the last day of shorter months.

Quickstart: your first subscription

Use your Test key: nothing is charged, and emails are only delivered to your own business-profile email (see Test mode below). Call the API from your server with curl or one of the SDKs.

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
}

The first invoice exists already: read it with GET /v1/invoices?subscription=sub_… and open its hostedInvoiceUrl to see what your customer sees. In live mode Ana also receives it by email; in test mode the email is only delivered if the customer’s email is your business-profile email.

Prices

A price belongs to a product and fixes the amount and the cycle. The same product can have several prices — monthly and yearly, for example.

Amount, cycle and product never change once the price exists — changing them answers 400. To raise a price, create a new price and archive the old one with POST /v1/prices/:id and { "active": false }. Existing subscriptions keep their price; new ones cannot use an archived price (price_inactive).

Customers

Update with POST /v1/customers/:id (send null to clear a field). DELETE /v1/customers/:id removes a customer with no live subscription; otherwise it answers 409 customer_has_active_subscriptions. Find a customer by email with GET /v1/customers?email=ana@example.com.

Subscriptions

Invoices and the hosted invoice page

Each period has one invoice, numbered per account with no gaps (K7Q2M9XA-0001, -0002, …). It is due when issued. Its hostedInvoiceUrl is a payment page in your name: the customer picks a method and pays the Bs amount at that moment’s rate. Emails show the amount in dollars only, because the bolívar amount depends on the day they pay.

• attemptsTotal, attemptCount and nextPaymentAttempt show where the invoice is in its collection attempts.
• When the invoice is paid through VEX Pay, payment.completed includes invoice: { id, number, subscription }, so your existing payment handler knows which subscription it was for.

Collection, retries and cancellation

Every invoice gets N collection attempts, one a day: attempt 1 the moment it is issued, attempt 2 a day later, and so on. N is the subscription’s collectionAttempts (1–15), else your account default (3 unless you change it). N is fixed on the invoice when it is issued (attemptsTotal), so changing it later applies from the next invoice. Each attempt either emails the invoice (send_invoice) or debits the customer (charge_automatically; if no debit can be made, the attempt emails the invoice instead).

With the default N = 3 that is: attempts on days 0, 1 and 2, past_due on day 1, canceled on day 3. With N = 1 the invoice becomes overdue and the subscription is canceled at the same time, one day after issue. Paying at any point stops the remaining attempts, emails a receipt and returns a past_due subscription to active. A past_due subscription keeps renewing: if a period ends while an invoice is unpaid, the next invoice is still issued.

Choosing N: 3 is a good default for monthly plans. Use more (up to 15) when your customers often pay late, and fewer for daily or weekly plans. Set the account default in Portal → Billing → Settings, or per subscription with collectionAttempts.

Emails to your customers

All emails are in Spanish, show your business name and logo from your business profile, come from facturas@mail.vexwallet.co as “<your business> vía VEX Pay”, and replies go to your business email. Each one is sent once — retries never send duplicates.

Invoice and reminder emails show the dollar amount, the invoice number, the date the subscription will be canceled if unpaid, and the button to the hosted invoice page. They never show a fixed Bs amount, because it is calculated when the customer pays.

Trials and notices

• A trial starts with status trialing and no invoice. When it ends, the first paid period starts and its invoice is issued.
• customer.subscription.trial_will_end fires 3 days before a trial ends (for trials longer than 3 days) — a good moment to remind the customer.
• invoice.upcoming fires 3 days before each renewal that will happen, with the amount and the next period. Automatic-debit customers also receive the “Aviso de cobro” email then.

Fees and your balance

An invoice paid through VEX Pay is a normal payment: its method’s fee applies as usual (see Pricing) and the money follows the usual balance hold (see Balances & holds). On top of that, VEX Pay charges a billing fee of 0.5% of each paid invoice (unless your agreement says otherwise), in the currency the customer paid. It appears on the invoice as billingFee and in your balance movements.

An automatic debit (domiciliación) carries your bolívar pay-in rate, the same as Débito Inmediato (see Pricing), plus the billing fee. Invoices marked paid out of band (paidOutOfBand: true) move no money and carry no fee.

Webhooks

Subscribe your endpoint to the billing events you need (see Webhooks for registration and signature verification). Unless noted, data is the full object — the same JSON the API returns — plus 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"
}

Test mode

• Everything above works with your Test key, with the same webhooks. Test and live objects are separate.
• Emails go only to your business-profile email. A test-mode email is delivered only when the customer’s email is the email on your business profile; every other address is suppressed. Use that address on your test customers to see exactly what your customers receive.
• Pay test invoices on their hosted page with the test payment methods.
• Automatic charging works in test mode without asking VEX Pay to enable it: a simulator stands in for the bank. See Automatic charging for the phone numbers that simulate each outcome.
• Test clocks are coming soon. Until then, try renewals and dunning with a daily price ("recurring": { "interval": "day" }): a new invoice every 24 hours, and an unpaid one reaches past_due after a day and cancellation after N days.

Errors

Errors use the usual shape: { "error": "<code>", "message": "…" }, plus field for invalid input.

Full request and response schemas for every billing endpoint are in the API reference (API reference).