@atbas/m-mcp 0.1.0

package/knowledge/templates/node/checkout-redirect.tmpl

@@ -0,0 +1,166 @@
+/**
+ * JazzCash — {{FLOW_TITLE}}
+ *
+ * Generated by the JazzCash MCP server from {{FLOW_ID}} ({{CORPUS_VERSION}} guides).
+ * Sources: {{DOC_SOURCES}}
+ *
+ * Renders a signed, auto-submitting form that redirects the customer to the
+ * JazzCash hosted payment page.
+ *
+ * SAFETY NOTES
+ *  - Sandbox and production use the SAME URL. The environment is decided by the
+ *    credentials alone.
+ *  - The Integrity Salt is the HMAC key and must never reach the browser. This
+ *    module runs server-side and emits only the finished hash.
+ *  - pp_ReturnURL must be byte-identical to the URL registered in the portal.
+ *
+ * Requires Node.js 20 or later.
+ */
+
+import { createHmac, randomInt } from 'node:crypto';
+
+export const JAZZCASH_POST_URL = '{{ENDPOINT}}';
+
+const PAKISTAN_TIME_ZONE = 'Asia/Karachi';
+
+// pp_TxnRefNo is annotated [20AN] in the guides: at most 20 letters and digits.
+const MAX_REFERENCE_LENGTH = 20;
+const REFERENCE_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+const pktFormatter = new Intl.DateTimeFormat('en-GB', {
+  timeZone: PAKISTAN_TIME_ZONE,
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+  hour: '2-digit',
+  minute: '2-digit',
+  second: '2-digit',
+  hourCycle: 'h23',
+});
+
+function txnDateTime(date = new Date()) {
+  const parts = Object.fromEntries(
+    pktFormatter.formatToParts(date).filter((part) => part.type !== 'literal').map((part) => [part.type, part.value]),
+  );
+  return `${parts.year}${parts.month}${parts.day}${parts.hour}${parts.minute}${parts.second}`;
+}
+
+/**
+ * Reference that stays unique inside a single millisecond.
+ *
+ * The clock alone is not enough: two orders placed in the same millisecond
+ * produce the same reference, and the gateway rejects the second as a duplicate.
+ * The random suffix fills whatever the prefix and the timestamp leave of the
+ * 20-character budget, drawn from crypto.randomInt rather than Math.random.
+ */
+function generateReference(prefix, date = new Date()) {
+  const stamp = txnDateTime(date);
+  const room = MAX_REFERENCE_LENGTH - prefix.length - stamp.length;
+
+  if (room < 1) {
+    throw new Error(`Reference prefix "${prefix}" leaves no room inside the ${MAX_REFERENCE_LENGTH}-character limit.`);
+  }
+
+  let suffix = '';
+  for (let index = 0; index < room; index += 1) {
+    suffix += REFERENCE_ALPHABET[randomInt(REFERENCE_ALPHABET.length)];
+  }
+
+  return `${prefix}${stamp}${suffix}`;
+}
+
+function toMinorUnits(majorAmount) {
+  const match = /^(\d+)(?:\.(\d{1,2}))?$/.exec(String(majorAmount).trim());
+  if (match === null) {
+    throw new Error(`Amount "${majorAmount}" must be a positive value with at most two decimal places.`);
+  }
+  return (BigInt(match[1]) * 100n + BigInt((match[2] ?? '').padEnd(2, '0'))).toString();
+}
+
+function secureHash(parameters, integritySalt) {
+  const values = Object.keys(parameters)
+    .filter((name) => name !== 'pp_SecureHash')
+    .sort()
+    .map((name) => (parameters[name] === null || parameters[name] === undefined ? '' : String(parameters[name])))
+    .filter((value) => value !== '');
+
+  const message = values.length === 0 ? integritySalt : `${integritySalt}&${values.join('&')}`;
+
+  return createHmac('sha256', integritySalt).update(message, 'utf8').digest('hex');
+}
+
+const HTML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (character) => HTML_ESCAPES[character]);
+}
+
+/**
+ * Build the signed parameter set for one order.
+ *
+ * `order` carries `amountMajor` (rupees, as a string), `billReference`
+ * (alphanumeric only) and `description`.
+ */
+export function buildCheckoutParameters(order) {
+  const merchantId = process.env.JAZZCASH_MERCHANT_ID ?? '';
+  const password = process.env.JAZZCASH_PASSWORD ?? '';
+  const integritySalt = process.env.JAZZCASH_INTEGRITY_SALT ?? '';
+  const returnUrl = process.env.JAZZCASH_RETURN_URL ?? '';
+
+  if (merchantId === '' || password === '' || integritySalt === '' || returnUrl === '') {
+    throw new Error('JazzCash credentials are not configured.');
+  }
+
+  const now = new Date();
+  const expiry = new Date(now.getTime() + 86_400_000);
+
+  const parameters = {
+{{PARAMS}}
+    pp_MerchantID: merchantId,
+    pp_Password: password,
+    pp_ReturnURL: returnUrl,
+    // Unique per transaction. Replace TRN with your own three-letter merchant
+    // prefix, as the guides recommend.
+    pp_TxnRefNo: generateReference('TRN', now),
+    pp_Amount: toMinorUnits(order.amountMajor),
+    pp_BillReference: order.billReference,
+    pp_Description: order.description,
+    pp_TxnDateTime: txnDateTime(now),
+    pp_TxnExpiryDateTime: txnDateTime(expiry),
+  };
+
+  parameters.pp_SecureHash = secureHash(parameters, integritySalt);
+
+  return parameters;
+}
+
+/** Render an auto-submitting HTML form. Every value is HTML-escaped. */
+export function renderCheckoutForm(parameters) {
+  const inputs = Object.entries(parameters)
+    .map(([name, value]) => `    <input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`)
+    .join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"><title>Redirecting to JazzCash…</title></head>
+<body>
+  <p>Redirecting you to the JazzCash secure payment page…</p>
+  <form id="jazzcash" method="post" action="${escapeHtml(JAZZCASH_POST_URL)}">
+${inputs}
+    <noscript><button type="submit">Continue</button></noscript>
+  </form>
+  <script>document.getElementById('jazzcash').submit();</script>
+</body>
+</html>`;
+}
+
+// Example wiring with Express:
+//
+//   app.post('/checkout', (request, response) => {
+//     const parameters = buildCheckoutParameters({
+//       amountMajor: '1.00',
+//       billReference: 'billref001',
+//       description: 'Order 1024',
+//     });
+//     response.type('html').send(renderCheckoutForm(parameters));
+//   });

package/knowledge/templates/node/ipn-handler.tmpl

@@ -0,0 +1,108 @@
+/**
+ * JazzCash IPN (Instant Payment Notification) listener — {{FRAMEWORK}}
+ *
+ * Generated by the JazzCash MCP server ({{CORPUS_VERSION}} guides).
+ * Sources: {{DOC_SOURCES}}
+ *
+ * Register this URL under Integration > Credentials in the merchant portal.
+ *
+ * CONTRACT
+ *  - Respond within 60 seconds. JazzCash retries twice on failure or timeout.
+ *  - Therefore this handler MUST be idempotent: the same notification can
+ *    legitimately arrive three times.
+ *  - This URL is public. Anyone can post to it. VERIFY THE HASH FIRST.
+ *  - In an inbound IPN the payment outcome is in pp_ResponseCode: 121 succeeded,
+ *    199/999 failed. (In a Status Inquiry response it is pp_PaymentResponseCode.)
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import express from 'express';
+
+const app = express();
+app.use(express.json());
+
+const INTEGRITY_SALT = process.env.JAZZCASH_INTEGRITY_SALT ?? '';
+if (INTEGRITY_SALT === '') {
+  throw new Error('JAZZCASH_INTEGRITY_SALT is not configured.');
+}
+
+function secureHash(parameters, integritySalt) {
+  const values = Object.keys(parameters)
+    .filter((name) => name !== 'pp_SecureHash' && name !== 'SecureHash')
+    .sort()
+    // The gateway sends JSON null in IPN payloads even though merchants are told
+    // never to send null. Treat null as empty when hashing.
+    .map((name) => (parameters[name] === null || parameters[name] === undefined ? '' : String(parameters[name])))
+    .filter((value) => value !== '');
+
+  const message = values.length === 0 ? integritySalt : `${integritySalt}&${values.join('&')}`;
+
+  return createHmac('sha256', integritySalt).update(message, 'utf8').digest('hex');
+}
+
+function hashMatches(left, right) {
+  const a = Buffer.from(String(left).trim().toLowerCase(), 'utf8');
+  const b = Buffer.from(String(right).trim().toLowerCase(), 'utf8');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+function acknowledgement(message) {
+  const body = { pp_ResponseCode: '000', pp_ResponseMessage: message };
+  body.pp_SecureHash = secureHash(body, INTEGRITY_SALT);
+  return body;
+}
+
+app.post('{{IPN_PATH}}', (request, response) => {
+  const notification = request.body;
+
+  if (typeof notification !== 'object' || notification === null) {
+    response.status(400).json({ pp_ResponseCode: '400', pp_ResponseMessage: 'Malformed body' });
+    return;
+  }
+
+  // 1. Verify the hash BEFORE anything else.
+  const supplied = notification.pp_SecureHash;
+  if (typeof supplied !== 'string' || !hashMatches(secureHash(notification, INTEGRITY_SALT), supplied)) {
+    console.error('JazzCash IPN rejected: secure hash did not verify.');
+    response.status(400).json({ pp_ResponseCode: '400', pp_ResponseMessage: 'Invalid secure hash' });
+    return;
+  }
+
+  const txnRefNo = String(notification.pp_TxnRefNo ?? '');
+  const responseCode = String(notification.pp_ResponseCode ?? '');
+
+  // 2. Acknowledge FIRST, then do the slow work. The 60-second budget is for the
+  //    HTTP response, not for your order pipeline.
+  response.json(acknowledgement('IPN received successfully'));
+
+  // 3. Process asynchronously and idempotently.
+  queueMicrotask(() => {
+    void handleNotification(txnRefNo, responseCode, notification).catch((error) => {
+      console.error('JazzCash IPN processing failed for', txnRefNo, error);
+    });
+  });
+});
+
+async function handleNotification(txnRefNo, responseCode, notification) {
+  // Replace with your own persistence layer.
+  // const order = await findOrderByReference(txnRefNo);
+  // if (order === null) return;                       // acknowledge and investigate
+  // if (order.isPaid) return;                         // retry: already handled
+  // if (order.amountMinorUnits !== String(notification.pp_Amount)) return;  // amount mismatch
+
+  if (responseCode === '121') {
+    // Paid. Mark the order paid.
+    // await markOrderPaid(txnRefNo, notification);
+  } else if (responseCode === '199' || responseCode === '999') {
+    // Failed. Do not release goods.
+    // await markOrderFailed(txnRefNo, notification);
+  } else {
+    // Undocumented code: unresolved, NOT failed. Reconcile with Status Inquiry.
+    console.error('JazzCash IPN carried undocumented code', responseCode, 'for', txnRefNo);
+  }
+}
+
+const port = Number(process.env.PORT ?? 3000);
+app.listen(port, () => {
+  console.error(`JazzCash IPN listener on port ${port} at {{IPN_PATH}}`);
+});

package/knowledge/templates/node/rest-client.tmpl

@@ -0,0 +1,197 @@
+/**
+ * JazzCash — {{FLOW_TITLE}}
+ *
+ * Generated by the JazzCash MCP server from {{FLOW_ID}} ({{CORPUS_VERSION}} guides).
+ * Sources: {{DOC_SOURCES}}
+ *
+ * SAFETY NOTES
+ *  - Sandbox and production use the SAME URL ({{ENDPOINT}}). The environment is
+ *    decided entirely by the credentials. Confirm which are loaded before running.
+ *  - Moves money: {{MOVES_MONEY}}.
+ *
+ * Requires Node.js 20 or later (global fetch, AbortSignal.timeout).
+ */
+
+import { createHmac, randomInt, timingSafeEqual } from 'node:crypto';
+
+export const JAZZCASH_ENDPOINT = '{{ENDPOINT}}';
+
+const TIMEOUT_MS = 30_000;
+const PAKISTAN_TIME_ZONE = 'Asia/Karachi';
+
+// pp_TxnRefNo and pp_RequestID are annotated [20AN] in the guides: at most 20
+// letters and digits.
+const MAX_REFERENCE_LENGTH = 20;
+const REFERENCE_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+const pktFormatter = new Intl.DateTimeFormat('en-GB', {
+  timeZone: PAKISTAN_TIME_ZONE,
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+  hour: '2-digit',
+  minute: '2-digit',
+  second: '2-digit',
+  hourCycle: 'h23',
+});
+
+/**
+ * Format an instant as YYYYMMDDHHMMSS in Pakistan Standard Time.
+ *
+ * Uses an explicit time zone so the stamp is correct regardless of the host
+ * clock. A server in UTC and one in New York must produce the same value.
+ */
+export function txnDateTime(date = new Date()) {
+  const parts = Object.fromEntries(
+    pktFormatter.formatToParts(date).filter((part) => part.type !== 'literal').map((part) => [part.type, part.value]),
+  );
+  return `${parts.year}${parts.month}${parts.day}${parts.hour}${parts.minute}${parts.second}`;
+}
+
+/** Expiry stamp, one day after the transaction, as the guides require. */
+export function txnExpiryDateTime(date = new Date()) {
+  return txnDateTime(new Date(date.getTime() + 86_400_000));
+}
+
+/** Convert rupees to the minor units the gateway expects. Integer maths only. */
+export function toMinorUnits(majorAmount) {
+  const match = /^(\d+)(?:\.(\d{1,2}))?$/.exec(String(majorAmount).trim());
+  if (match === null) {
+    throw new Error(`Amount "${majorAmount}" must be a positive value with at most two decimal places.`);
+  }
+  return (BigInt(match[1]) * 100n + BigInt((match[2] ?? '').padEnd(2, '0'))).toString();
+}
+
+/**
+ * Reference that stays unique inside a single millisecond.
+ *
+ * The clock alone is not enough: two orders placed in the same millisecond
+ * produce the same reference, and the gateway rejects the second as a duplicate.
+ * The random suffix fills whatever the prefix and the timestamp leave of the
+ * 20-character budget, drawn from crypto.randomInt rather than Math.random.
+ */
+export function generateReference(prefix = 'T', date = new Date()) {
+  const stamp = txnDateTime(date);
+  const room = MAX_REFERENCE_LENGTH - prefix.length - stamp.length;
+
+  if (room < 1) {
+    throw new Error(`Reference prefix "${prefix}" leaves no room inside the ${MAX_REFERENCE_LENGTH}-character limit.`);
+  }
+
+  let suffix = '';
+  for (let index = 0; index < room; index += 1) {
+    suffix += REFERENCE_ALPHABET[randomInt(REFERENCE_ALPHABET.length)];
+  }
+
+  return `${prefix}${stamp}${suffix}`;
+}
+
+/**
+ * Build pp_SecureHash.
+ *
+ * Sort by parameter NAME ascending, join the non-empty VALUES with "&", prepend
+ * the Integrity Salt, then HMAC-SHA256 with the salt as the key.
+ *
+ * Sorting uses the default comparator, which is code-unit order. Do NOT use
+ * localeCompare: it is locale-sensitive and would produce a hash that works on
+ * one host and fails on another.
+ */
+export function secureHash(parameters, integritySalt) {
+  const values = Object.keys(parameters)
+    .filter((name) => name !== 'pp_SecureHash' && name !== 'SecureHash')
+    .sort()
+    .map((name) => (parameters[name] === null || parameters[name] === undefined ? '' : String(parameters[name])))
+    .filter((value) => value !== '');
+
+  const message = values.length === 0 ? integritySalt : `${integritySalt}&${values.join('&')}`;
+
+  return createHmac('sha256', integritySalt).update(message, 'utf8').digest('hex');
+}
+
+/**
+ * Compare hashes in constant time, case-insensitively.
+ *
+ * JazzCash returns uppercase hex; this code produces lowercase. Same digest.
+ */
+export function hashMatches(left, right) {
+  const a = Buffer.from(String(left).trim().toLowerCase(), 'utf8');
+  const b = Buffer.from(String(right).trim().toLowerCase(), 'utf8');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+function credentials() {
+  const merchantId = process.env.JAZZCASH_MERCHANT_ID ?? '';
+  const password = process.env.JAZZCASH_PASSWORD ?? '';
+  const integritySalt = process.env.JAZZCASH_INTEGRITY_SALT ?? '';
+
+  if (merchantId === '' || password === '' || integritySalt === '') {
+    throw new Error('JazzCash credentials are not configured.');
+  }
+
+  return { merchantId, password, integritySalt };
+}
+
+/** Send one request. Never logs the payload: it carries the password. */
+async function post(parameters) {
+  const response = await fetch(JAZZCASH_ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify(parameters),
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+
+  const text = await response.text();
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`JazzCash returned a non-JSON body with HTTP ${response.status}.`);
+  }
+}
+
+/**
+ * Execute {{FLOW_ID}}.
+ *
+ * Every value marked TODO must be supplied by your application, either by
+ * editing the literal below or by passing it in `overrides`. pp_Amount is in
+ * MINOR units: pass `toMinorUnits('100.00')` rather than a rupee float, so the
+ * conversion is exact.
+ */
+export async function run(overrides = {}) {
+  const { merchantId, password, integritySalt } = credentials();
+
+  const parameters = {
+{{PARAMS}}
+    ...overrides,
+    pp_MerchantID: merchantId,
+    pp_Password: password,
+{{RUNTIME_OVERRIDES}}
+  };
+
+  // Hash LAST, from exactly the object about to be transmitted.
+  parameters.pp_SecureHash = secureHash(parameters, integritySalt);
+
+  const result = await post(parameters);
+
+  if (result['{{SUCCESS_FIELD}}'] === '{{SUCCESS_VALUE}}') {
+{{SETTLEMENT_CHECK}}    // For Status Inquiry this only means the enquiry worked. Read
+    // pp_PaymentResponseCode for the payment outcome: 121 means completed.
+{{SUCCESS_REPORT}}
+  } else {
+    // An unrecognised code is UNRESOLVED, not failed. Resolve it with the
+    // Status Inquiry API before refunding or re-charging.
+    console.error('JazzCash call unresolved. Code:', result['{{SUCCESS_FIELD}}']);
+  }
+
+  const responseHash = result['{{RESPONSE_HASH_FIELD}}'];
+  if (typeof responseHash === 'string' && responseHash !== '') {
+    if (!hashMatches(secureHash(result, integritySalt), responseHash)) {
+      // JazzCash does not document which response fields feed this hash, so a
+      // mismatch means UNVERIFIED, not proven tampering. Reconcile through
+      // Status Inquiry rather than rejecting the payment.
+      console.error('JazzCash response hash could not be verified for', result.pp_TxnRefNo);
+    }
+  }
+
+  return result;
+}

package/knowledge/templates/node/wallet-linking.tmpl

@@ -0,0 +1,147 @@
+/**
+ * JazzCash — MWallet linking form
+ *
+ * Generated by the JazzCash MCP server from {{FLOW_ID}} ({{CORPUS_VERSION}} guides).
+ * Sources: {{DOC_SOURCES}}
+ *
+ *  - Sandbox and production use the SAME URL. The environment is decided by the
+ *    credentials alone: going live is a credential swap, not a URL change.
+ *
+ * TWO CORRECTIONS TO THE OFFICIAL SAMPLE, both deliberate:
+ *
+ *  1. The sample in the guide computes the hash in browser JavaScript with the
+ *     Integrity Salt embedded in the page. The salt is the HMAC key: publishing
+ *     it lets anyone forge a valid pp_SecureHash for your merchant account. This
+ *     module runs server-side and emits only the finished hash.
+ *
+ *  2. The sample posts to https://pgw.jazzcash.com.pk/..., contradicting the
+ *     endpoint table and screenshot in the same document. This module uses the
+ *     endpoint from the table: {{ENDPOINT}}
+ *
+ * Requires Node.js 20 or later.
+ */
+
+import { createHmac, randomInt } from 'node:crypto';
+
+export const JAZZCASH_LINKING_URL = '{{ENDPOINT}}';
+
+const MSISDN_PATTERN = /^03\d{9}$/;
+
+// pp_RequestID is annotated [20AN] in the guides: at most 20 letters and digits.
+const MAX_REFERENCE_LENGTH = 20;
+const REFERENCE_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+const pktFormatter = new Intl.DateTimeFormat('en-GB', {
+  timeZone: 'Asia/Karachi',
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+  hour: '2-digit',
+  minute: '2-digit',
+  second: '2-digit',
+  hourCycle: 'h23',
+});
+
+function txnDateTime(date = new Date()) {
+  const parts = Object.fromEntries(
+    pktFormatter.formatToParts(date).filter((part) => part.type !== 'literal').map((part) => [part.type, part.value]),
+  );
+  return `${parts.year}${parts.month}${parts.day}${parts.hour}${parts.minute}${parts.second}`;
+}
+
+/**
+ * Reference that stays unique inside a single millisecond.
+ *
+ * The clock alone is not enough: two linking attempts started in the same
+ * millisecond produce the same pp_RequestID, and the gateway rejects the second
+ * as a duplicate. Drawn from crypto.randomInt rather than Math.random.
+ */
+function generateReference(prefix, date = new Date()) {
+  const stamp = txnDateTime(date);
+  const room = MAX_REFERENCE_LENGTH - prefix.length - stamp.length;
+
+  if (room < 1) {
+    throw new Error(`Reference prefix "${prefix}" leaves no room inside the ${MAX_REFERENCE_LENGTH}-character limit.`);
+  }
+
+  let suffix = '';
+  for (let index = 0; index < room; index += 1) {
+    suffix += REFERENCE_ALPHABET[randomInt(REFERENCE_ALPHABET.length)];
+  }
+
+  return `${prefix}${stamp}${suffix}`;
+}
+
+function secureHash(parameters, integritySalt) {
+  const values = Object.keys(parameters)
+    .filter((name) => name !== 'pp_SecureHash')
+    .sort()
+    .map((name) => (parameters[name] === null || parameters[name] === undefined ? '' : String(parameters[name])))
+    .filter((value) => value !== '');
+
+  const message = values.length === 0 ? integritySalt : `${integritySalt}&${values.join('&')}`;
+
+  return createHmac('sha256', integritySalt).update(message, 'utf8').digest('hex');
+}
+
+const HTML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (character) => HTML_ESCAPES[character]);
+}
+
+/** Build the signed linking parameters for one customer wallet number. */
+export function buildLinkingParameters(msisdn) {
+  if (!MSISDN_PATTERN.test(String(msisdn))) {
+    throw new Error('A Pakistani mobile wallet number in the form 03XXXXXXXXX is required.');
+  }
+
+  const merchantId = process.env.JAZZCASH_MERCHANT_ID ?? '';
+  const password = process.env.JAZZCASH_PASSWORD ?? '';
+  const integritySalt = process.env.JAZZCASH_INTEGRITY_SALT ?? '';
+  const returnUrl = process.env.JAZZCASH_RETURN_URL ?? '';
+
+  if (merchantId === '' || password === '' || integritySalt === '' || returnUrl === '') {
+    throw new Error('JazzCash credentials are not configured.');
+  }
+
+  const now = new Date();
+
+  const parameters = {
+{{PARAMS}}
+    pp_MerchantID: merchantId,
+    pp_Password: password,
+    pp_MSISDN: String(msisdn),
+    // Must be unique for every linking attempt.
+    pp_RequestID: generateReference('R', now),
+    pp_ReturnURL: returnUrl,
+  };
+
+  parameters.pp_SecureHash = secureHash(parameters, integritySalt);
+
+  return parameters;
+}
+
+/** Render an auto-submitting linking form. */
+export function renderLinkingForm(parameters) {
+  const inputs = Object.entries(parameters)
+    .map(([name, value]) => `    <input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`)
+    .join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"><title>Link your JazzCash wallet</title></head>
+<body>
+  <p>You will be asked for your MPIN on the JazzCash page.</p>
+  <form id="link-wallet" method="post" action="${escapeHtml(JAZZCASH_LINKING_URL)}">
+${inputs}
+    <noscript><button type="submit">Continue</button></noscript>
+  </form>
+  <script>document.getElementById('link-wallet').submit();</script>
+</body>
+</html>`;
+}
+
+// On return, JazzCash posts a payment token to your Return URL. Store it against
+// the customer and charge it later with the token payment API. Call the Token
+// Inquiry API before charging: the customer may have unlinked their wallet.