Transaction Status API

This API allows merchants to check the status of previously submitted transactions. It provides detailed information about transaction processing, completion, and any failures.

API Endpoint

GET
https://payments.vikotrust.com/api/check-transaction-status

Headers

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

Query Parameters

Parameter Type Description Required
reference string Customer reference Yes
accountNumber string Your merchant account number Yes

Example Request

curl "https://payments.vikotrust.com/api/check-transaction-status?reference=invoice123&accountNumber=VT68488896328" \
  -X GET \
  -H "Authorization: Bearer <Your API Key>" \
  -H "Content-Type: application/json"

Response

Success Response

{
  "success": true,
  "status": "success",
  "message": "SUCCESS. TID 130269180792 SUCCESS.",
  "customer_reference": "invoice123",
  "internal_reference": "398581c01d1d95c3e482e259f489bed3",
  "msisdn": "+256745198769",
  "amount": 5000,
  "currency": "UGX",
  "provider": "AIRTEL_UGANDA",
  "request_status": "success",
  "provider_transaction_id": "TID130269180792",
  "completed_at": "2023-10-15T14:30:45Z",
  "charge": 0
}

Response Fields

Field Type Description
success boolean Indicates if the API request was successful
status string Overall transaction status (success, failed, pending)
message string Detailed message about the transaction status
customer_reference string Customer reference
internal_reference string Internal transaction reference used by the system
msisdn string Recipient's phone number
amount number Transaction amount
currency string Currency code (e.g., UGX)
provider string Mobile money provider (e.e., AIRTEL_UGANDA)
request_status string Detailed status from the payment provider
provider_transaction_id string Transaction ID from the payment provider
completed_at string Timestamp when the transaction was completed
charge number Transaction fee charged (0 for successful transactions)

Error Responses

Error Type HTTP Status Response Example
Missing API key 401 {"error": "API key missing"}
Missing required parameters 400 {"error": "reference and accountNumber are required"}
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"}
Transaction not found 404 {"error": "Transaction not found"}
Internal server error 500 {"error": "Internal server error"}

Implementation Examples

PHP Implementation

<?php
function checkTransactionStatus($apiKey, $reference, $accountNumber) {

    $url = "https://payments.vikotrust.com/api/check-transaction-status?reference=" . 
          urlencode($reference) . "&accountNumber=" . urlencode($accountNumber);

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

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    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 checkTransactionStatus(apiKey, reference, accountNumber) {
  const url = `https://payments.vikotrust.com/api/check-transaction-status?reference=${encodeURIComponent(reference)}&accountNumber=${encodeURIComponent(accountNumber)}`;
  
  const headers = { 
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  };
  
  try {
    const response = await axios.get(url, { 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
import urllib.parse

def check_transaction_status(api_key, reference, account_number):
    encoded_reference = urllib.parse.quote(reference)
    encoded_account = urllib.parse.quote(account_number)
    url = f"https://payments.vikotrust.com/api/check-transaction-status?reference={encoded_reference}&accountNumber={encoded_account}"

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

    try:
        response = requests.get(url, 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