Implement Your First VTPE Integration in Minutes

Step-by-step guide to implement the Product Information API and webhook handler for VTPE, from creating a partner account to going live.

This quickstart walks you through building a complete VTPE integration. You will implement a Product Information API endpoint that VTPE calls to retrieve payment details, and a webhook handler that receives payment state change events.

Prerequisites

Before you begin, make sure you have:

• A partner account at partner.mizaniyapay.dz
• Your API Secret for Bearer token authentication
• Your HMAC Secret for verifying webhook signatures
• An HTTPS-accessible server to host your endpoints

1. Create a Partner Account

   Register at the Partner Portal. Once your account is approved by Mizaniya Pay, you will receive your API Secret and HMAC Secret. Store both values securely as environment variables before proceeding.

   export VTPE_API_SECRET="your_api_secret"
   export VTPE_HMAC_SECRET="your_hmac_secret"
   
2. Configure Your Integration

   Provide the following two URLs to Mizaniya Pay so VTPE knows where to route requests:

   Field	Example	Description
   API URL	https://api.example.com/payments	Endpoint VTPE calls to retrieve payment info
   Webhook URL	https://api.example.com/webhooks/vtpe	Endpoint that receives payment lifecycle events

3. Implement the Product Information API

   Expose a GET endpoint at {API_URL}/{reference}. VTPE calls this before initiating any payment. Return the payment details or the appropriate error response.

   Node.js

   import express from "express";
   const app = express();
   app.use(express.json());
   
   function authenticate(req, res, next) {
     const auth = req.headers["authorization"];
     if (auth !== `Bearer ${process.env.VTPE_API_SECRET}`) {
       return res.status(401).json({ error: "UNAUTHORIZED", errorMessage: "Invalid or missing API Secret" });
     }
     next();
   }
   
   app.get("/payments/:reference", authenticate, (req, res) => {
     const { reference } = req.params;
   
     // Replace with your real database lookup
     const order = db.findOrder(reference);
   
     if (!order) {
       return res.status(404).json({ error: "NOT_FOUND", errorMessage: "Reference not found" });
     }
     if (order.isPaid) {
       return res.status(409).json({ error: "ALREADY_PAID", errorMessage: "Payment already completed" });
     }
   
     return res.status(200).json({
       reference: order.reference,
       total_amount: order.totalAmount,
       currency: order.currency,
       amount_detail: order.amountDetail ?? [],
       details: order.details ?? []
     });
   });
   
   app.listen(3000);
   

   See Errors for the full list of error codes and when to return each one.

4. Implement the Webhook Handler

   VTPE POSTs signed webhook events to your Webhook URL. Verify the signature, parse the event and data fields, handle each event type, and return HTTP 200 with { "success": true }.

   Node.js

   import crypto from "crypto";
   
   // Use raw body middleware BEFORE JSON parsing
   app.use("/webhooks/vtpe", express.raw({ type: "application/json" }));
   
   app.post("/webhooks/vtpe", (req, res) => {
     const rawBody = req.body.toString("utf8");
     const timestamp = req.headers["x-timestamp"] ?? "";
     const receivedSig = req.headers["x-signature"] ?? "";
   
     const expectedSig = crypto
       .createHmac("sha256", process.env.VTPE_HMAC_SECRET)
       .update(rawBody + timestamp)
       .digest("hex");
   
     if (!crypto.timingSafeEqual(Buffer.from(expectedSig), Buffer.from(receivedSig))) {
       return res.status(400).json({ error: "Invalid signature" });
     }
   
     const { event, data } = JSON.parse(rawBody);
   
     switch (event) {
       case "payment.initialized":
         // Create a pending payment record
         console.log("Payment initialized:", data.paymentId);
         break;
       case "payment.success":
         // Fulfill the order
         console.log("Payment success:", data.reference, "via", data.channel);
         break;
       case "payment.fail":
         // Release reservations
         console.log("Payment failed:", data.paymentId);
         break;
       default:
         console.log("Unknown event:", event);
     }
   
     return res.status(200).json({ success: true });
   });
   
5. Verify Signatures

   VTPE signs every webhook using HMAC-SHA256(rawBody + timestamp, HMAC_SECRET). The result is a plain hex string in the X-Signature header. Always verify this before processing any event.

   For the full verification guide with step-by-step instructions, see Webhook Security.

6. Go Live

   Before switching to production, complete this checklist:

   • Switch to your production API Secret and HMAC Secret
   • Confirm both your API URL and Webhook URL are HTTPS
   • Test the full payment flow with Mizaniya Pay
   • Verify signature verification is active (never skip in production)

Next Steps

• Review the API Reference for complete request and response fields.
• Read the Webhook Security guide for full HMAC signature verification details.
• Follow Best Practices to make your integration robust and production-ready.