Send Money API Documentation

API Endpoint

POST

https://payments.vikotrust.com/api/send-money

Headers

Header	Description	Required
Content-Type	application/json	Yes
Authorization	Bearer <Your API Key>	Yes

Request Parameters

Parameter	Type	Description	Required	Constraints
accountNumber	string	Your merchant account number	Yes	Must match API key owner
phoneNumber	string	Recipient's phone number	Yes	International format (e.g. +256...)
amount	float	Amount to send	Yes	Positive number
currency	string	Currency code	Yes	3-letter code (e.g. UGX)
reference	string	Your transaction reference	Yes	No spaces allowed, max 15 characters
description	string	Payment description	Yes	Max 255 chars

Example Request

curl "https://payments.vikotrust.com/api/send-money" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Your API Key>" \
  -d '{
    "accountNumber": "VT68488896328",
    "phoneNumber": "+256745198769",
    "amount": 5000.00,
    "currency": "UGX",
    "reference": "invoice123",
    "description": "Payment for services rendered"
  }'

Response

Success Response

{
  "success": true,
  "message": "Send payment in progress.",
  "internal_reference": "d3ae5e14f05fcc58427331d38cb11d42"
}

Error Responses

Error Type	HTTP Status	Response Example
Missing API key	401	{"error": "API key missing"}
Missing required fields	400	{"error": "Missing required fields"}
Reference contains spaces	400	{"error": "Reference must not contain spaces"}
Reference too long	400	{"error": "Reference must be at most 15 characters"}
Invalid API key	401	{"error": "Invalid API key"}
Account mismatch	403	{"error": "Account number does not match API key owner"}
Merchant not found	404	{"error": "Merchant not found"}
Account not verified	403	{"error": "Your account is not authorized"}
IP not allowed	403	{"error": "IP <client_ip> not allowed"}
Insufficient balance	400	{"error": "Insufficient balance"}
Rate limit exceeded	429	{"success": false, "message": "Too many requests. Please try again later."}
Internal server error	500	{"error": "Internal server error"}

Implementation Examples

PHP Implementation

<?php
function sendMoney($apiKey, $accountNumber, $phoneNumber, $amount, $currency, $reference, $description) {

    $url = "https://payments.vikotrust.com/api/send-money";

    $data = [
        "accountNumber" => $accountNumber,
        "phoneNumber" => $phoneNumber,
        "amount" => $amount,
        "currency" => $currency,
        "reference" => $reference,
        "description" => $description
    ];

    $headers = [
        "Content-Type: application/json",
        "Authorization: Bearer " . $apiKey
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    $response = curl_exec($ch);

    if ($response === false) {
        $error = curl_error($ch);
        curl_close($ch);
        return ["error" => "cURL error: " . $error];
    }

    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $decoded = json_decode($response, true);
    if ($decoded === null) $decoded = $response;

    return [
        "httpCode" => $httpCode,
        "response" => $decoded
    ];
}
?>

Node.js Implementation

const axios = require('axios');

async function sendMoney(apiKey, accountNumber, phoneNumber, amount, currency, reference, description) {
  const url = "https://payments.vikotrust.com/api/send-money";
  
  const data = { accountNumber, phoneNumber, amount, currency, reference, description };
  
  const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` };
  
  try {
    const response = await axios.post(url, data, { headers });
    return { httpCode: response.status, response: response.data };
  } catch (error) {
    return {
      httpCode: error.response?.status || null,
      response: error.response?.data || error.message
    };
  }
}

Python Implementation

import requests

def send_money(api_key, account_number, phone_number, amount, currency, reference, description):
    url = "https://payments.vikotrust.com/api/send-money"

    data = {
        "accountNumber": account_number,
        "phoneNumber": phone_number,
        "amount": amount,
        "currency": currency,
        "reference": reference,
        "description": description
    }

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }

    try:
        response = requests.post(url, json=data, headers=headers)
        try:
            body = response.json()
        except ValueError:
            body = response.text
        return {"httpCode": response.status_code, "response": body}
    except requests.RequestException as e:
        return {"httpCode": None, "response": str(e)}