Top up Wallets

API To Top up A Wallet from Mpesa, Bank, Visa, Other Banks and at Agent.

Overview

The wallet top-up functionality allows users to add funds to their wallets through various methods. Some methods involve internal system handling, such as M-Pesa STK push or Card payments, while others require external interaction, such as deposits at agents or transfers from other banks. Top-ups are free of charges unless external fees apply (e.g., M-Pesa transaction fees).

Top-Up Methods

Method	Handling	Description
M-Pesa (STK Push)	Internal	System sends a push notification to the user's M-Pesa account for authorization.
Deposit at Agent	External	User deposits money at a Tuku agent location. The agent updates the system with deposit details.
Visa/MasterCard	Internal	User provides card details for the transaction.
PayPal	Internal	User links their PayPal account and loads funds into their wallet.
Other Banks	External	User deposits money via other banks; Tuku Pay displays deposit instructions (e.g., account details).
Co-op Bank	Internal	System sends a push notification (similar to M-Pesa) for wallet top-up.
From Another Tuku Till	Internal	Transfer funds from one Tuku wallet to another.

---

Top-Up Endpoint

Endpoint: Top-Up Wallet

• Method: POST

• URL: /api/wallets/topup

Request Body:

{
  "appId": "app123",
  "walletNumber": "AAA0705035022",
  "method": "mpesa",
  "amount": 500,
  "details": {
    "phoneNumber": "[phone]"
  }
}

---

Top-Up Methods in Detail

1. M-Pesa (STK Push):

   • How it works: System sends an STK push to the user's M-Pesa phone number for authorization.

   • Additional Details Required:

     {
       "method": "mpesa",
       "details": {
         "phoneNumber": "[phone]"
       }
     }

2. Deposit at Agent:

   • How it works: User deposits funds with an agent. The agent updates the system with the transaction details.

   • Additional Details Required: Users receive deposit instructions, and agents will provide a receipt code.

3. Visa/MasterCard:

   • How it works: User enters card details via a secure payment gateway.

   • Additional Details Required:

     {
       "method": "card",
       "details": {
         "cardNumber": "4111111111111111",
         "expiryDate": "12/25",
         "cvv": "123"
       }
     }

4. PayPal:

   • How it works: User links a PayPal account and transfers funds.

   • Additional Details Required:

     {
       "method": "paypal",
       "details": {
         "paypalAccount": "[e-mail]"
       }
     }

5. Other Banks:

   • How it works: User initiates a transfer from their bank using displayed Tuku Pay deposit instructions.

   • Additional Details Provided by System:

     {
       "bankName": "Equity Bank",
       "accountName": "Tuku Pay",
       "accountNumber": "1234567890"
     }

6. Co-op Bank:

   • How it works: System sends a push notification for authorization, similar to M-Pesa STK Push.

   • Additional Details Required:

     {
       "method": "coop_bank",
       "details": {
         "phoneNumber": "[phone]"
       }
     }

7. From Another Tuku Till:

   • How it works: Funds are transferred from one Tuku wallet to another within the system.

   • Additional Details Required:

     {
       "method": "tuku_till",
       "details": {
         "sourceWallet": "AAA0705035021"
       }
     }

---

Response

Success Response:

{
  "status": "success",
  "message": "Top-up successful.",
  "transactionId": "TRX123456789",
  "updatedBalance": 1500
}

Error Response:

{
  "status": "error",
  "message": "Failed to process top-up. Check details and try again."
}

---

Additional Notes

1. Real-Time Updates: Top-up balances are updated in real time for methods handled internally.

2. External Methods: Deposits through agents or other banks may take longer and require manual confirmation.

3. Free Top-Up: No charges are applied by Tuku Pay for top-ups unless third-party fees (e.g., M-Pesa) are involved.