Accept South African Bank Payments with Ozow

Create an Ozow instant EFT integration for a Node.js/Express app. 1. src/services/ozow.service.ts — export two functions: generateOzowHash(params: { siteCode: string, countryCode: string, currencyCode: string, amount: string, transactionReference: string, bankReference: string, cancelUrl: string, errorUrl: string, successUrl: string, notifyUrl: string, isTest: string, privateKey: string }): string — Concatenate all values in lowercase in this exact order: siteCode + countryCode + currencyCode + amount + transactionReference + bankReference + cancelUrl + errorUrl + successUrl + notifyUrl + isTest + privateKey. Compute SHA-512 hash of the concatenated string. Return the hex digest in lowercase. createPaymentRequest(params: { amount: number, reference: string, bankReference: string, successUrl: string, errorUrl: string, cancelUrl: string, notifyUrl: string }): Promise — Build the form data object: { SiteCode: OZOW_SITE_CODE, CountryCode: "ZA", CurrencyCode: "ZAR", Amount: params.amount.toFixed(2), TransactionReference: params.reference, BankReference: params.bankReference, SuccessUrl: params.successUrl, ErrorUrl: params.errorUrl, CancelUrl: params.cancelUrl, NotifyUrl: params.notifyUrl, IsTest: process.env.NODE_ENV === "production" ? "false" : "true", HashCheck: generateOzowHash({ ... all fields plus OZOW_PRIVATE_KEY }) } POST this as application/x-www-form-urlencoded to ${OZOW_BASE_URL}/PostPaymentRequest. The response contains a URL — return it so the client can redirect the customer. 2. src/controllers/ozow.controller.ts — export createOzowPayment(req, res, next): - Extract amount and description from req.body - Generate a unique reference: "OZOW-" + Date.now() + "-" + crypto.randomBytes(4).toString("hex").toUpperCase() - Use description or reference as the bankReference (this appears on the customer's bank statement) - Set successUrl, errorUrl, cancelUrl to your frontend routes and notifyUrl to your server webhook - Save the order to your database with status "pending" and the reference - Call createPaymentRequest and return 201 with { paymentUrl, reference } 3. src/routes/ozow.router.ts — POST / → createOzowPayment. Mount under /pay/ozow in your main app.

Create the Ozow webhook verification handler. 1. src/services/ozow.service.ts — add a function: verifyOzowNotification(body: Record<string, string>, privateKey: string): boolean — Ozow sends these fields in the notification: SiteCode, TransactionId, TransactionReference, Amount, Status, Optional1, Optional2, Optional3, StatusMessage, Hash. To verify: concatenate lowercase values in this order: siteCode + transactionId + transactionReference + amount + status + optional1 + optional2 + optional3 + statusMessage + privateKey (use empty string for any missing optional fields). Compute SHA-512 of the concatenated string. Compare the resulting hex digest (lowercase) against the Hash field from the notification (also lowercased). Return true if they match. 2. src/controllers/ozow.controller.ts — add ozowNotify(req, res, next): - Parse the notification body (Ozow sends application/x-www-form-urlencoded or JSON depending on configuration) - Call verifyOzowNotification with the body and OZOW_PRIVATE_KEY - If verification fails, log the attempt and return 400 { error: "Invalid hash" } - If Status === "Complete": find the order by TransactionReference, update status to "paid", save the TransactionId and paid_at timestamp - If Status === "Cancelled" or "Error" or "Abandoned": update the order status to "failed" with the StatusMessage - Return 200 immediately - Important: use crypto.timingSafeEqual for the hash comparison to prevent timing attacks 3. src/routes/ozow.router.ts — add POST /notify → ozowNotify. Ensure this route is accessible without authentication — Ozow's servers need to reach it.