Funding Your Nyota Wallet (M-Pesa STK Push, Airtel Money & Card)

The Nyota Wallet is the centralized financial engine that powers your infrastructure usage across Nyota ID (KYC/KYB verifications), Nyota SMS (transactional units), Nyota Drive (metered storage), and Nyota Mail (seat renewals).

This guide explains how wallet deposits and automated webhooks work under the hood, how to top up your balance using local mobile money or international credit cards, and how to troubleshoot pending transactions.

1. How It Works Under the Hood

When you top up your workspace balance, funds move through an automated, double-entry financial ledger:

1. DEPOSIT INITIATION (Web Console)
    Admin selects amount -> Chooses payment method (M-Pesa / Airtel / Card)
                         │
                         ▼
 2. GATEWAY PROCESSING (Paystack & Safaricom Rails)
    - M-Pesa: Triggers automated STK prompt on user's handset.
    - Card: Processes 3D-Secure verification via PCI-DSS Level 1 vault.
                         │
                         ▼
 3. ASYNCHRONOUS WEBHOOK SETTLEMENT
    Gateway emits signed HMAC callback -> POST /v1/webhooks/paystack
    -> Backend verifies signature -> Atomically credits billing.billing_accounts.balanceCents
    -> Writes audit record in billing.ledger_entries.

Financial Precision Guarantee

All balances inside Nyota Imara are calculated in integer subunits (e.g., KES cents, where 100 cents = KSh 1.00). This eliminates floating-point rounding errors common in software billing systems and guarantees that every cent deposited is accounted for.

2. Supported Payment Methods & Fees

3. Step-by-Step: How to Fund Your Wallet

Method A: Safaricom M-Pesa STK Push (Fastest)

1. Log in to accounts.nyotaimara.com/billing.
2. Under Workspace Balance, click "Add Funds".
3. Select your currency (KES) and enter the amount you wish to deposit (minimum KSh 10.00).
4. Select M-Pesa as your payment method.
5. Enter your Safaricom mobile phone number (e.g., 0712345678 or 0110000000).
6. Click "Top Up Wallet".
7. An automated PIN prompt will appear on your phone screen. Enter your M-Pesa PIN to complete the transaction.
8. Your wallet balance will update automatically within 5 seconds.

Method B: Credit or Debit Card

1. Navigate to accounts.nyotaimara.com/billing.
2. Click "Add Funds" and select Card.
3. Enter your card details (Card Number, Expiry, CVV).
4. Complete the 3D-Secure one-time password (OTP) verification sent by your issuing bank.
5. Optionally check "Save card for automated PAYG top-ups" to ensure your SMS broadcasts or verification sessions are never paused mid-execution.

4. Common Pitfalls & How to Troubleshoot

Pitfall A: "I entered my M-Pesa PIN, but my wallet balance hasn't updated."

• The Cause: Occasional network latency between Safaricom and the payment gateway, or the browser session timed out before the webhook settled.
• The Resolution (Self-Service Verification):
• 1. Open your M-Pesa confirmation SMS and find the transaction code (e.g., RKD7XXXXXX).
  2. Go to accounts.nyotaimara.com/billing.
  3. Locate the pending transaction row and click "Verify Transaction".
  4. The backend will manually query the payment gateway and credit your wallet immediately without needing a support ticket.

Pitfall B: "Why was I charged KSh 10.00 for a KSh 4.00 test?"

• The Cause: Payment gateways enforce a minimum transaction threshold of KSh 10.00 (1,000 cents) for mobile money and card transactions.
• The Resolution:
• • No money is lost. The full KSh 10.00 is credited to your active wallet balance.
  • Your KSh 4.00 operation is executed, and the remaining KSh 6.00 remains in your wallet for future API checks, SMS sends, or storage renewals.

Pitfall C: "My card was declined with an authentication error."

• The Cause: Your issuing bank blocked the transaction due to international/e-commerce fraud filters, or 3D-Secure OTP verification was not completed.
• The Resolution:
• • Ensure your card is enabled for international online transactions with your bank.
  • Alternatively, use instant Safaricom M-Pesa STK Push for 100% immediate settlement.

Related Support Guides & Links

• Managing Financial Shield Limits & Budget Caps
• Understanding Holds & Settlements in Nyota ID
• Direct Wallet Management Console