Introduction
Vixzz provides a unified API to access our proprietary mobile money ledger. Our infrastructure is completely independent of traditional telecom networks, ensuring 99.99% uptime and instant settlement.
Base URL: All API requests should be made
to https://api.vixzzpay.com/v1/
Authentication
All API requests require an access token. Generate a token using
your
access_key and
access_secret. Include the token in every request header.
Request Body
{
"access_key": "ak_your_access_key",
"access_secret": "as_your_access_secret"
} {
"status": "success",
"data": {
"token": "sk_live_abc123xyz789...",
"expires_in": 3600
}
} Required Headers for All API Requests
Authorization Bearer token from /auth/token (e.g. 'Bearer sk_live_...')
account_short_code Your Vixzz business account short code.
callback_url URL to receive transaction webhook notifications.
{
"Authorization": "Bearer sk_live_abc123xyz789...",
"account_short_code": "123456",
"callback_url": "https://yourdomain.com/webhooks/vixzz",
"Content-Type": "application/json"
} Errors & Codes
| Code | Description |
|---|---|
| 200 | Request successful. |
| 400 | Bad Request. Invalid parameters. |
| 401 | Unauthorized. Check your API key. |
Verify User
Validate a Vixzz user's wallet ID (email or phone) before initiating a transaction. This ensures the account exists on our ledger.
curl "https://api.vixzzpay.com/v1/customers/verify?account_number=+254712345678" \ -u sk_test_...:
Parameters
account_number The customer's Vixzz Wallet ID (email or phone).
{
"status": "success",
"data": {
"account_number": "+254712345678",
"name": "JANE DOE",
"valid": true,
"kyc_level": "tier_2"
}
} Request OTP
Before initiating a collection, you must first request a 6-digit OTP which will be sent to the user's Vixzz App. This OTP is required for the collection request.
{
"account_number": "+254712345678",
"purpose": "collection"
} Parameters
account_number The customer's Vixzz Wallet ID (email or phone).
purpose The purpose of the OTP. Use 'collection' for C2B transactions.
{
"status": "success",
"message": "OTP sent to user",
"data": {
"otp_reference": "otp_abc123xyz",
"expires_in": 300
}
} Collect Money (C2B)
Charge a Vixzz wallet. Important: You must first
request an OTP using the /otp/request
endpoint and include the 6-digit OTP in the request body.
{
"amount": 5000,
"currency": "MWK",
"account_number": "+254712345678",
"otp": "123456",
"description": "Order #8822"
} Parameters
amount The amount to charge in smallest currency unit.
currency The 3-letter ISO currency code (e.g. MWK, USD).
account_number The Wallet ID of the person paying you.
otp The 6-digit OTP received by the user.
description A note about the transaction.
{
"status": "success",
"message": "Payment collected",
"data": {
"id": "tr_123456789",
"status": "success",
"amount": 5000,
"currency": "MWK"
}
} Send Money (B2C)
Instant transfer from your business wallet to another user's Vixzz wallet.
{
"amount": 10000,
"currency": "MWK",
"recipient_account": "bob@vixzz.com",
"narration": "Salary Payment"
} Parameters
amount The amount to send.
currency The currency code.
recipient_account The Wallet ID of the recipient.
narration Reason for payment.
{
"status": "success",
"message": "Transfer successful",
"data": {
"id": "po_99887766",
"status": "success",
"amount": 10000,
"recipient": "bob@vixzz.com"
}
} B2B Transfer
Transfer funds between business accounts on the Vixzz network.
{
"amount": 50000,
"currency": "KES",
"transfer_type": "merchant",
"recipient_short_code": "654321",
"narration": "Vendor Payment"
} Parameters
amount The amount to transfer.
currency The 3-letter ISO currency code.
transfer_type Type of recipient: 'merchant' or 'biller'.
recipient_short_code The recipient business short code.
narration Reason for transfer.
{
"status": "success",
"message": "B2B transfer successful",
"data": {
"id": "b2b_55667788",
"status": "success",
"amount": 50000
}
} Reverse Transaction
Reverse a completed transaction. Only eligible transactions can be reversed.
{
"transaction_id": "tr_123456789",
"reason": "Customer refund request"
} Parameters
transaction_id The ID of the transaction to reverse.
reason Reason for the reversal.
{
"status": "success",
"message": "Transaction reversed",
"data": {
"id": "rv_998877",
"original_transaction": "tr_123456789",
"status": "reversed",
"amount": 5000
}
} Account Balance
Retrieve the current balance of your business account.
curl "https://api.vixzzpay.com/v1/balance" \ -H "Authorization: Bearer sk_live_..."
{
"status": "success",
"data": {
"available_balance": 1250000,
"pending_balance": 50000,
"currency": "KES",
"last_updated": "2024-01-27T10:30:00Z"
}
} Dynamic QR Code
Generate a dynamic QR code for payment collection. Returns the QR code image as a base64-encoded string.
{
"amount": 1500,
"currency": "KES",
"description": "Coffee Order #42",
"expires_in": 600
} Parameters
amount The amount to collect.
currency The 3-letter ISO currency code.
description Description shown to the payer.
expires_in QR code expiry in seconds (default: 600).
{
"status": "success",
"data": {
"qr_id": "qr_aabbccdd",
"qr_image": "data:image/png;base64,iVBORw0KGgo...",
"amount": 1500,
"currency": "KES",
"expires_at": "2024-01-27T10:40:00Z"
}
} Check Transaction Status
Check the status of a specific transaction on the ledger.
curl "https://api.vixzzpay.com/v1/transactions/tr_123456789" \ -u sk_test_...:
{
"status": "success",
"data": {
"id": "tr_123456789",
"type": "collection",
"status": "success",
"amount": 5000,
"currency": "MWK"
}
} Webhooks
We send a JSON POST request to your webhook URL when a transaction reaches a final state.
{
"id": "evt_2398423",
"type": "charge.success",
"created_at": "2023-10-25T10:05:00Z",
"data": {
"id": "tr_123456789",
"amount": 5000,
"status": "success",
"customer": {
"account_number": "+254712345678"
}
}
}