Payment status

Polling Architecture

Ziba Pay uses status API polling for merchant payment verification. Outbound merchant notifications are not implemented for collection routes.

Important: POST/payment/mtn/callback is an internal provider callback used by MTN's servers only. Do not call it from your merchant server or wait for an outbound notification.

Status Polling Endpoints

Depending on the payment channel used during collection, query status using the corresponding endpoint below:

Recommended Polling Algorithm

When implementing your polling worker, follow these best practice intervals to balance prompt resolution with rate limit compliance:

• Initial Delay: Wait 3 to 5 seconds after initiating collection before issuing the first status request.
• Polling Frequency: Poll every 3 to 5 seconds while status remains PENDING or PROCESSING.
• Exponential Backoff: If status remains PENDING after 30 seconds, increase the polling interval to 10 seconds.
• Timeout Threshold: After 180 seconds (3 minutes), conclude polling and treat the session as EXPIRED if no terminal status has been received.

async function pollPaymentStatus(reference, token, maxTimeoutMs = 180000) {
  const startTime = Date.now();
  let intervalMs = 3000;

  // Initial wait for customer USSD prompt
  await new Promise((r) => setTimeout(r, 3000));

  while (Date.now() - startTime < maxTimeoutMs) {
    const res = await fetch(`https://payment-service-mh2d.onrender.com/api/payment/mtn/status/${reference}`, {
      method: "GET",
      headers: { "Authorization": `Bearer ${token}` }
    });

    if (res.ok) {
      const { status } = await res.json();
      console.log(`Current status for ${reference}: ${status}`);

      if (status === "COMPLETED") return { success: true, status };
      if (["FAILED", "CANCELLED", "EXPIRED", "REVERSED"].includes(status)) {
        return { success: false, status };
      }
    }

    // Exponential backoff after 30 seconds
    if (Date.now() - startTime > 30000) {
      intervalMs = Math.min(intervalMs * 1.5, 10000);
    }

    await new Promise((r) => setTimeout(r, intervalMs));
  }

  throw new Error("Payment polling timed out after 3 minutes");
}

Special Edge Case: MTN TIMEOUT Behavior

In cases where the upstream mobile network experiences temporary network latency, MTN may return a TIMEOUT event. Ziba Pay intentionally keeps the local order status as PENDING rather than marking it FAILED.

This ensures that if the customer subsequently enters their PIN and the network confirms settlement, the payment successfully completes instead of being prematurely abandoned.