Request Money API

This API allows merchants to request payments from mobile money users with comprehensive validation, security checks, and transaction processing.

API Endpoint

POST
https://payments.vikotrust.com/api/request-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 request 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/request-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": "Payment request 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"}
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 requestMoney($apiKey, $accountNumber, $phoneNumber, $amount, $currency, $reference, $description) {

    $url = "https://payments.vikotrust.com/api/request-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 ($deced === null) $decoded = $response;

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

Node.js Implementation

const axios = require('axios');

async function requestMoney(apiKey, accountNumber, phoneNumber, amount, currency, reference, description) {
  const url = "https://payments.vikotrust.com/api/request-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 request_money(api_key, account_number, phone_number, amount, currency, reference, description):
    url = "https://payments.vikotrust.com/api/request-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)}
Security Requirements