payment-url-generator-and-verification

A TypeScript/JavaScript library for generating secure Bob Pay payment URLs and MD5 signatures.
Designed for easy integration with the Bob Pay payment gateway.

Features

• Generate Bob Pay-compliant payment URLs
• Create MD5 signatures from key-value pairs and a passphrase to ensure the authenticity and integrity of the payment request sent to Bob Pay.
• TypeScript-first, works in Node.js and modern JS projects

Installation

npm install bobpay-payment-url-generator-and-verification

Usage

import { generatePayURL, generateSignature } from 'payment-url-generator';

// Example payment details
const config = {
  bobPayWebsiteURL: 'https://sandbox.bobpay.co.za',
  passphrase: 'your-secret-passphrase',
  notifyUrl: 'https://yourdomain.com/payment/notify',
  successUrl: 'https://yourdomain.com/payment/success?id=',
  pendingUrl: 'https://yourdomain.com/payment/pending?id=',
  cancelUrl: 'https://yourdomain.com/payment/cancel?id=',
};

const details = {
  recipient_account_code: 'SAN001',
  custom_payment_id: '12345',
  email: '[email protected]',
  mobile_number: '',
  amount: '499.99',
  item_name: 'Order 12345',
  item_description: 'Lego Set',
};

// Generate the payment URL
const url = generatePayURL(config, details);

// If you only need the signature:
import { KeyValuePair } from 'payment-url-generator';
const kvPairs: KeyValuePair[] = [
 { key: 'amount', value: '499.99' },
 { key: 'item_name', value: 'Order 12345' },
  // ...other pairs
];
const signature = generateSignature(kvPairs, config.passphrase);

API

generatePayURL(config: PaymentConfig, details: PaymentDetails): string

Generates a Bob Pay payment URL with all required parameters and a valid signature.

• config: Object containing Bob Pay URLs and your passphrase.
• details: Object with payment details (amount, item name, etc).

Returns:
A string representing the full payment URL.

generateSignature(kvPairs: KeyValuePair[], passphrase: string): string

Generates an MD5 signature string from sorted, encoded key-value pairs and your passphrase.

• kvPairs: Array of { key: string, value: string } pairs.
• passphrase: Your Bob Pay passphrase.

Returns:
A string representing the MD5 hash signature.

Parameter Encoding & Signature Rules

• Spaces are encoded as + (not %20) to match Bob Pay requirements.
• The passphrase is appended as &passphrase=YOUR_PASSPHRASE before hashing.
• The signature parameter is not included in the string to hash.

TypeScript Types

The package exports types for PaymentConfig, PaymentDetails, and KeyValuePair for type safety.

Payment Notification Signature Validation

You can also validate incoming payment notifications from Bob Pay to ensure they are authentic and have not been tampered with.

Example: Validate a Notification

import { validatePaymentNotification } from 'bobpay-payment-url-generator-and-verification';

const notification: PaymentNotification = {
  recipient_account_code: 'SAN001',
  custom_payment_id: '12345',
  email: '[email protected]',
  mobile_number: '',
  amount: '499.99',
  item_name: 'Order 12345',
  item_description: 'Lego Set',
  notify_url: 'https://yourdomain.com/payment/notify',
  success_url: 'https://yourdomain.com/payment/success?id=12345',
  pending_url: 'https://yourdomain.com/payment/pending?id=12345',
  cancel_url: 'https://yourdomain.com/payment/cancel?id=12345',
  signature: 'the-signature-from-bobpay'
};

const validationConfig: ValidationConfig = {
  passphrase: 'your-secret-passphrase',
  expectedAmount: 499.99,
  allowedIps: ['::1'],
  bobPayValidationUrl: 'https://api.sandbox.bobpay.co.za/payments/intents/validate',
};

const isValid = validatePaymentNotification(notification, validationConfig);

if (isValid) {
  // Process the payment notification
} else {
  // Reject or log the invalid notification
}

How it works:

• The function reconstructs the signature from the notification fields and your passphrase.
• It compares the calculated signature to the one provided in the notification.
• Returns true if the signature matches, otherwise false.

Parameter Encoding & Signature Rules

• Spaces are encoded as + (not %20) to match Bob Pay requirements.
• The passphrase is appended as &passphrase=YOUR_PASSPHRASE before hashing.
• The signature parameter is not included in the string to hash.

Example: Validating a Payment Notification in a Local Express POST Endpoint

import express, { Request, Response } from 'express';
import { ValidationConfig,PaymentNotification,validatePaymentNotification, checkAllowedIp } from 'bobpay-payment-url-generator-and-verification';

const app = express();

app.use(express.json());

const validationConfig: ValidationConfig = {
  passphrase: ''your-secret-passphrase',
  expectedAmount: 499.99,
  allowedIps: ['::1'],
  bobPayValidationUrl: 'https://api.sandbox.bobpay.co.za/payments/intents/validate',
};

app.post('/bobpay/notify', async (req: Request, res: Response) => {
  const notification = req.body as PaymentNotification;
  const ip = req.ip ?? req.connection.remoteAddress ?? '';

  if (!checkAllowedIp(ip, validationConfig.allowedIps)) {
    return res.status(403).json({ success: false, message: 'IP not allowed' });
  }

  const isValid = await validatePaymentNotification(notification, validationConfig);

  if (isValid) {
    return res.json({ success: true, message: 'Notification validated' });
  } else {
    return res.status(400).json({ success: false, message: 'Notification invalid' });
  }
});

  const PORT = 3000;
  app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
  });