> For the complete documentation index, see [llms.txt](https://tuku-pay.gitbook.io/tuku-pay-internal-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tuku-pay.gitbook.io/tuku-pay-internal-docs/transactions/send-money.md).

# 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.