Phone Number Validation API

This API allows merchants to validate phone numbers (MSISDN) to ensure they are properly formatted and retrieve customer information before processing transactions.

API Endpoint

POST
https://payments.vikotrust.com/api/validate-msisdn

Headers

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

Request Parameters

Parameter Type Description Required Constraints
msisdn string Phone number to validate Yes International format (e.g. +256745198769)

Example Request

curl "https://payments.vikotrust.com/api/validate-msisdn" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Your API Key>" \
  -d '{
    "msisdn": "+256745198769"
  }'

Response

Success Response

{
  "success": true,
  "message": "Msisdn +256745198769 successfully validated.",
  "customer_name": "PETER OKIA"
}

Error Responses

Error Type HTTP Status Response Example
Missing API key 401 {"error": "API key missing"}
Missing required fields 400 {"error": "Missing required fields"}
Invalid API key 401 {"error": "Invalid API key"}
Invalid MSISDN format 400 {"error": "Invalid msisdn format"}
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 validateMsisdn($apiKey, $msisdn) {

    $url = "https://payments.vikotrust.com/api/validate-msisdn";

    $data = [
        "msisdn" => $msisdn
    ];

    $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 validateMsisdn(apiKey, msisdn) {
  const url = "https://payments.vikotrust.com/api/validate-msisdn";
  
  const data = { msisdn };
  
  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 validate_msisdn(api_key, msisdn):
    url = "https://payments.vikotrust.com/api/validate-msisdn"

    data = {
        "msisdn": msisdn
    }

    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