Billing

The PayBridgeNP Billing system handles recurring payments - create a plan, add customers, and start subscriptions. PayBridgeNP generates invoices automatically at each renewal, sends payment links to customers, and manages retries when payments fail.

In live mode, Billing requires a Growth plan or higher on your PayBridgeNP account. In sandbox (test) mode Billing is open on every plan, so you can build and test the full lifecycle before upgrading - with test-mode guardrails: invoice emails are delivered only to your own account email (50 per month, everything else is recorded but not sent), and test subscriptions auto-expire after 12 invoices or 30 days without a payment. Sandbox object limits: 25 customers, 10 active plans, 25 subscriptions, 25 coupons, 25 promotion codes, 10 dunning policies. Coupons and dunning policies are separate per mode - a test coupon or policy never applies in live mode, and the same code can exist in both.

Core concepts

Plans define the recurring charge - amount, interval (monthly, yearly, etc.), trial period, and dunning behavior. Plans are templates; subscriptions are instances. Customers are the people being billed. They exist independently of subscriptions - you can have a customer with no active subscriptions. Subscriptions link a customer to a plan. When you create a subscription, PayBridgeNP immediately generates the first invoice (unless there’s a trial period). Invoices are generated automatically at each billing cycle. Each invoice has a payment link that PayBridgeNP sends to the customer. Invoices go from open → paid once the customer pays, or overdue if they don’t pay in time.

Instead of the hosted payment link, you can collect an invoice with a Fonepay Direct-QR (POST /v1/billing/invoices/{id}/qr) - the customer scans a QR in your own app or at a counter, and on payment the invoice is marked paid and the subscription activates automatically. See Direct-QR for Fonepay.

Step 1: Create a plan

const plan = await paybridgenp.plans.create({
  name: "Pro Monthly",
  amount: 99900,          // Rs. 999.00 in paisa
  intervalUnit: "month",
  intervalCount: 1,       // every 1 month
  trialDays: 14,          // 14-day free trial
  gracePeriodDays: 3,     // 3 days after due before going overdue
  overdueAction: "mark_past_due",
});

console.log(plan.id); // bp_...

Interval options

`intervalUnit`	`intervalCount`	Billing frequency
`month`	`1`	Monthly
`month`	`3`	Quarterly
`year`	`1`	Yearly
`week`	`2`	Every 2 weeks
`day`	`30`	Every 30 days

Dunning settings

Dunning controls what happens when a customer doesn’t pay on time:

Setting	Description
`gracePeriodDays`	Days after due before triggering the overdue action
`reminderDaysBeforeDue`	Send a reminder email N days before the invoice is due
`overdueReminderIntervalDays`	Repeat overdue reminders every N days
`overdueAction`	What to do when overdue: `keep_active`, `mark_past_due`, `pause`, or `cancel`

Step 2: Create a customer

const customer = await paybridgenp.customers.create({
  name: "Aarav Sharma",
  email: "aarav@example.com",
  phone: "9801234567",          // optional
  externalCustomerId: "user_123", // optional - your internal user ID
});

console.log(customer.id); // bc_...

The externalCustomerId field lets you link PayBridgeNP customers to your own user records.

Step 3: Create a subscription

const subscription = await paybridgenp.subscriptions.create({
  customerId: customer.id,
  planId: plan.id,
});

console.log(subscription.id);     // sub_...
console.log(subscription.status); // "trialing" (if plan has trialDays > 0)

When a subscription is created:

If the plan has trialDays > 0 - the subscription starts in trial mode (active / trialing), no invoice is generated until the trial ends
Otherwise - the subscription starts as incomplete, an invoice is generated immediately, and PayBridgeNP sends a payment link to the customer’s email. The subscription becomes active only once that first invoice is paid.

active always means paid. A subscription is incomplete until its first invoice is paid (prepaid activation). Gate access on the subscription being active, or on the first invoice.paid / subscription.activated event - not on subscription.created. The subscription.activated event fires only after the first payment is collected. You can also read latest_invoice.status on the subscription object to see whether it is paid. If the first invoice is never paid within 24 hours, the subscription moves to incomplete_expired and the invoice is voided.

Subscription lifecycle

incomplete → active → past_due → cancelled
   │              ↳ paused → active
   ↳ incomplete_expired   (first invoice never paid)

trial start: active (trialing) → active → ...
future start: draft → incomplete → active → ...

Display status	Meaning
`incomplete`	Created, first invoice not yet paid - no access until paid
`incomplete_expired`	First invoice was never paid within 24 hours - terminal
`draft`	Start date is in the future
`trialing`	Active, in trial period - no invoices yet
`active`	First invoice paid, billing normally
`past_due`	A renewal invoice is unpaid past the grace period
`paused`	Billing paused - no invoices generated
`cancelled`	Ended - no further invoices
`completed`	Reached a natural end date

Managing subscriptions

Pause

await paybridgenp.subscriptions.pause(subscription.id, {
  reason: "Customer requested temporary pause",
});

No invoices are generated while paused. Resume resumes billing from the current period.

Resume

await paybridgenp.subscriptions.resume(subscription.id);

Cancel

// Cancel immediately
await paybridgenp.subscriptions.cancel(subscription.id, {
  reason: "Customer churned",
});

// Cancel at end of current period
await paybridgenp.subscriptions.cancel(subscription.id, {
  atPeriodEnd: true,
});

Change plan

// Change takes effect at the next renewal
await paybridgenp.subscriptions.changePlan(subscription.id, {
  planId: newPlan.id,
});

The current period continues on the old plan. At renewal, the subscription switches to the new plan.

Invoices

Invoices are read-only from the API - PayBridgeNP creates them automatically. Use them to display billing history to customers.

const { data: invoices } = await paybridgenp.invoices.list({
  subscriptionId: subscription.id,
});

for (const invoice of invoices) {
  console.log(invoice.status, invoice.amount_due, invoice.due_at);
}

Invoice status	Meaning
`draft`	Not yet sent
`open`	Sent to customer, awaiting payment
`paid`	Customer paid
`overdue`	Not paid by due date
`void`	Cancelled
`uncollectible`	Dunning exhausted - written off as unrecoverable

Webhook events

PayBridgeNP fires webhook events throughout the subscription lifecycle:

Event	When
`subscription.created`	New subscription created (may be `incomplete` until first payment)
`subscription.activated`	First invoice paid, trial ended, or a paused subscription resumed - billing is now active
`subscription.expired`	First invoice never paid within 24h - subscription is `incomplete_expired`
`subscription.past_due`	A renewal invoice went past due
`subscription.paused`	Subscription paused
`subscription.cancelled`	Subscription cancelled
`invoice.created`	New invoice generated
`invoice.paid`	Customer paid an invoice
`invoice.overdue`	Invoice went past due

Getting Started

Accepting Payments

Checkout

Providers

Subscriptions & Billing

Branding

Operations

Integrations

Core concepts

Step 1: Create a plan

Interval options

Dunning settings

Step 2: Create a customer

Step 3: Create a subscription

Subscription lifecycle

Managing subscriptions

Pause

Resume

Cancel

Change plan

Invoices

Webhook events

​Core concepts

​Step 1: Create a plan

​Interval options

​Dunning settings

​Step 2: Create a customer

​Step 3: Create a subscription

​Subscription lifecycle

​Managing subscriptions

​Pause

​Resume

​Cancel

​Change plan

​Invoices

​Webhook events

Core concepts

Step 1: Create a plan

Interval options

Dunning settings

Step 2: Create a customer

Step 3: Create a subscription

Subscription lifecycle

Managing subscriptions

Pause

Resume

Cancel

Change plan

Invoices

Webhook events