VixonPay v1
Overview
The VixonPay API enables seamless integration between your systems and VixonPay services. With it, you can:
- Collect Payments: Receive mobile money payments directly into your VixonPay wallet.
- Make Disbursements: Send funds from your wallet to mobile money accounts or commercial bank accounts.
- Manage Transactions: Access and work with transaction data to streamline your financial operations.
This documentation provides detailed guidance on available endpoints, request/response formats, and authentication requirements to help you integrate VixonPay efficiently.
Getting Started
Follow these 4 simple steps to start accepting payments with VixonPay:
- Register an Account - Sign up with your email and basic information
- Verify KYC - Submit your kyc documents for verification
- Get API Keys - Access your
Api keysfrom the dashboard Settings → API Keys - Accept Payments - Integrate our API and start accepting Mobile Money, Cards, and Wallet transfers
Webhook and Callback Notifications
The VixonPay API can automatically notify your system when transaction statuses change, eliminating the need for continuous polling. Webhooks provide real-time updates for collection and disbursement transactions.
How webhooks work
- Initiate a collection or disbursement request from your system to VixonPay.
- VixonPay processes the transaction and sends an HTTP POST request to your configured webhook URL when the transaction status changes.
- The webhook payload contains the complete transaction details and includes security headers for verification.
Example Incoming Webhook
JSON Payload
{
"event": "transaction.failed",
"data": {
"id": 31542,
"internal_reference": "VXN99817266291345",
"merchant_reference": "COL85b83e2a54193470735",
"transaction_type": "COLLECTION",
"request_currency": "UGX",
"transaction_amount": "500.00",
"transaction_charge": "0.00",
"transaction_account": "256751142954",
"total_credit": "0.00",
"provider_code": "airtel_ug",
"customer_name": "JOHN DOE",
"customer_email": "johndoe@gmail.com",
"transaction_status": "Failed",
"status_message": "Transaction failed due to timeout",
"description": "Test Collection"
}
}Webhook Headers
-
Content-Typestringrequired
-
X-VixonPay-Signaturestringrequired
HMAC SHA512 hash of the raw request body, computed using your webhook secret key
Webhook Events
-
transaction.completed
Transaction successfully completed - Triggered when transaction status changes to Completed
-
transaction.failed
Transaction failed - Triggered when transaction status changes to Failed
-
transaction.pending
Transaction is pending - Triggered when transaction is initiated and pending
Authentication
All webhook requests include an X-VixonPay-Signature header with a HMAC SHA512 hash of the payload for security verification. You should verify this signature to ensure the request is legitimate.
Signature Header
X-VixonPay-Signature: <hmac-sha512-signature>
This is a HMAC SHA512 hash of the raw request body, computed using your webhook secret key. You should compute the same hash and compare it to this value.
Content-Type
The request body is always JSON format containing transaction details.
Verification Steps
- Read the raw request body
- Compute HMAC SHA512 hash of the body using your webhook secret
- Compare your computed hash to the value in the X-VixonPay-Signature header
- Only process the webhook if the signatures match
Webhook Parameters
-
eventStringrequired
Event type (e.g., transaction.failed)
-
dataObjectrequired
Transaction data object
Transaction Data Fields
-
idInteger
Transaction ID
-
internal_referenceString
Internal transaction reference
-
merchant_referenceString
Merchant's reference ID
-
transaction_typeString
Transaction type (COLLECTION/PAYOUT)
-
request_currencyString
Transaction currency (UGX)
-
transaction_amountString
Transaction amount
-
transaction_chargeString
Transaction fee charged
-
transaction_accountString
Phone number used for transaction
-
total_creditString
Total amount credited
-
provider_codeString
Mobile money provider (airtel_ug, mtn_ug)
-
customer_nameString
Customer name
-
customer_emailString
Customer email
-
transaction_statusString
Transaction status (Completed, Pending, Failed)
-
status_messageString
Status description message
-
descriptionString
Transaction description
Code Examples
Receiving an event: A valid request from VixonPay has the header X-VixonPay-Signature which is a HMAC SHA512 hash of the payload. This hash is computed using your webhook secret key. To verify the authenticity of the request, you need to:
- Read the raw request body.
- Compute the HMAC SHA512 hash of the body using your webhook secret.
- Compare your computed hash to the value in the X-VixonPay-Signature header.
Below are sample codes in PHP:
PHP
$secret_key = 'your_webhook_secret';
$body = file_get_contents('php://input');
$data = json_decode($body, true);
$signature = $_SERVER['HTTP_X_VIXONPAY_SIGNATURE'] ?? '';
// Compute HMAC SHA512 hash of the raw body
(transaction_status, merchant_reference and internal_reference only)
$hash = hash_hmac('sha512', $body, $secret_key, false);
if (!hash_equals($hash, $signature)) {
http_response_code(401);
echo 'Unauthorized request!';
exit;
}
// Access the webhook data
$transactionStatus = $data['transaction_status'] ?? null;
$merchantReference = $data['merchant_reference'] ?? null;
$internalReference = $data['internal_reference'] ?? null;
// Your business logic here
// Process the transaction based on transactionStatus
http_response_code(200);
echo 'Success!';