UnitedApi - Virtual Account API Documentation

API Endpoint

Base URL: https://unitedapi.ng/api/virtual-account/

Authentication

Include the API key in the headers using the Authorization token.

{
  "Authorization": "Token your-api-key-here"
}

Request Headers

Header	Type	Description
Content-Type	string	application/json
Authorization	string	API token required

Request Parameters

Parameter	Type	Status	Description
firstname	string	Required	Customer's firstname name
lastname	string	Required	Customer's last name
phoneNumber	string	Required	Customer's phone number
bvn	string	optional	e.g 225225223234
webhook_url	string	Required	URL to receive transaction updates

Example Request

{
    "firstname": "Halima",
    "lastname": "Muhammad",
    "phoneNumber": "07065390488",
    "bvn": "optional",
    "webhook_url": "https://yourwebhook.com/callback2"
}

Example Response

{
    "success": true,
    "data": {
        "metadata": {},
        "createdAt": 1717077370399,
        "updatedAt": 1717077370399,
        "id": 1,
        "accountNumber": "0000000033",
        "accountName": "UnitedApi - Ismail",
        "accountType": "individual",
        "firstname": "John",
        "lastname": "Doe",
        "middlename": "User",
        "mobileNumber": "08091329974",
        "externalReference": "24053014560933057683",
        "emailAddress": "ahmad9980@doe.com",
        "bvn": "992323214",
        "gender": "male",
        "address": "wall street",
        "dateOfBirth": "1993/12/29",
        "validityType": "permanent"
    }
}

Error Responses

{
  "status": "fail",
  "msg": "Missing required parameters: email, phone_number"
}

{
  "status": "fail",
  "msg": "Your authorization token is required."
}

Webhook Implementation

Webhook Security Guidelines Introduction To ensure the integrity and authenticity of webhook requests sent from our system, follow these security best practices when handling incoming webhooks. 1. Verify the Webhook Signature Each webhook request includes an x-api-signature header, which is an HMAC SHA-512 hash of the request payload. This signature ensures that the webhook originates from us and has not been tampered with. How to Verify the Signature Retrieve your API key from your secure storage. Compute an HMAC SHA-512 hash of the request payload using your API key. Compare the computed hash with the x-api-signature header value. If they match, process the request. Otherwise, reject it.

{
  "event": "collection",
  "reference": "GREENBOOK_0012503061243548473552096512",
  "virtualAccount": "1000111082",
  "externalReference": "2405301456093305768388",
  "amountReceived": "2500.0",
  "sessionId": "999999999900124056556",
  "sourceCurrency": "NGN",
  "sourceAccountNumber": "0123456789",
  "sourceAccountName": "John Doe",
  "sourceBankCode": "0001",
   "sourceBankName": "Test Bank",
   "remarks":"Testing",
  "destinationCurrency": "NGN",
  "status": "success",
  "createdAt": 1717079472957,
  "updatedAt": 1717079473518
}

function verifyWebhookSignature($payload, $receivedSignature, $apiKey) {
    $computedHash = hash_hmac('sha512', $payload, $apiKey);
    return hash_equals($computedHash, $receivedSignature);
}

// Get raw POST body
$payload = file_get_contents("php://input");

// Get signature from header
$receivedSignature = $_SERVER['HTTP_X_API_SIGNATURE'] ?? '';

// Your API key (fetch securely)
$apiKey = 'your_api_key_here'; 

// Verify the signature
if (!verifyWebhookSignature($payload, $receivedSignature, $apiKey)) {
    http_response_code(403);
    die("Invalid webhook signature");
}

// Process the webhook
$data = json_decode($payload, true);

Example Frontend Integration

Use Php to integrate the API into your website.

fetch("https://unitedapi.ng/api/virtual-account/", {
  // Generate payload
    $payload = json_encode([
        "firstname" => $fname,
        "lastname" => $lname,
        "phoneNumber" => $phone,
        "webhook_url" => "https://yoursite.com/webhook/unitedapi/"
    ]);

    // Initialize CURL request
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POSTFIELDS => $payload,
        CURLOPT_HTTPHEADER => [
            "Authorization: Token dkjfhkdjghbvjdghkjdfnzmvhudriyg7iduhfkjvnzjkf",
            "Content-Type: application/json",
        ],
    ]);

    // Execute CURL request and decode response
    $result = curl_exec($ch);
    curl_close($ch);
    $response = json_decode($result, true);

    // Log the response for debugging
    file_put_contents("unitedapi_log.txt", $result);

   if (isset($response['data']['accountNumber'])) {
    $accountNumber = $response['data']['accountNumber'];