> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uw.stargate.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Cash-In Operations via API

> Learn how to programmatically create cash-in operations using the Distributor API

## Introduction

Cash-in operations allow distributors to credit wallets in exchange for physical cash. Distributors can cash-in to two types of destinations:

* **Individual wallets** — identified by the end user's phone number
* **Merchant wallets** — identified by the merchant's short code

<Panel>
  ```mermaid theme={null}
  sequenceDiagram
      participant User as End User / Merchant
      participant Distributor as Distributor System
      participant API as Universal Wallet API
      participant Wallet as Destination Wallet

      User->>Distributor: Gives Cash
      Distributor->>API: POST /api/v1/distributors/{distributorID}/operations
      API->>API: Validate permissions & limits
      API->>Wallet: Credit destination wallet
      API->>Distributor: Return operation ID
      Distributor->>User: Confirms transaction
  ```
</Panel>

## Prerequisites

* An active API key with **Perform Operations** permission
* Sufficient distributor balance to cover the cash-in amount
* End user's mobile phone number **or** merchant's short code

<Warning>
  Cash-in operations follow the maker-checker pattern. API requests create pending operations that require approval before execution.
</Warning>

## Cash-In to Individual Wallet

Send a cash-in with the `phoneTo` field to credit an individual wallet.

### Request Body

```json theme={null}
{
  "operationType": "cash-in",
  "amount": "5000.00",
  "phoneTo": "+234 8123456781"
}
```

### Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations" \
    -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "operationType": "cash-in",
      "amount": "5000.00",
      "phoneTo": "+234 8123456781"
    }'
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const distributorID = '36e48800-22ce-4ea0-b37a-198f7978cd53';
  const apiKey = 'uwk_YOUR_API_KEY_HERE';

  const response = await axios.post(
    `https://api.yourdomain.com/api/v1/distributors/${distributorID}/operations`,
    {
      operationType: 'cash-in',
      amount: '5000.00',
      phoneTo: '+234 8123456781'
    },
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log('Operation ID:', response.data.operationID);
  ```

  ```python Python theme={null}
  import requests

  distributor_id = '36e48800-22ce-4ea0-b37a-198f7978cd53'
  api_key = 'uwk_YOUR_API_KEY_HERE'

  response = requests.post(
      f'https://api.yourdomain.com/api/v1/distributors/{distributor_id}/operations',
      headers={
          'Authorization': f'Bearer {api_key}',
          'Content-Type': 'application/json'
      },
      json={
          'operationType': 'cash-in',
          'amount': '5000.00',
          'phoneTo': '+234 8123456781'
      }
  )

  print('Operation ID:', response.json()['operationID'])
  ```
</CodeGroup>

## Cash-In to Merchant Wallet

Send a cash-in with the `merchantToShortCode` field to credit a merchant wallet. The merchant is identified by their short code (e.g., `100000`).

### Request Body

```json theme={null}
{
  "operationType": "cash-in",
  "amount": "25000.00",
  "merchantToShortCode": "100000"
}
```

### Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations" \
    -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "operationType": "cash-in",
      "amount": "25000.00",
      "merchantToShortCode": "100000"
    }'
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const distributorID = '36e48800-22ce-4ea0-b37a-198f7978cd53';
  const apiKey = 'uwk_YOUR_API_KEY_HERE';

  const response = await axios.post(
    `https://api.yourdomain.com/api/v1/distributors/${distributorID}/operations`,
    {
      operationType: 'cash-in',
      amount: '25000.00',
      merchantToShortCode: '100000'
    },
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log('Operation ID:', response.data.operationID);
  ```

  ```python Python theme={null}
  import requests

  distributor_id = '36e48800-22ce-4ea0-b37a-198f7978cd53'
  api_key = 'uwk_YOUR_API_KEY_HERE'

  response = requests.post(
      f'https://api.yourdomain.com/api/v1/distributors/{distributor_id}/operations',
      headers={
          'Authorization': f'Bearer {api_key}',
          'Content-Type': 'application/json'
      },
      json={
          'operationType': 'cash-in',
          'amount': '25000.00',
          'merchantToShortCode': '100000'
      }
  )

  print('Operation ID:', response.json()['operationID'])
  ```
</CodeGroup>

<Note>
  You must provide either `phoneTo` or `merchantToShortCode`, but not both. The API will return a validation error if both fields are provided or if neither is provided.
</Note>

## Response

### Success Response (200 OK)

```json theme={null}
{
  "operationID": "op_8b7c9d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e"
}
```

## Parameters

### Endpoint

```
POST /api/v1/distributors/{distributorID}/operations
```

### Request Headers

```http theme={null}
Authorization: Bearer uwk_YOUR_API_KEY_HERE
Content-Type: application/json
```

### Fields

<ParamField path="operationType" type="string" required>
  Type of operation. Must be `"cash-in"` for cash-in operations.
</ParamField>

<ParamField path="amount" type="string" required>
  Amount to credit to the destination wallet. Must be a valid decimal string (e.g., "1000.00").
</ParamField>

<ParamField path="phoneTo" type="string">
  End user's mobile phone number in international format (e.g., "+234 8123456781"). Required when cashing in to an individual wallet.
</ParamField>

<ParamField path="merchantToShortCode" type="string">
  Merchant's short code number (e.g., "100000"). Required when cashing in to a merchant wallet.
</ParamField>

<ParamField path="memo" type="string">
  Optional reference note or description (e.g., "Cash deposit - Receipt #1234").
</ParamField>

## Next Steps

<CardGroup cols={2}>
  <Card title="Cash-Out via API" icon="arrow-down" href="/distributors/api-tutorials/cash-out">
    Learn how to process cash-out operations
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/distributors/authentication">
    Full API endpoint documentation
  </Card>
</CardGroup>