WebPay Integration

WebPay is a hosted payment page that handles the mobile number collection and payment flow for you. Every bill has a webPayUrl that you can redirect customers to.

How it works

1. Create a bill via the API (with or without a mobile number)
2. Redirect the customer to bill.webPayUrl
3. The customer enters their mobile number and pays
4. On successful payment, the customer is redirected back to your site

URL parameters

The webPayUrl supports additional query parameters for customizing the flow:

Parameter	Description
bill	Bill UUID (automatically included)
mobile	Pre-fill the mobile number field
redirect	URL to redirect to after successful payment
cancel	URL for the "cancel" link

Example: Custom redirect

const bill = await api.issue(
  new cashless.BillParams(null, 5000, 'ORDER-001')
);

// Add redirect URL
const paymentUrl = `${bill.webPayUrl}&redirect=${encodeURIComponent(
  'https://yoursite.com/order/001/success?status=paid'
)}&cancel=${encodeURIComponent(
  'https://yoursite.com/order/001'
)}`;

// Redirect customer
res.redirect(paymentUrl);

After successful payment, the customer is redirected to:

https://yoursite.com/order/001/success?status=paid&cashless_bill_uuid=a1b2c3d4-...

The cashless_bill_uuid parameter is appended automatically so you can verify the payment.

Example: Pre-filled mobile

const paymentUrl = `${bill.webPayUrl}&mobile=0712345678`;

Payment page behavior

1. Loading -- The page fetches bill details (merchant name, amount)
2. Input -- Customer enters their mobile number (10 digits, starting with 0)
3. USSD push -- Customer clicks "Pay with mobile", a USSD prompt appears on their phone
4. Polling -- The page polls for payment status every 5 seconds
5. Success -- On FULLY_PAID, redirects to the redirect URL (with 5-second delay)

Integration patterns

Redirect (simplest)

// After creating bill, redirect the browser
app.post('/checkout', async (req, res) => {
  const bill = await api.issue(params);
  const returnUrl = `https://yoursite.com/orders/${orderId}/complete`;
  res.redirect(`${bill.webPayUrl}&redirect=${encodeURIComponent(returnUrl)}`);
});

// Handle the return
app.get('/orders/:id/complete', async (req, res) => {
  const billId = req.query.cashless_bill_uuid;
  const bill = await api.get(billId);
  if (bill.status.name === 'FULLY_PAID') {
    // Order paid
  }
});

New window/tab

<button onclick="window.open(paymentUrl, '_blank')">
  Pay Now
</button>

Then poll the API from your main page to detect when payment completes.