# Send Money

**Overview**

The Send Money functionality allows users to transfer money from their wallet to various destinations. Supported transaction types include:

* **`toBank`**: Transfer to a bank account.
* **`toMobileWallet`**: Transfer to a mobile wallet like M-Pesa.
* **`toPayPal`**: Transfer to a PayPal account.
* **`toVisaMasterCard`**: Transfer to a Visa or MasterCard account.

Each transaction is recorded with its own transaction ID, and the associated transaction cost is recorded separately, linked to the parent transaction for traceability.

***

**Endpoint: Send Money**

* **Method:** `POST`
* **URL:** `/api/transactions/send-money`

**Request Body:**

```json
{
  "appId": "app123",
  "walletNumber": "AAA0705035022",
  "destination": {
    "type": "toMobileWallet",
    "accountNumber": "+254700123456"
  },
  "amount": 1000,
  "description": "Payment for goods",
  "metadata": {
    "referenceId": "REF12345",
    "additionalInfo": "Invoice #9876"
  }
}
```

**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 destination (`toBank`, `toMobileWallet`, `toPayPal`, `toVisaMasterCard`). |
| `destination.accountNumber` | `string` | Yes          | The destination account, such as a phone number, bank account, or PayPal ID.      |
| `amount`                    | `number` | Yes          | The amount to be sent.                                                            |
| `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**

**Endpoint:**

* **Method:** `POST`
* **URL:** `/api/transaction-costs`

**Request Body:**

```json
{
  "parentTransactionId": "TRX123456",
  "appId": "app123",
  "walletNumber": "AAA0705035022",
  "destination": {
    "type": "toMobileWallet",
    "accountNumber": "+254700123456"
  },
  "transactionCost": 15,
  "description": "Transaction cost for sending money"
}
```

**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 Transaction Types**

| **Type**           | **Description**                                   |
| ------------------ | ------------------------------------------------- |
| `toBank`           | Transfer money to a bank account.                 |
| `toMobileWallet`   | Transfer money to a mobile wallet (e.g., M-Pesa). |
| `toPayPal`         | Transfer money to a PayPal account.               |
| `toVisaMasterCard` | Transfer money to a Visa or MasterCard account.   |

***

**Response: Send Money**

**Success Response:**

```json
{
  "status": "success",
  "transactionId": "TRX123456",
  "transactionCostId": "COST123456",
  "message": "Money sent successfully.",
  "updatedBalance": 900
}
```

**Error Response:**

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

***

**Example Flow**

1. **Send Money Request:**
   * A user initiates a transaction to send KES 1,000 to a PayPal account.
2. **Transaction Processing:**
   * The system creates a parent transaction record (e.g., `TRX123456`) with all details.
   * Simultaneously, it calculates the transaction cost (e.g., KES 15) and creates a separate transaction cost record (`COST123456`) linked to `TRX123456`.
3. **Database Linking:**
   * Both records are stored, and the `parentTransactionId` in the cost record links them.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tuku-pay.gitbook.io/tuku-pay-internal-docs/transactions/send-money.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.