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. In sandbox mode, every plan can build and test the full Billing lifecycle. See the sandbox limits.

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.

Sandbox limits

Sandbox Billing is open on every plan with these account-level guardrails:

Resource	Sandbox limit
Customers	25
Active plans	10
Non-terminal subscriptions	25
Active coupons	25
Active promotion codes	25
Active dunning policies	10
Delivered invoice emails	50 per calendar month, sent only to your PayBridgeNP account email

Other sandbox emails are recorded but not sent. A sandbox subscription auto-expires after 12 generated invoices or 30 days without a payment. Coupons and dunning policies are mode-specific, so a sandbox coupon or policy never affects live Billing; the same code can exist once in each mode. For usage, invoice items, subscription discounts, dunning actions, and proration, use a key belonging to the subscription or invoice’s project and mode. Another project’s key cannot access these records, even within the same account. A proration target plan must also belong to that project and mode. Dunning policy definitions remain shared within an account and mode.

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:

A future startDate displays as draft. At the start date it displays as trialing when a trial follows, otherwise active.
A trial displays as trialing, and no invoice is generated until the trial ends.
An immediate subscription without a trial starts as incomplete. PayBridgeNP generates the first invoice and sends its payment link; the subscription becomes active when that invoice is paid.

Do not grant paid access from status alone. active means billing is enabled, but it can coexist with an open first invoice after a trial or an overdue renewal when the plan uses keep_active. Base access for a billing period on that period’s invoice.paid event or paid invoice record. For immediate prepaid activation, the subscription stays incomplete until the first invoice is paid; if it remains unpaid for 24 hours, it becomes incomplete_expired and the invoice is voided.

Subscription lifecycle

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`	Billing enabled. Check the invoice for the period before granting paid access.
`past_due`	A renewal invoice is unpaid past the grace period
`paused`	Billing paused - no invoices generated
`cancelled`	Ended - no further invoices
`completed`	Terminal - no further invoices. Open-ended plans normally end as `cancelled`.

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, a `past_due` subscription recovered, or a paused subscription resumed
`subscription.trial_ended`	Trial ended and the first post-trial invoice was generated
`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

Sandbox limits

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

​Sandbox limits

​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

Sandbox limits

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