API Documentation

Welcome to the Vixzz Developer API. Build the future of payments by integrating our secure, instant, and reliable mobile money endpoints.

Base URL

https://api.vixzz.com/v1

Support

Need help integrating?

Contact Developer Support →

Authentication

The Vixzz API uses Bearer Token authentication. You must include your Secret Key in the Authorization header for all requests.

Header Example
Authorization: Bearer sk_live_839293848239023849023

Error Types

We use standard HTTP status codes to indicate the success or failure of your API requests. The body of the response will contain a JSON object with more details.

StatusError CodeDescription
400BAD_REQUESTThe request was invalid or missing parameters.
401UNAUTHORIZEDInvalid API key provided.
402INSUFFICIENT_FUNDSThe wallet balance is too low to complete the transaction.
404NOT_FOUNDThe requested resource (e.g., Transaction ID) does not exist.
429RATE_LIMITToo many requests. Please slow down.
500SERVER_ERRORSomething went wrong on our end.

Error Response Example

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Your wallet balance is KES 200.00, but the transaction requires KES 500.00.",
    "doc_url": "https://api.vixzz.com/errors/402"
  }
}

Customer to Business (C2B)

Trigger an STK Push to a customer's phone. This will prompt them to enter their PIN to authorize a payment to your business.

POST/c2b/simulate
Request Body
{
  "phone_number": "+254700000000",
  "amount": 500,
  "currency": "KES",
  "account_reference": "ORDER-123",
  "transaction_desc": "Payment for goods"
}
Response Example
{
  "status": "success",
  "message": "Payment request sent",
  "checkout_request_id": "ws_CO_123456789"
}

Business to Customer (B2C)

Send funds from your business Paybill/Till to a customer. Useful for salary disbursements, refunds, or promotional payouts.

POST/b2c/payment
Request Body
{
  "amount": 1200,
  "currency": "KES",
  "recipient_phone": "+254711223344",
  "remarks": "Salary Advance",
  "occasion": "Salary"
}
Response Example
{
  "status": "success",
  "conversation_id": "AG_2023_8989",
  "originator_conversation_id": "12345-67890",
  "response_desc": "Accept the service request successfully."
}

Business to Business (B2B)

Transfer funds securely between two business entities (Paybill to Paybill or Paybill to Till).

POST/b2b/transfer
Request Body
{
  "amount": 50000,
  "currency": "KES",
  "receiver_shortcode": "600000",
  "account_reference": "INVOICE_99",
  "remarks": "Supplier Payment"
}
Response Example
{
  "status": "success",
  "transaction_id": "LGH1234567",
  "message": "Funds transferred successfully"
}

Checkout Session

Create a hosted checkout session for web payments. This returns a URL you can redirect your user to.

POST/checkout/sessions
Request Body
{
  "amount": 2500,
  "currency": "KES",
  "cancel_url": "https://yoursite.com/cancel",
  "success_url": "https://yoursite.com/success",
  "customer_email": "customer@example.com"
}
Response Example
{
  "id": "sess_123...",
  "url": "https://checkout.vixzz.com/pay/sess_123..."
}

Account Validation

Verify if a phone number is a valid Vixzz user and retreive their registered name to prevent erroneous transfers.

GET/accounts/validate/{phone}
Response Example
{
  "valid": true,
  "account_name": "John Doe",
  "status": "Active"
}

Transaction Status

Poll the status of a pending transaction using the Request ID returned from the initiation endpoint.

GET/transactions/{id}/status
Response Example
{
  "status": "Completed",
  "result_code": 0,
  "result_desc": "The service request is processed successfully.",
  "amount": 500,
  "currency": "KES"
}

Verify Transaction

Verify a transaction callback or confirmation code locally on your server to prevent fraud.

POST/transactions/verify
Request Body
{
  "transaction_code": "LGH1234567"
}
Response Example
{
  "exists": true,
  "amount": 1000,
  "currency": "KES",
  "payer": "+254700000000",
  "timestamp": "2024-01-01 12:00:00"
}

Query Balance

Check your current business account balance. This returns both working account and utility float.

GET/accounts/balance
Response Example
{
  "working_account": {
    "currency": "KES",
    "value": 50000.00
  },
  "utility_account": {
    "currency": "KES",
    "value": 1500.00
  }
}