Subscriptions

​

How it works

1. Your server creates a payment session with a subscription object, using your secret key. amount is your price for one period.
2. The customer pays the first period on the Payviox payment page, with a card, Apple Pay or Google Pay. This payment goes through the usual fraud checks, the customer explicitly authorizes the recurring charge, and the card is saved for the renewals.
3. When the first payment succeeds, Payviox creates the subscription (psub_...) and sends you a succeeded webhook with a subscription block.
4. Payviox then sets up a Stripe Billing subscription on your own Stripe account, starting at the end of the paid period. Stripe charges each renewal automatically — the money lands on your Stripe account, as for your one-time Stripe payments.
5. Each renewal reaches you as a new succeeded webhook, with order_id = {your order_id}-{cycle}. Failed renewals and cancellations have their own events.
6. The customer can cancel at the end of the paid period from a self-service link; you can cancel or resume from your backend or from the dashboard.

​

Before you start

​

Connect Stripe with card or wallets

• In the Payviox dashboard, Providers → Stripe must be connected (publishable key, secret key and webhook signing secret) — the same setup as for one-time Stripe payments.
• At least one of these methods must be active: card (stripe_credit), Apple Pay (stripe_apple_pay), Google Pay (stripe_google_pay). They’re the only methods offered on the payment page of a subscription.

​

Enable the Stripe renewal events

​

Turn on the subscription webhooks in Payviox

​

Create a subscription session

const PLANS = {
  pro_monthly: { name: 'Pro plan', price: 999, interval: 'month', interval_count: 1 },
  pro_yearly: { name: 'Pro plan (yearly)', price: 9990, interval: 'year', interval_count: 1 },
};

app.post('/api/subscribe', requireLogin, async (req, res) => {
  const plan = PLANS[req.body.plan];
  if (!plan) return res.status(400).json({ error: 'unknown_plan' });

  const response = await fetch('https://api.payviox.com/session', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PAYVIOX_SECRET_KEY}`, // sk_
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: plan.price, // price of ONE period, in cents
      currency: 'USD',
      customer: req.user.id, // your ID: lets you find the subscription later
      email: req.user.email,
      order_id: `sub_${req.user.id}_${Date.now()}`, // renewals: `${order_id}-2`, `-3`…
      description: plan.name,
      ip: req.ip,
      metadata: { user_id: req.user.id, plan: req.body.plan },
      subscription: { interval: plan.interval, interval_count: plan.interval_count },
      items: [{ name: plan.name, quantity: 1, price: plan.price }],
    }),
  });

  const body = await response.json();
  if (!response.ok) {
    // e.g. 400 subscription_setup_incomplete: body.missing_events lists the Stripe events to enable
    console.error('Payviox session failed', response.status, body);
    return res.status(502).json({ error: 'checkout_unavailable' });
  }

  res.json({ session_id: body.session_id });
});

curl https://api.payviox.com/session \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "amount": 999,
    "currency": "USD",
    "customer": "customer_abc123",
    "email": "john@example.com",
    "order_id": "sub_customer_abc123_1760351400",
    "description": "Pro plan",
    "ip": "203.0.113.42",
    "metadata": { "user_id": "usr_123", "plan": "pro_monthly" },
    "subscription": { "interval": "month", "interval_count": 1 },
    "items": [{ "name": "Pro plan", "quantity": 1, "price": 999 }]
  }'

<script src="https://sdk.payviox.com/payviox.js"></script>
<script>
  const payviox = new Payviox('pk_live_your_key');

  document.querySelector('#subscribe').addEventListener('click', async () => {
    const { session_id } = await fetch('/api/subscribe', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ plan: 'pro_monthly' }),
    }).then((r) => r.json());

    payviox.openSession(session_id); // redirects to the payment page
  });
</script>

​

Handle the webhooks

// After verifying the signature (see Webhook Integration)
switch (data.type) {
  case 'succeeded':
    if (!data.subscription) return fulfillOrder(data.order_id, data); // one-time payment

    await db.subscriptions.upsert({
      id: data.subscription.id,
      user_id: data.metadata.user_id,
      paid_until: data.subscription.current_period_end, // end of the period just paid
      management_url: data.subscription.management_url,
    });
    if (data.subscription.cycle === 1) {
      await sendWelcomeEmail(data.metadata.user_id, data.subscription.management_url);
    }
    break;

  case 'subscription_payment_failed':
    await sendPaymentIssueEmail(data.subscription.id, data.failure_reason);
    break;

  case 'subscription_canceled':
    // Access ends at paid_until (stored from the last `succeeded`)
    await db.subscriptions.update(data.subscription.id, { canceled: true });
    break;
}

• Idempotency: deduplicate on order_id + type, as for one-time payments. Each cycle has its own order_id (order_12345, order_12345-2, …), so renewals never collide.
• Fraud review: the first payment can be pending_review before succeeded — don’t give access yet. Renewals aren’t reviewed: they arrive directly as succeeded.
• Failed renewals: you get one subscription_payment_failed per cycle, even if Stripe retries several times. Its subscription.current_period_end is the end of the period that wasn’t paid — don’t extend access from it. If a retry succeeds, you receive succeeded with the same order_id. The retry schedule, and what happens when all retries fail, are set in your Stripe Billing settings (failed payments / revenue recovery): we recommend canceling the subscription, so you receive subscription_canceled. If Stripe leaves it unpaid instead, it stays past_due in Payviox and no further event is sent.
• authentication_required: the bank wants the customer to approve the renewal (3D Secure), which Stripe retries alone can’t solve. Payviox doesn’t contact the customer: enable Stripe’s emails with a hosted confirmation link for payments that require 3D Secure in your Stripe Billing settings, or ask the customer to subscribe again.
• Cancellation: scheduling a cancellation (by you or the customer) sends no event — subscription_canceled arrives when the subscription actually ends. It’s attached to the signup payment (order_id = your original one, cycle = 1): identify the subscription with subscription.id. When you cancel immediately yourself, it’s your call whether access ends now or at the end of the paid period.

​

Let customers manage their subscription

• see the price, the next payment date and the card used;
• cancel at the end of the paid period — they keep what they paid for;
• undo their own cancellation before the period ends. If you scheduled the cancellation, the page tells them to contact you instead.

​

Cancel or resume from your backend

• Cancel now (at_period_end: false) also voids the subscription’s unpaid Stripe invoices, so no pending retry can charge the customer afterwards. There’s no automatic refund.
• Resume only works on a cancellation scheduled on your side (cancel_requested_by api, manager, or null for one scheduled from your Stripe dashboard). A cancellation scheduled by the customer (payer) can only be undone by the customer, from their management link; one scheduled by Payviox (admin, system) requires support. Both return 403. The customer’s cancellation withdraws their consent to be charged: renewing anyway would be an unauthorized charge, the typical cause of “canceled recurring payment” disputes.

# Cancel at the end of the paid period (default) — can be undone
curl -X POST https://api.payviox.com/subscriptions/psub_8fKx2LmQp4ZrT7vW1nYc3aBd/cancel \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

# Cancel now — no further charges, no automatic refund
curl -X POST https://api.payviox.com/subscriptions/psub_8fKx2LmQp4ZrT7vW1nYc3aBd/cancel \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "at_period_end": false }'

# Undo a scheduled cancellation
curl -X POST https://api.payviox.com/subscriptions/psub_8fKx2LmQp4ZrT7vW1nYc3aBd/resume \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

​

Limits

• USD only, like every Payviox session. Minimum 100 cents per period.
• Card, Apple Pay and Google Pay through Stripe only. Other providers and local methods aren’t offered for subscriptions.
• No free trial: the first period is charged when the customer subscribes.
• No plan catalog: price and interval are set per session. To change a customer’s price or interval, cancel at period end and have them subscribe again with a new session — there’s no upgrade or proration.
• Intervals up to 3 years: 1095 days, 156 weeks, 36 months or 3 years per period.
• The customer can’t update their card. If it expires or keeps being declined, renewals fail; once the subscription is canceled, invite the customer to subscribe again.
• Fraud screening applies to the signup payment only, not to renewals.

​

Test your integration

1. Connect Stripe in Payviox with your Stripe test-mode keys and test-mode webhook signing secret, and enable the five events on the test-mode endpoint.
2. Create a subscription session with { "interval": "day", "interval_count": 1 } so the first renewal happens one day later.
3. Pay with a Stripe test card:
   • 4242 4242 4242 4242 — signup and renewals succeed.
   • 4000 0027 6000 3184 — requires authentication on every charge: the signup succeeds after you complete the test authentication, and the renewal fails with failure_reason: "authentication_required".
4. Check that you received succeeded with subscription.cycle: 1, then fetch the subscription with Get Subscription: provider_subscription_id is filled within about a minute, and the subscription shows up in your Stripe dashboard (test mode).
5. Open the management_url, cancel, then undo — and check cancel_at_period_end with the API.

​

Troubleshooting