Payment Flows

Starting a payment always follows the same pattern: build the gateway's payment data, call the gateway, then act on the typed result. Each flow has its own result class with exactly the fields that flow needs, and every result has a flow property ('redirect', 'form', 'qr' or 'app'), so a switch on payment.flow narrows the PaymentResult union.

Result	What you do	Returned by
RedirectPayment	Redirect the customer to payment.url	kbz.pwa, wave.initiate
FormPayment	Return payment.toHtml()	aya.initiate, cs.initiate
QrPayment	Show the QR to the customer	kbz.qr, yoma.initiate, yoma.renewQr
AppPayment	Return the signed payload to your mobile app	kbz.app

Every method validates the payment data first and throws InvalidPaymentDataError before any request is sent. Call the gateway's static validate() yourself to check the data earlier, e.g. KbzPay.validate(data) while handling a form. The customer finishing on the gateway's side is never proof of payment: fulfill orders from the verified callback or a status check.

The samples on this page and the gateway pages are node:http handlers; Framework Integration shows Express, Fastify, Next.js and Hono.

Redirect Payments

Here is the flow with the KBZ Pay PWA; Wave Money works the same way with its own payment page.

Redirect payment with the KBZ Pay PWA

The gateway hosts its own payment page. Send the customer there.

import type { IncomingMessage, ServerResponse } from 'node:http';
import { Amount, KbzPay } from '@laranex/myanmar-payments';

const kbz = KbzPay.fromEnv(process.env);

async function checkout(
  req: IncomingMessage,
  res: ServerResponse,
): Promise<void> {
  const payment = await kbz.pwa({
    orderId: 'ORDER_1',
    amount: Amount.kyat(10000),
    callbackUrl: 'https://shop.test/payments/kbz/callback',
  });
  res.writeHead(302, { Location: payment.url }).end();
}

payment.gatewayReference holds the gateway's ID for the attempt (KBZ prepay_id, Wave transaction_id).

Form Payments

Here is the flow with AYA Pay; CyberSource works the same way with its hosted checkout.

Form payment with AYA Pay

The gateway expects the customer's browser to POST a signed form. toHtml() returns a complete page that submits the form as soon as it loads, with every value escaped:

async function ayaCheckout(
  req: IncomingMessage,
  res: ServerResponse,
): Promise<void> {
  // no network call: synchronous, never awaited
  const payment = aya.initiate(data);
  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
  res.end(payment.toHtml());
}

To build the form yourself, use action, fields (an ordered array of { name, value }) and enctype with your template engine, which escapes every value:

<form
  id="payment-form"
  method="POST"
  action={payment.action}
  encType={payment.enctype}
>
  {payment.fields.map((field) => (
    <input
      key={field.name}
      type="hidden"
      name={field.name}
      value={field.value}
    />
  ))}
</form>

Post the fields unchanged: they are signed. payment.field(name) looks up one value and payment.values() returns them as an object. AYA expects multipart/form-data, which enctype carries.

QR Payments

Here is the flow with Yoma MMQR, whose QR expires after 120 seconds; a KBZ Pay QR follows the same steps without renewals.

QR payment with Yoma MMQR

Gateways return QR codes in two shapes:

Field	Gateway	Use it as
qrString	KBZ Pay	A payload: encode it into a QR image with any QR library, e.g. qrcode
qrImage	Yoma MMQR	A base64 image: display it as is, e.g. with qrImageDataUri()

async function yomaCheckout(
  req: IncomingMessage,
  res: ServerResponse,
): Promise<void> {
  const payment = await yoma.initiate(data);
  const until = payment.expiresAt?.toLocaleTimeString();
  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
  res.end(`<img src="${payment.qrImageDataUri()}" alt="Scan to pay">
<p>Payable until ${until}</p>`);
}

expiresAt is a Date when the gateway limits how long the QR is payable (undefined otherwise), and reference holds the ID used for status checks (Yoma refLabel, KBZ prepay_id).

App Payments

Here is the flow with the KBZ Pay mobile SDK.

In-app payment with the KBZ Pay SDK

The KBZ Pay mobile SDK needs a signed order string. AppPayment.toJSON() returns the values with the SDK's names, so return it to your app as JSON; the app passes the values to KBZPay.startPay():

async function kbzAppCheckout(
  req: IncomingMessage,
  res: ServerResponse,
): Promise<void> {
  const payment = await kbz.app(data);
  res.writeHead(200, { 'Content-Type': 'application/json' });
  // {"orderId", "orderInfo", "sign", "signType"}
  res.end(JSON.stringify(payment));
}

The SDK's own result only means the payment screen closed; rely on the callback or kbz.status().

Handling Any Result

import type { ServerResponse } from 'node:http';
import type { PaymentResult } from '@laranex/myanmar-payments';

function respond(payment: PaymentResult, res: ServerResponse): void {
  switch (payment.flow) {
    case 'redirect':
      res.writeHead(302, { Location: payment.url }).end();
      break;
    case 'form':
      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
      res.end(payment.toHtml());
      break;
    case 'qr':
      res.end(payment.qrImageDataUri() ?? payment.qrString);
      break;
    case 'app':
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify(payment));
      break;
  }
}

See Results for every field.