Withdraw

Overview

The Withdraw Money functionality allows users to withdraw funds from their wallets to various destinations. The supported withdrawal types are:

• toBank: Withdraw funds to a bank account.

• toMobileWallet: Withdraw funds to a mobile money wallet (e.g., M-Pesa).

• toVisaMasterCard: Withdraw funds to a Visa or MasterCard account.

• toAgent: Withdraw cash at a registered Tuku Pay agent.

Each withdrawal transaction is recorded, and the associated transaction cost is logged separately, linked to the parent withdrawal transaction for traceability.

---

Endpoint: Withdraw Money

• Method: POST

• URL: /api/transactions/withdraw

Request Body:

{
  "appId": "app123",
  "walletNumber": "AAA0705035022",
  "destination": {
    "type": "toMobileWallet",
    "accountNumber": "[phone]"
  },
  "amount": 5000,
  "description": "Withdraw funds to mobile wallet",
  "metadata": {
    "referenceId": "WITHDRAW12345",
    "additionalInfo": "Transaction at Agent #001"
  }
}

Request Body Fields:

Field	Type	Required	Description
appId	string	Yes	The app identifier from which the transaction originates.
walletNumber	string	Yes	The source wallet/account number.
destination.type	string	Yes	Type of withdrawal (toBank, toMobileWallet, toVisaMasterCard, toAgent).
destination.accountNumber	string	Yes	The destination account or phone number for the withdrawal.
amount	number	Yes	The amount to be withdrawn.
description	string	No	A brief description of the transaction.
metadata	object	No	Optional metadata for custom fields (e.g., reference IDs, additional info).

---

Transaction Cost Record for Withdrawals

Endpoint:

• Method: POST

• URL: /api/transaction-costs

Request Body:

{
  "parentTransactionId": "TRX654321",
  "appId": "app123",
  "walletNumber": "AAA0705035022",
  "destination": {
    "type": "toMobileWallet",
    "accountNumber": "[phone]"
  },
  "transactionCost": 30,
  "description": "Transaction cost for withdrawal"
}

Request Body Fields:

Field	Type	Required	Description
parentTransactionId	string	Yes	The ID of the parent transaction.
appId	string	Yes	The app identifier from which the transaction originates.
walletNumber	string	Yes	The source wallet/account number.
destination	object	Yes	Details of the destination (same as the parent transaction).
transactionCost	number	Yes	The transaction cost amount.
description	string	No	A brief description of the transaction cost.

---

Supported Withdrawal Types

Type	Description
toBank	Withdraw funds to a bank account.
toMobileWallet	Withdraw funds to a mobile money wallet (e.g., M-Pesa).
toVisaMasterCard	Withdraw funds to a Visa or MasterCard account.
toAgent	Withdraw cash at a Tuku Pay registered agent.

---

Response: Withdraw Money

Success Response:

{
  "status": "success",
  "transactionId": "TRX654321",
  "transactionCostId": "COST654321",
  "message": "Withdrawal successful.",
  "updatedBalance": 4500
}

Error Response:

{
  "status": "error",
  "message": "Failed to process the withdrawal. Please try again."
}

---

Business Rules for Withdrawal

1. Charges:

   • Transaction costs are calculated separately and stored as independent records linked to the parent transaction.

   • Withdrawal to certain types (e.g., agents, mobile wallets) may incur external charges.

2. Validation:

   • Ensure sufficient funds are available in the wallet before processing the transaction.

   • Verify the destination account is valid and active.

3. Notifications:

   • Notify the user of successful withdrawal or failure via SMS, email, or app notification.

4. Agent Withdrawals:

   • Withdrawal at an agent requires the agent's ID in the metadata field.

   • Provide a unique code to the user for verification at the agent.

---

Example Flow

1. User Action:

   • A user requests to withdraw KES 5,000 to their M-Pesa account.

2. System Processing:

   • The system validates the wallet balance, calculates transaction costs (e.g., KES 30), and creates a withdrawal transaction record (TRX654321).

   • A separate transaction cost record (COST654321) is created and linked to the withdrawal.

3. Notification:

   • The system notifies the user of successful processing and updates the wallet balance.

---