Payment Troubleshooting

Diagnose and resolve common payment gateway issues — callback timeouts, STK push delays, unallocated payments, and walled garden blocks.

Diagnosing payment issues systematically

When a customer reports an issue during plan purchase or renewal, follow a structured diagnostic sequence before modifying customer accounts or recording manual payments.

In modern billing architectures, payment delivery consists of four discrete stages:

1. Initiation: The customer enters their phone number or opens the card checkout dialog.
2. Authorization: The customer authorizes the transaction (entering their mobile money PIN or 3D-Secure card OTP).
3. Gateway Settlement: The payment provider captures the funds and prepares an encrypted callback.
4. Nukta Reconciliation & Router Activation: Nukta's webhook receives the callback, updates the customer ledger, and instructs the MikroTik router to apply speed limits.

Common payment issues and solutions

1. Customer completed payment, but remains offline

This is the most common operational inquiry. Follow this 3-step checklist:

1. Check the Payment Ledger: Open Finance → Payments and search for the customer's phone number or receipt reference:
   • If Confirmed: The payment arrived successfully. Open Users → Customers → View Customer and confirm that their expiry date advanced.
   • If Pending: The gateway has not yet sent confirmation. Click the transaction and select Verify with Provider to force a real-time status query.
   • If Missing: The funds were sent to a different shortcode, entered with a typo, or the gateway experienced a callback delay.
2. Clear Stale Router Sessions: If the customer device was attempting to browse while expired, the MikroTik router may have cached a rejected session. Open Users → Active Users, find the device, and click Graceful Disconnect (Kick). The device will reconnect automatically in seconds with active speed queues.
3. Verify Walled Garden Rules: In Devices → Mikrotiks, open the router menu and click Sync Walled Garden to ensure the payment provider is not blocked locally.

2. STK push prompt does not appear on customer phone

If a customer initiates checkout but does not receive the PIN prompt on their handset:

• Phone Number Formatting: Ensure the phone number includes the correct country dial code (e.g., +254712345678 or 0712345678). Leading spaces or international symbol mismatches will cause API rejection.
• Handset State: If the customer's phone is currently engaged in an active phone call, on low battery saver mode, or has poor cellular reception, SIM Toolkit prompts cannot be displayed. Advise the customer to disconnect active calls or restart their mobile device.
• Recent Password / SIM Swap: Telecommunications operators temporarily block mobile banking prompts on SIM cards that were swapped or replaced within the previous 48 hours for anti-fraud protection.

3. Payment completed, but status is stuck in "Pending"

If a payment remains in Pending status for more than two minutes:

• Webhook Endpoint Reachability: Verify that the webhook URL registered in your payment gateway dashboard matches your active workspace domain (e.g., https://{subdomain}.nukta.one/api/payments/saf/callback).
• Manual Verification: Open the pending transaction in Finance → Payments and click Verify with Provider. Nukta sends a direct server-to-server query to retrieve the settled transaction state.

4. Captive device cannot reach checkout

If customers see a connection error or blank screen when opening the checkout window:

• The customer device is unauthenticated and the payment gateway domain is missing from your router's walled garden.
• Open Devices → Mikrotiks, locate the router, and click Sync Walled Garden.
• Verify that your router has working external DNS resolution by running /ip dns print in the MikroTik terminal.

5. Unallocated payments (Customer paid using incorrect account number)

In C2B Paybill workflows, walk-in customers sometimes enter an incorrect account number (e.g., entering their friend's name instead of their assigned account code):

• Automated Phone Matching: Nukta's intelligent payment matcher first attempts to link the transaction by matching the customer's mobile phone number. If the phone number matches an existing customer in your directory, access is credited automatically regardless of what was typed in the account field.
• Unallocated Queue: If neither the account number nor the phone number matches an existing customer, the transaction is safely held in Finance → Payments under the Unallocated tab.
• Reallocating Funds: Open the unallocated transaction, click Assign to Customer, select the correct customer record, and click Reallocate. The funds are credited to the customer immediately.

TIP

Avoid Duplicate Payments

Never record a manual payment while investigating a missing online payment until you have confirmed whether the original transaction succeeded. Recording duplicate payments distorts your financial ledgers and tax reporting.