TouchPay ORS Cashier API

Base URL:

    https://ors-api.touchpay.so/api/v1

Authentication

All requests must include the following headers:

X-API-KEY: your_api_key
X-API-SECRET: your_api_secret
Content-Type: application/json

1. Cashier Details

GET /cashier

Retrieve cashier profile information and available transaction limit.

Success Response

{
  "cashier_name": "Main Cashier",
  "agent_name": "TouchPay Agent",
  "available_limit": 150.75
}

Possible Errors

{
  "error": "CASHIER_NOT_FOUND"
}

2. Preview Remittance

POST /remittances/preview

Calculate fees, validate balance, and validate receiver name.

Request Body (JSON)

{
  "receiver_phone": "0615445566",
  "amount": 10,
  "country_code": 252
}

Success Response

{
  "success": true,
  "country_code": 252,
  "receiver_number": "0615445566",
  "receiver_name": "AHMED MOHAMED",
  "current_balance": 120.50,
  "send_amount": 10,
  "rate_percent": "1%",
  "commission_amount": 0.10,
  "total_deduction": 10.10,
  "balance_after_send": 110.40
}

Possible Errors

{
  "error": "INVALID_COUNTRY_CODE"
}

{
  "error": "CASHIER_NOT_FOUND"
}

{
  "error": "AGENT_NOT_FOUND"
}

{
  "error": "RATE_NOT_FOUND"
}

{
  "error": "INSUFFICIENT_BALANCE"
}

3. Submit Remittance

POST /remittances

Create a remittance transaction.

Request Body (JSON)

{
  "receiver_phone": "0615445566",
  "amount": 10,
  "country_code": 252,
  "reference_id": "ORDER-123456"
}

Success Response

{
  "success": true,
  "code": "REMITTANCE_CREATED",
  "message": "Remittance submitted successfully",
  "data": {
    "transaction_id": 206,
    "reference_id": "ORDER-123456"
  }
}

Possible Errors

{
  "error": "DUPLICATE_ORDER"
}

{
  "code": "RECEIVER_NAME_NOT_READY"
}

{
  "code": "CALCULATION_FAILED"
}

{
  "code": "REMITTANCE_FAILED"
}

4. Remittance History

GET /get-remittances

Retrieve cashier transaction history.

Optional Query Parameters

Parameter Type Description
from_date date Filter from date (YYYY-MM-DD)
to_date date Filter to date (YYYY-MM-DD)
status string Completed | Underprocess | Failed
transaction_id integer Filter by a specific transaction ID
reference_id string Filter by a specific reference ID

Success Response

{
  "count": 2,
  "data": [
    {
      "transaction_id": 206,
      "reference_id": "ORDER-123456",
      "receiver_phone": "0613504684",
      "receiver_country": "Somalia",
      "amount": 2,
      "commission": 0.02,
      "total_deduction": 2.02,
      "status": "Completed",
      "created_at": "2025-12-25 16:59:58"
    }
  ]
}