SMS notifications

Automatic SMS to your customers for payments, refunds, and invoice reminders. Premium-gated, sandbox-safe, fully audited.

PayBridgeNP sends transactional SMS to your customers’ Nepali phone numbers for the events your business cares about - successful payments, failed payments, refunds, and invoice reminders. Every send (and every suppression) is logged so you can verify what went out and why.

SMS is a Premium feature. On the free plan, the SMS dispatcher logs each event as skipped_free_plan so you can see what would have gone out, but does not contact the provider.

What triggers an SMS

Template	Event	Recipient
payment.succeeded	A checkout session completes successfully	The customer who paid
payment.failed	A provider returns failure or the customer abandons	The customer who tried to pay
refund.processed	You issue a refund (full or partial) from the dashboard or API	The original customer
invoice.created	A subscription invoice is generated	The billing customer
invoice.due	An open invoice’s due date is approaching	The billing customer
invoice.overdue	An invoice passes its due date unpaid	The billing customer

A customer phone number must be present on the checkout session, payment, or billing customer for SMS to fire - there’s no separate phone-collection step.

Sandbox testing - real sends, monthly quota

Sandbox sessions get a small monthly quota of real SMS sends so you can verify the integration end-to-end before flipping live. Currently 10 SMS per merchant per calendar month - your sandbox sends actually go through the SMS provider and reach the recipient phone, so you can confirm formatting, delivery, and template rendering without trusting that prod will work.

Free and Premium merchants both get the sandbox quota - this is part of our sandbox-openness policy (Stripe-style: sandbox lets you prove the integration before deciding to upgrade).

Beyond the cap, sandbox events log as skipped_sandbox_quota with the full message body. The quota resets at the start of each calendar month - no manual reset, no carry-over.

The SMS dashboard shows your remaining sandbox quota at the top of the page: “Sandbox SMS test quota - 7 of 10 - 3 remaining”.

To test the real send path beyond the sandbox quota, switch your project to live mode (Settings → Environment → “Switch to live”) and use a real phone number you control. Live sends require a Premium plan.

Premium gating (live mode)

In live mode, only Premium merchants can send SMS. The dispatcher resolves merchant entitlements on every send and short-circuits with status: skipped_free_plan for non-Premium accounts. The log row still shows the would-have-been-sent body - handy if you’re evaluating whether to upgrade.

In sandbox mode, every merchant on every plan can send up to the monthly quota - no Premium gate.

When you upgrade, in-flight live events from the moment of upgrade onward send normally. There’s no backfill of skipped sends.

When you downgrade, the next live event after your billing period ends gets skipped_free_plan again. No SMS is held in a queue. Sandbox quota stays available either way.

Phone number format

The SMS API expects 10-digit Nepali mobile numbers. The dispatcher accepts and normalizes:

• 9XXXXXXXXX (10 digits, starts with 96–99) - used as-is
• 977XXXXXXXXXX (13 digits with country code) - country code stripped
• +977XXXXXXXXXX (E.164) - formatting and country code stripped

Spaces, hyphens, parentheses, and dots are tolerated and stripped. Numbers that don’t match these formats log as skipped_invalid_phone with the original value preserved for debugging.

Viewing SMS history

The SMS history page in your dashboard (Account → SMS) shows every send attempt for the last 30 days, including suppressed ones. Each row carries:

• Status pill - sent, failed, skipped_sandbox_quota, skipped_sandbox, skipped_free_plan, skipped_invalid_phone, or skipped_no_provider
• Template - which event triggered it
• Recipient - the normalized phone number
• Mode - live or sandbox
• Body preview - the exact text that was (or would have been) sent
• Timestamp

Use the filter pills to narrow by status or mode. The summary cards at the top show running counts for the current month.

Body templates

Bodies are short, plain text, optimised to fit a single SMS segment (160 ASCII characters). They include:

• The amount in NPR (e.g. NPR 1,500)
• Your merchant name as registered in PayBridgeNP
• For invoice reminders: a short hosted-token URL the customer can click to pay

You cannot customize the body in this release. If you need branded messaging, contact support - we’re tracking demand for a v2 with merchant-defined templates.

Cost

PayBridgeNP currently does not pass SMS costs through to merchants - they’re absorbed into the Premium plan. There’s no per-message charge or quota beyond what the SMS provider’s network capacity supports. If your sending volume becomes unusual (many thousands per day), our admin team will reach out before throttling.

Failure modes

Status	What happened	What to do
failed	The provider rejected the message after we attempted to send. Common causes: invalid number not caught by client-side validation, blocked content keywords, provider outage.	Check the errorMessage field in the log row. For repeated failures, contact support with the row IDs.
skipped_invalid_phone	The recipient number didn’t normalise to a Nepali 10-digit.	Validate phone format on your collection forms. The dispatcher won’t retry.
skipped_no_provider	Our SMS provider isn’t configured for this environment (only happens in self-hosted setups).	Not applicable to merchants on the hosted PayBridgeNP - contact support if you see this.
skipped_sandbox	Sandbox SMS is disabled platform-wide (only happens in self-hosted setups with SANDBOX_SMS_MONTHLY_CAP=0).	Not applicable on hosted PayBridgeNP.
skipped_sandbox_quota	Reached the monthly sandbox SMS test quota for this merchant.	Resets at the start of next month. To send more sandbox SMS now, switch to live mode (Premium required for live).
skipped_free_plan	Account is on the free plan and the session is in live mode.	Upgrade to Premium to enable live SMS. Sandbox sends are open to all plans.

Privacy and retention

The body of each SMS is stored in the log so you can audit what your customers received. Bodies contain only the same information already visible to you in the corresponding payment, refund, or invoice - no additional PII. SMS log rows are retained for the same period as your other transactional data (Free: 30 days, Premium: unlimited).

Disabling SMS

Premium merchants who want to selectively suppress SMS templates (e.g. send refund SMS but not payment-success SMS) can toggle individual templates in Settings → Notifications. Toggling a template off logs subsequent events as skipped_template_disabled and does not call the provider.

To disable SMS entirely, downgrade to the free plan or contact support to apply a per-merchant override.