Integrate OPay Cashier Checkout

Create an OPay Cashier integration for a Node.js/Express app. 1. src/services/opay.service.ts — export two functions: signRequest(body: object, secretKey: string): string — JSON.stringify the body, then compute HMAC-SHA512 using the secretKey. Return the hex digest. initializeCashier(params: { reference: string, amount: number, currency: "NGN" | "GHS" | "EGP", callbackUrl: string, returnUrl: string, user: { id: string, name: string, email: string, phone: string } }): Promise<{ cashierUrl: string }> — Build the request body: json { "merchant": { "merchantId": OPAY_MERCHANT_ID, "merchantName": "Your Store" }, "reference": params.reference, "amount": { "total": params.amount, "currency": params.currency }, "callbackUrl": params.callbackUrl, "returnUrl": params.returnUrl, "expireAt": new Date(Date.now() + 30 * 60 * 1000).toISOString(), "userInfo": { "userId": params.user.id, "userName": params.user.name, "userEmail": params.user.email, "userMobile": params.user.phone } } Generate headers: Authorization "Bearer ", MerchantId from env, Content-Type "application/json", Timestamp (Date.now().toString() — Unix ms), Nonce (crypto.randomUUID()). Also add a Signature header with the result of signRequest(body, OPAY_SECRET_KEY). POST to ${OPAY_BASE_URL}/api/v3/native/cashier/initialize. Return data.cashierUrl from the response. 2. src/controllers/opay.controller.ts — export createOpayPayment(req, res, next): - Extract amount, currency, userId, userName, userEmail, userPhone from req.body - Generate a unique reference: "OPAY-" + Date.now() + "-" + crypto.randomBytes(4).toString("hex").toUpperCase() - Call initializeCashier with the callbackUrl set to your server's webhook URL and returnUrl set to your frontend's order confirmation page - Save the order to your database with status "pending" and the reference - Return 201 with { cashierUrl, reference } 3. src/routes/opay.router.ts — POST / → createOpayPayment. Mount under /pay/opay in your main app.

Create the OPay webhook and status verification handler. 1. src/services/opay.service.ts — add a function: checkCashierStatus(merchantId: string, reference: string): Promise<{ status: string, amount: number }> — Build the request body: { merchantId, reference }. Sign it with signRequest. POST to ${OPAY_BASE_URL}/api/v3/native/cashier/status with the same five headers (Authorization, MerchantId, Timestamp, Nonce, Content-Type) plus the Signature header. Return { status: data.status, amount: data.amount.total } from the response. 2. src/controllers/opay.controller.ts — add opayCallback(req, res, next): - Extract the reference from the request body - Call checkCashierStatus with OPAY_MERCHANT_ID and the reference - If status === "SUCCESS": update the order in the database to status "paid", save paid_at timestamp - If status === "FAIL" or "CLOSE": update order status to "failed" - If status === "PENDING": do nothing — OPay will retry - Return 200 immediately (OPay expects a fast response) - Important: always verify via the status endpoint rather than trusting the callback body alone — this prevents forged callback attacks 3. src/routes/opay.router.ts — add POST /callback → opayCallback.