Products

Get paid

Move money

Infrastructure

Solutions

By industry

Developers

Build

Tools

npm i @pediwave/node
Pricing
Company
Get started Sign in

Billing & subscriptions

Recurring revenue on every rail.

Subscriptions on direct debit, wallet autodebit, and transfer invoices for feature phones, with card on file and USSD coming. When a charge fails, PediWave retries on the days your customers get paid and falls back to their backup method.

Get started Talk to sales

Test keys in five minutes. Billing runs in the sandbox with test clocks ↗ (opens docs site).

Illustrative. A failed direct debit cycle recovered from the customer's backup wallet mandate, with the subscription kept active through the grace period.
Consent is taken once per rail. Card on file follows our PCI DSS certification; mobile money mandates follow the mobile money rail.

Every recurring rail

One subscription. A backup method behind it.

Take consent once, on the rail your customer prefers: a direct debit mandate authorised with their bank, or a wallet autodebit approved with their PIN. Each cycle is charged without asking again. Add a backup method and a soft decline on one moves to the other. Customers who refuse mandates get an invoice every cycle, paid by transfer. Card on file, saved with 3D Secure, and USSD invoices are coming.

How mandates work ↗ (opens docs site)
Illustrative. Smart Dunning shows the signals and the choice for every case.

Smart Dunning Coming

Retries on the day your customer gets paid.

Today, every failed cycle is retried by its decline reason on a schedule tuned to Nigerian salary days, inside a grace period, with a pay-now link the customer can use on any rail. Smart Dunning goes further for each customer: it decides when to retry, on which rail, through which channel, with what message, and when to stop or hand over to a person. It can warn a customer three days before a charge that is likely to fail, so the failure never happens.

Smart Dunning never retries a payment whose result is unknown, never exceeds your attempt limits, keeps quiet hours from 22:00 to 07:00 by default, and respects opt-outs. Every decision shows the signals behind it.

How retries are decided ↗ (opens docs site)
Illustrative. A mid-cycle upgrade, prorated on the next invoice.

Plans and changes

Customers change plans. The invoice keeps up.

Upgrade or downgrade mid-cycle and PediWave prorates the difference, on the next invoice or straight away. Schedule a downgrade for the end of the period, pause collection and resume, or cancel at period end with access until then. Trials, coupons and promotion codes are built in, and you can preview the next invoice before it is charged.

  • Proration
  • Pause and resume
  • Cancel at period end
  • Trials
  • Coupons
  • Customer portal Coming
  • Quotes Coming
Plan changes in the docs ↗ (opens docs site)
GET /v1/customers/cus_01J9ZK…/entitlements 
{
  "object": "list",
  "customer": "cus_01J9ZK…",
  "features": [
    { "key": "api_calls", "limit": 100000, "used": 64120 },
    { "key": "sso", "enabled": true }
  ]
}
Coming. Entitlements are cached for 60 seconds and refreshed when the subscription changes.

Metering and entitlements Coming

Bill for usage and gate features from one place.

Send usage events as they happen and PediWave adds them up per customer at the end of the cycle. Ask one endpoint what a customer may use, with limits and current usage, and get an event when a limit is reached so your app can block or offer an upgrade.

Read the plan for metering ↗ (opens docs site)
Illustrative. Three instalments, one overdue after the grace period.

Instalments and repayments

Fixed payments on fixed dates, with late fees you set.

A payment schedule is a set of dated charges: school fees in three parts, a phone on instalments, a loan repaid monthly. Set the grace days and a late fee with a cap. Customers can pay an instalment early or clear the balance on a hosted page, and you get an event for every paid and overdue instalment.

Payment schedules in the docs ↗ (opens docs site)
Illustrative. One invoice, payable by transfer from any phone. USSD codes are coming.

Feature phones

Bill customers who have only a phone number.

For customers without a smartphone or a card, each cycle becomes an SMS invoice with a bank account to transfer to and a link to pay. Reminders go out on the due date and two days later. When the invoice is paid, the subscription stays active; when it is not, you decide what happens.

USSD codesComing Pay at an agentComing

Invoices by SMS ↗ (opens docs site)
Coming. Illustrative invoice; the TIN shown is a placeholder.

Automatic tax Coming

VAT on every invoice, at the right rate.

Register your tax numbers and PediWave adds the right VAT line to invoices and Checkout: Nigeria at 7.5 %, with other countries' rates as they launch, inclusive or exclusive of your prices. Export every tax transaction for your return. PediWave computes the tax; it does not file it for you.

Tax in the docs ↗ (opens docs site)

What recovery looks like.

Three ways billing keeps revenue that would otherwise be lost.

Failures that never happen. Coming

A customer whose card expires this month, or whose wallet is short, hears from you before the charge, with a one-tap fix.

Recovered on another rail.

When the default method declines, the charge moves to the backup mandate or becomes a transfer invoice, instead of failing again on the same method.

Customers who stay.

A grace period keeps the subscription active while retries run, and a customer who pays late on the hosted invoice page is reactivated, not cancelled.

Build billing

A plan, a subscription, one webhook.

  • Every cycle is an invoice and a payment intent, so refunds and receipts work as usual.
  • Send an Idempotency-Key and a retried request never creates a second subscription.
  • invoice.payment_failed tells you the reason and the next attempt.
  • Test clocks run a year of cycles in minutes in the sandbox.
Get a test key Billing docs (opens docs site)
Code example 
import PediWave from "@pediwave/node";
const pediwave = new PediWave(process.env.PEDIWAVE_SECRET_KEY);

// ₦15,000.00 a month, in kobo, with a 14-day trial
const plan = await pediwave.plans.create({
  amount: 1500000,
  currency: "NGN",
  interval: "month",
  interval_count: 1,
  trial_days: 14,
});

console.log(plan.id); // plan_01J9ZK…
const subscription = await pediwave.subscriptions.create(
  {
    customer: "cus_01J9ZK3M7Q8R",
    items: [{ price: plan.id, quantity: 1 }],
    default_payment_method: "mdt_debit_01J9ZK",  // direct debit mandate
    backup_payment_method: "mdt_wallet_01J9ZK", // wallet mandate
    collection_method: "charge_automatically",
    grace_days: 3,
  },
  { idempotencyKey: "sub-cus_01J9ZK3M7Q8R-commuter" }
);

// subscription.status === "trialing"
POST /webhooks/pediwave
PediWave-Event-Type: invoice.payment_failed
PediWave-Signature: t=1761984000,v1=5257a869e7…

{
  "type": "invoice.payment_failed",
  "data": { "object": {
    "id": "inv_01J9ZM…",
    "subscription": "sub_01J9ZK…",
    "amount_due": 1500000,
    "attempt_count": 1,
    "decline_code": "insufficient_funds",
    "next_payment_attempt": "2026-11-04T08:00:00Z"
  } }
}
Plans, subscriptions and events as in the API reference. Amounts are in kobo.

Questions about billing

Can customers pay by transfer each month instead of a mandate?
Yes. Set the subscription to send an invoice instead of charging automatically. Each cycle the customer receives an invoice by email, SMS or WhatsApp with a bank account number for that invoice and a link to pay. USSD codes on invoices are coming. The transfer is matched to the invoice and the subscription stays active. This is also the usual choice for business customers.
Can customers pay with a saved card?
Card on file is coming, once our PCI DSS certification completes. When it ships, a customer whose card expires is sent a link to add a new card and the backup method is charged meanwhile, and a hard decline, such as a closed or stolen card, is never retried. Until then, use direct debit, wallet autodebit or transfer invoices.
How do you decide when to retry a failed payment?
By the reason it failed. Insufficient funds is retried on a schedule tuned to salary days, issuer errors are retried within hours, and hard declines are not retried at all. You can change the schedule, the grace period and what happens when retries run out. A payment whose result is unknown is checked with the provider first, never charged again blind. Smart Dunning, which is coming, chooses the day, rail and message per customer and shows why for every case.
Do you support NIBSS e-mandates? (Coming)
Not yet. Direct debit mandates work today through the mandate types your customer's bank supports, authorised by redirect or one-time code. NIBSS e-mandates are coming; when they ship, existing subscriptions can move to them without a new integration.
Can I test a year of billing before going live?
Yes. In the sandbox, a test clock moves time forward for the subscriptions attached to it, so you can watch trials end, cycles bill, retries run and plans change in minutes. The sandbox includes a payment method that always fails for insufficient funds.
Can I bill a fixed number of payments, like a loan or school fees?
Yes. Use a payment schedule rather than a subscription: a list of dated charges with a total, grace days and an optional late fee with a cap. You receive an event for every paid and overdue instalment, and the customer can pay early or clear the balance.
What does billing cost?
Each cycle is a payment on its rail and is priced as that rail is on the Pricing page. Talk to sales about volume pricing for large billing books.

Bill on the rails your customers actually use.

Start in test mode today. Live billing follows verification.

Get started Talk to sales