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

# Create Operation

> Create a new merchant operation (cash-out, pay-merchant, or pay-individual)

## Endpoint

```
POST /api/v1/merchants/{merchantID}/operations
```

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key. Must have **Perform Operations** permission.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

## Path Parameters

<ParamField path="merchantID" type="string" required>
  The unique identifier of the merchant. Must match the merchant ID associated with the API key.
</ParamField>

## Request Body

### Cash-Out Operation

<ParamField body="operationType" type="string" required>
  Must be `"cash-out"`
</ParamField>

<ParamField body="amount" type="string" required>
  Amount to withdraw (e.g., "20000.00")
</ParamField>

<ParamField body="distributorToShortCode" type="string" required>
  Distributor short code to withdraw to
</ParamField>

<ParamField body="memo" type="string">
  Optional reference note or description for the operation
</ParamField>

### Pay Merchant Operation

<ParamField body="operationType" type="string" required>
  Must be `"pay-merchant"`
</ParamField>

<ParamField body="amount" type="string" required>
  Amount to pay (e.g., "15000.00")
</ParamField>

<ParamField body="merchantToShortCode" type="string" required>
  Destination merchant's short code
</ParamField>

<ParamField body="memo" type="string">
  Optional reference note or description for the operation
</ParamField>

### Pay Individual Operation

<ParamField body="operationType" type="string" required>
  Must be `"pay-individual"`
</ParamField>

<ParamField body="amount" type="string" required>
  Amount to pay (e.g., "3000.00")
</ParamField>

<ParamField body="phoneTo" type="string" required>
  Recipient's phone number in international format (e.g., "+234 8123456781")
</ParamField>

<ParamField body="memo" type="string">
  Optional reference note or description for the operation
</ParamField>

## Response

<ResponseField name="operationID" type="string">
  Unique identifier for the created operation
</ResponseField>

<RequestExample>
  ```bash Cash-Out cURL theme={null}
  curl -X POST "https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/operations" \
    -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "operationType": "cash-out",
      "amount": "20000.00",
      "distributorToShortCode": "100000",
      "memo": "Cash withdrawal"
    }'
  ```

  ```bash Pay Merchant cURL theme={null}
  curl -X POST "https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/operations" \
    -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "operationType": "pay-merchant",
      "amount": "15000.00",
      "merchantToShortCode": "100001",
      "memo": "Wholesale payment"
    }'
  ```

  ```bash Pay Individual cURL theme={null}
  curl -X POST "https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/operations" \
    -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "operationType": "pay-individual",
      "amount": "3000.00",
      "phoneTo": "+234 8123456781",
      "memo": "Refund for order #1234"
    }'
  ```

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

  const response = await axios.post(
    'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/operations',
    {
      operationType: 'pay-merchant',
      amount: '15000.00',
      merchantToShortCode: '100001',
      memo: 'Wholesale payment'
    },
    {
      headers: {
        'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE',
        'Content-Type': 'application/json'
      }
    }
  );

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

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

  response = requests.post(
      'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/operations',
      json={
          'operationType': 'pay-individual',
          'amount': '3000.00',
          'phoneTo': '+234 8123456781',
          'memo': 'Refund for order #1234'
      },
      headers={'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE'}
  )

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

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

  ```json 400 Bad Request - Invalid Amount theme={null}
  {
    "type": "/problems/input-validation-problems",
    "status": 400,
    "title": "There are some validation errors",
    "detail": "Please fix the validation issues and try again",
    "errors": [
      {
        "type": "/problems/input-validation-problems/invalid-field",
        "field": "amount",
        "detail": "Amount must be a valid decimal number"
      }
    ]
  }
  ```

  ```json 403 Forbidden - Insufficient Permission theme={null}
  {
    "type": "/problems/access-forbidden",
    "status": 403,
    "title": "Access Forbidden",
    "detail": "API key does not have Perform Operations permission"
  }
  ```

  ```json 403 Forbidden - Insufficient Balance theme={null}
  {
    "type": "/problems/insufficient-balance",
    "status": 403,
    "title": "Insufficient Balance",
    "detail": "Insufficient balance to complete this operation"
  }
  ```
</ResponseExample>

## Maker-Checker Workflow

<Note>
  Operations created via API follow the maker-checker approval pattern. The operation is created in a **pending** state and requires approval by a checker before execution.
</Note>

After creating an operation:

1. Operation is saved with status **pending**
2. A checker with appropriate permissions must approve it via the web interface
3. Once approved, the operation is executed on the blockchain
4. The operation status changes to **completed** or **failed**

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Balance" icon="wallet" href="/api-reference/merchants/get-balance">
    Check merchant balance before creating operations
  </Card>

  <Card title="Get Operations" icon="list" href="/api-reference/merchants/get-operations">
    Query operation history and status
  </Card>
</CardGroup>