Accept Pan-African Payments with DPO Pay

Create a DPO Pay integration for a Node.js/Express app. Install the fast-xml-parser package for XML handling. 1. src/services/dpo.service.ts — export two functions: createPaymentToken(params: { amount: number, currency: string, reference: string, redirectUrl: string, backUrl: string, customerEmail: string, customerName: string, serviceDescription: string }): Promise<{ token: string, transRef: string }> — Build an XML request body: xml <?xml version="1.0" encoding="utf-8"?> <API3G> <CompanyToken>${DPO_COMPANY_TOKEN}</CompanyToken> <Request>createToken</Request> <Transaction> <PaymentAmount>${params.amount.toFixed(2)}</PaymentAmount> <PaymentCurrency>${params.currency}</PaymentCurrency> <CompanyRef>${params.reference}</CompanyRef> <RedirectURL>${params.redirectUrl}</RedirectURL> <BackURL>${params.backUrl}</BackURL> <CompanyRefUnique>1</CompanyRefUnique> <PTL>30</PTL> </Transaction> <Services> <Service> <ServiceType>5525</ServiceType> <ServiceDescription>${params.serviceDescription}</ServiceDescription> <ServiceDate>${new Date().toISOString().split("T")[0] + " " + new Date().toTimeString().split(" ")[0]}</ServiceDate> </Service> </Services> <Additional> <CustomerEmail>${params.customerEmail}</CustomerEmail> <CustomerName>${params.customerName}</CustomerName> </Additional> </API3G> POST this XML with Content-Type "application/xml" to ${DPO_BASE_URL}/API/v6/. Parse the XML response using fast-xml-parser. Check that Result === "000" (success). Return { token: TransToken, transRef: TransRef } from the response. If Result is not "000", throw an error with the ResultExplanation. getCheckoutUrl(token: string): string — Return ${DPO_BASE_URL}/payv2.php?ID=${token}. This is the hosted payment page URL. 2. src/controllers/dpo.controller.ts — export createDpoPayment(req, res, next): - Extract amount, currency (default "GHS"), customerEmail, customerName, description from req.body - Validate currency is one of: GHS, KES, NGN, ZAR, UGX, TZS, XOF - Generate a unique reference: "DPO-" + Date.now() + "-" + crypto.randomBytes(4).toString("hex").toUpperCase() - Set redirectUrl to your frontend's payment success page, backUrl to your frontend's payment cancelled page - Call createPaymentToken with all parameters - Save the order to your database with status "pending", the reference, and the DPO transaction token - Return 201 with { checkoutUrl: getCheckoutUrl(token), reference, token } 3. src/routes/dpo.router.ts — POST / → createDpoPayment. Mount under /pay/dpo in your main app.

Create the DPO Pay verification handler. 1. src/services/dpo.service.ts — add a function: verifyPaymentToken(token: string): Promise<{ result: string, resultExplanation: string, customerEmail: string, transactionAmount: string, transactionCurrency: string, transactionRef: string }> — Build an XML request body: xml <?xml version="1.0" encoding="utf-8"?> <API3G> <CompanyToken>${DPO_COMPANY_TOKEN}</CompanyToken> <Request>verifyToken</Request> <TransactionToken>${token}</TransactionToken> </API3G> POST to ${DPO_BASE_URL}/API/v6/ with Content-Type "application/xml". Parse the XML response. Return { result: Result, resultExplanation: ResultExplanation, customerEmail: CustomerEmail, transactionAmount: TransactionAmount, transactionCurrency: TransactionCurrency, transactionRef: CompanyRef }. 2. src/controllers/dpo.controller.ts — add verifyDpoPayment(req, res, next): - Extract the token from req.query.TransactionToken or req.body.token - Call verifyPaymentToken with the token - If result === "000": payment was successful. Find the order by its DPO token, update status to "paid", save paid_at timestamp and the transaction details. Return 200 with { status: "paid", reference } - If result === "901": token is invalid or expired. Return 400 with the resultExplanation - If result === "904": token not yet paid. Return 200 with { status: "pending" } - For any other result: log the result code and explanation, update order to "failed", return 200 with { status: "failed", reason: resultExplanation } 3. src/routes/dpo.router.ts — add: - GET /verify → verifyDpoPayment (called when customer is redirected back from DPO) - POST /verify → verifyDpoPayment (can also be called server-to-server)