Developer API Reference

Welcome to the Vixzz REST API documentation. Vixzz enables businesses to automate cross-border collections (C2B) and international disbursements (B2C) globally with direct local currency settlement rails.

BASE URL https://api.vixzz.com/v1

Key Features

Integration OAuth 2.0 Security

Standard bearer token model separating consumer-facing collections and payout operations.

Real-time Direct Settlement

Direct integration into mobile money rails and instant local bank transfers without delays.

Reliability Idempotent Payouts

Mandatory idempotency headers on disbursements protect against duplicate payments during network retries.

Safety Signed Webhooks

Verification keys allow validating asynchronous status updates before updating customer accounts.

Important: Store your API secret securely

Your API secret is a private production credential. Your team is responsible for protecting it inside your own infrastructure and for controlling which systems and people can access it.

  • Keep consumer secrets, business keys, and webhook secrets only on trusted backend servers or a managed secrets vault.
  • Never expose secrets in browser code, mobile apps, public repositories, screenshots, logs, support tickets, or client-side analytics tools.
  • Use environment variables with restricted access, rotate keys if exposure is suspected, and remove access for team members or services that no longer need it.
Quickstart Flow
1. Authenticate to request a Bearer token. 2. Submit a collection or payout payload. 3. Handle redirect URLs or wait for mobile prompt. 4. Listen to webhook events for status updates. 5. Query Transaction Status for verification.

Authentication

Vixzz APIs use OAuth 2.0 client credentials to issue short-lived Bearer tokens valid for 3600 seconds. Authentication credentials must be scoped correctly depending on the operation type:

C2B (Collect Money)

  • Prerequisite: C2B credentials
  • Requires: C2B Consumer Key
  • Requires: C2B Secret Key
  • Token Scope: c2b.collect

B2C (Send Money)

  • Prerequisite: B2C credentials
  • Requires: B2C Consumer Key
  • Requires: B2C Secret Key
  • Requires: X-Business-Key
  • Token Scope: b2c.payout
POST /v1/oauth2/token

Request Headers

Header Type Status Description
Authorization string Required Basic Base64 encoded credentials: Basic Base64(ConsumerKey:SecretKey). Ensure you encode the correct credential pair based on C2B or B2C operations.
Content-Type string Required Must be set exactly to: application/x-www-form-urlencoded.
X-Business-Key string Conditional Required for B2C payout tokens. Uniquely identifies the merchant business purse holding payout liquidity. Leave blank for C2B collections.

Body Parameters (Form URL-Encoded)

Parameter Type Status Description
grant_type string Required Must be set to exactly: client_credentials.

Response Fields (JSON)

Field Type Description
access_token string The issued temporary authorization token prefixed with vxz_tok_. Include this as Authorization: Bearer on subsequent API calls.
token_type string Identifies token authorization scheme. Always Bearer.
expires_in integer Remaining duration in seconds before token expires. Default is 3600 (1 hour).
scope string Authorized access scope. e.g. c2b.collect or b2c.payout.
C2B Token Request 
curl -X POST https://api.vixzz.com/v1/oauth2/token \
  -H "Authorization: Basic Base64(C2B_Consumer_Key:C2B_Secret_Key)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"
C2B Token Response (200 OK) 
{
  "access_token": "vxz_tok_c2b_8f9k3m9s2a1l",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "c2b.collect"
}
B2C Token Request 
curl -X POST https://api.vixzz.com/v1/oauth2/token \
  -H "Authorization: Basic Base64(B2C_Consumer_Key:B2C_Secret_Key)" \
  -H "X-Business-Key: bz_live_your_business_key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"
Auth Failure (401 Unauthorized) 
{
  "error": "invalid_client",
  "error_description": "Client credentials authentication failed. Double check your Consumer Key and Secret Key."
}

Create Payment (C2B)

Initiate incoming collections from customers. When calling this endpoint, Vixzz connects directly to local currency settlement operators (e.g. mobile money wallets or card networks) to debit the customer's wallet or launch a secure payment redirect page.

POST /v1/c2b/payments

Request Headers

Header Type Status Description
Authorization string Required Contains active C2B Bearer token: Bearer vxz_tok_c2b_...
Content-Type string Required Must be set to: application/json.

Body Parameters (JSON)

Parameter Type Status Description
amount integer Required The collection value in minor units of the target currency. For example, pass 15000 to request 150.00 KES.
currency string Required 3-letter ISO code specifying customer payment currency. (e.g., KES, UGX, TZS, GHS).
customer object Required A customer container object containing: name (string, Required) - Customer legal name. phone (string, Required) - Mobile money number starting with +. e.g. +254712345678. email (string, Optional) - Email address.
payment_channel string Required Preferred payment rail. Options: mobile_money, card, bank_transfer.
reference string Optional Your local order identification key (e.g. invoice ID) to correlate webhook events.
callback_url string Optional HTTPS endpoint on your server to receive immediate status update event payloads.

Response Fields (JSON)

Field Type Description
id string Unique transaction identifier returned by Vixzz, prefixed with c2b_. Save this to track payment progress.
amount integer Requested collection amount in minor units.
currency string Requested ISO currency code.
status string The state of the payment. Always initialized as pending. Wait for webhook or check status to verify transition to completed.
checkout_url string Secure checkout card payment redirect link. Defaults to null for mobile money push flows.
Create Payment Request 
curl -X POST https://api.vixzz.com/v1/c2b/payments \
  -H "Authorization: Bearer vxz_tok_c2b_8f9k3m9s2a1l" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "KES",
    "customer": {
      "name": "Jane Doe",
      "phone": "+254712345678",
      "email": "jane@example.com"
    },
    "payment_channel": "mobile_money",
    "reference": "invoice_94820",
    "callback_url": "https://api.yourcompany.com/v1/webhook"
  }'
Payment Response (201 Created) 
{
  "id": "c2b_7k9m",
  "amount": 15000,
  "currency": "KES",
  "status": "pending",
  "reference": "invoice_94820",
  "checkout_url": "https://checkout.vixzz.com/pay/c2b_7k9m",
  "created_at": "2026-06-02T12:00:00Z"
}
Validation Failure (400 Bad Request) 
{
  "error_code": "invalid_customer_phone",
  "message": "The customer phone number is invalid or not supported by mobile money provider.",
  "param": "customer.phone",
  "doc_url": "https://docs.vixzz.com/errors#invalid_customer_phone"
}

Refund Payment

Reverse a completed collection payment in full or in part. Reversals are routed back directly to the original sender's payment card or mobile money account details, subject to operator support and compliance policies.

POST /v1/transactions/{id}/refund

Path Parameters

Parameter Type Status Description
id string Required The unique transaction identifier (prefixed with c2b_) of the completed collection you want to refund.

Body Parameters (JSON)

Parameter Type Status Description
amount integer Optional Specific partial refund amount in minor units. If omitted, Vixzz processes a full reversal of the original collection amount.
reason string Optional Internal audit descriptor tag. e.g. customer_cancellation, fraudulent_transaction, item_out_of_stock.

Response Fields (JSON)

Field Type Description
refund_id string The unique reversal record key returned by Vixzz, prefixed with ref_.
original_transaction_id string The targeted collection transaction ID (c2b_...).
amount integer The processed refund amount in minor units.
status string State of the reversal. Success returns refunded.
Refund Request 
curl -X POST https://api.vixzz.com/v1/transactions/c2b_7k9m/refund \
  -H "Authorization: Bearer vxz_tok_c2b_8f9k3m9s2a1l" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "reason": "customer_cancellation"
  }'
Refund Response (200 OK) 
{
  "refund_id": "ref_9m4z",
  "original_transaction_id": "c2b_7k9m",
  "amount": 15000,
  "status": "refunded",
  "created_at": "2026-06-02T12:15:30Z"
}
Refund Failure (422 Unprocessable) 
{
  "error_code": "transaction_not_refundable",
  "message": "The transaction 'c2b_7k9m' has already been refunded or is not in a COMPLETED state.",
  "param": "id",
  "doc_url": "https://docs.vixzz.com/errors#transaction_not_refundable"
}

Create Payout (B2C)

Disburse payouts to bank accounts and mobile wallets in their local currencies. Disbursements process in real-time, routing local currency conversion directly to the recipient. To prevent accidental double payouts during network dropouts, Vixzz enforces the use of an Idempotency-Key header.

POST /v1/b2c/payouts

Request Headers

Header Type Status Description
Authorization string Required Contains active B2C Bearer token: Bearer vxz_tok_b2c_...
Idempotency-Key string Required Unique request identifier token generated in your server (e.g. UUIDv4). Resending the same payload with the identical key will safely return the existing transaction record rather than executing a new payout.
Content-Type string Required Must be set to: application/json.

Body Parameters (JSON)

Parameter Type Status Description
amount integer Required Payout value represented in the minor unit of the target recipient currency. e.g. send 50000 to disburse NGN 500.00.
currency string Required 3-letter ISO code of recipient target currency. (e.g. NGN, KES, GHS).
recipient object Required Beneficiary destination information details: name (string, Required) - Recipient legal name. account_number (string, Required) - Recipient bank account or mobile money phone number. bank_code (string, Conditional) - Routing identifier code. Required for bank account transfers. (e.g. 044 for Access Bank Nigeria).
payout_method string Required Target delivery rail. Options: bank_account, mobile_wallet.
purpose string Required KYC reason descriptor for compliance. e.g. developer_payroll, vendor_payment, salary_disbursement, refund.
callback_url string Optional HTTPS URL on your server to receive immediate status update event payloads.

Response Fields (JSON)

Field Type Description
id string Unique payout transaction ID generated by Vixzz, prefixed with b2c_.
amount integer Disbursed amount in minor units.
currency string Recipient target currency code.
status string Status of payout delivery. Initial requests return initiated while processing in local settlement systems.
recipient object Masked beneficiary validation confirmation details.
Create Payout Request 
curl -X POST https://api.vixzz.com/v1/b2c/payouts \
  -H "Authorization: Bearer vxz_tok_b2c_0a5l1n3m8x2z" \
  -H "Idempotency-Key: b2c_payout_order_5819" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "NGN",
    "recipient": {
      "name": "Chinedu Okafor",
      "account_number": "0123456789",
      "bank_code": "044"
    },
    "payout_method": "bank_account",
    "purpose": "developer_payroll",
    "callback_url": "https://api.yourcompany.com/v1/webhook"
  }'
Payout Response (202 Accepted) 
{
  "id": "b2c_3n8x",
  "amount": 50000,
  "currency": "NGN",
  "status": "initiated",
  "recipient": {
    "name": "Chinedu Okafor",
    "account_number": "xxxxxx6789"
  },
  "created_at": "2026-06-02T12:05:12Z"
}
Insufficient Funds (402 Payment Required) 
{
  "error_code": "insufficient_funds",
  "message": "Your business wallet balance is below the requested payout amount plus the 1% payout fee.",
  "param": "amount",
  "doc_url": "https://docs.vixzz.com/errors#insufficient_funds"
}

Check Status

Query the real-time processing state of any transaction. This endpoint provides instant verification of final settlement status, transaction timestamps, and local provider references.

GET /v1/transactions/{id}

Path Parameters

Parameter Type Status Description
id string Required The unique transaction ID (prefixed with c2b_ or b2c_) of the record you want to look up.

Response Fields (JSON)

Field Type Description
id string Unique transaction record key.
type string Categorizes transaction. e.g. c2b (incoming) or b2c (outgoing).
amount integer Original request value in minor units.
currency string ISO currency code.
status string Current processing state. e.g. pending, initiated, completed, failed, refunded.
payout_reference string The local delivery receipt identifier returned by mobile networks or local banks. Use this for reconciliation.
created_at timestamp ISO 8601 creation timestamp.
completed_at timestamp ISO 8601 completion timestamp when transaction successfully settles. Defaults to null for pending items.
Query Status Request 
curl -X GET https://api.vixzz.com/v1/transactions/b2c_3n8x \
  -H "Authorization: Bearer vxz_tok_b2c_0a5l1n3m8x2z"
Status Response (200 OK) 
{
  "id": "b2c_3n8x",
  "type": "b2c",
  "amount": 50000,
  "currency": "NGN",
  "status": "completed",
  "payout_reference": "NIP-9482018",
  "created_at": "2026-06-02T12:05:12Z",
  "completed_at": "2026-06-02T12:06:05Z"
}
Query Failure (404 Not Found) 
{
  "error_code": "transaction_not_found",
  "message": "No transaction found matching the ID 'b2c_3n8x_invalid'.",
  "param": "id",
  "doc_url": "https://docs.vixzz.com/errors#transaction_not_found"
}

Webhooks

Webhooks allow your application to handle status updates asynchronously. Vixzz automatically triggers a POST request containing an event object payload to your configured callback_url when transaction states change.

POST callback_url

Event Types

Event Type Trigger Condition
c2b.payment_completed Customer has authorized the push prompt and funds have cleared.
c2b.payment_failed Customer rejected the prompt, inputted wrong PIN, or request timed out.
b2c.payout_completed Funds successfully settled inside recipient's bank account or wallet.
b2c.payout_failed Payout rejected by recipient's operator or blocked by verification rules.
refund.processed Reversal transaction completed and funds returned to the customer.

Signature Verification

To prevent spoofing attacks, every webhook payload is signed with a secret hash. Vixzz includes a Vixzz-Signature header with every request. You should compute a HMAC-SHA256 signature of the raw request body using your webhook secret key and ensure it matches the header before updating any internal database records.

Webhook Payload Event JSON 
{
  "type": "b2c.payout_completed",
  "id": "evt_f2v9",
  "created_at": "2026-06-02T12:06:10Z",
  "data": {
    "transaction_id": "b2c_3n8x",
    "status": "completed",
    "payout_reference": "NIP-9482018"
  }
}

API Errors

Vixzz uses standard HTTP response codes to indicate request success or failure. Errors return a JSON payload containing an error code, message, and parameter details to help debug integration issues.

HTTP Status Code Reference

Status Error Code Typical Cause
400 Bad Request invalid_customer_phone Customer phone number is malformed or invalid.
401 Unauthorized invalid_client API token is missing, expired, or credentials are wrong.
402 Payment Required insufficient_funds Business purse balance is insufficient to process payouts.
404 Not Found transaction_not_found The requested transaction ID does not match records.
422 Unprocessable transaction_not_refundable Reversal request fails because item is not completed.
202 Accepted review_required Payout accepted but flagged for compliance review.
Standard Error Response JSON 
{
  "error": "invalid_client",
  "error_description": "Client credentials authentication failed. Double check your Consumer Key and Secret Key."
}

Sandbox Testing

Test your integrations inside our sandbox environment before taking your product live. The sandbox uses separate API keys, allows simulating various success/failure triggers, and will never move real money.

SANDBOX BASE URL https://sandbox.api.vixzz.com/v1
Test Credentials

Request separate sandbox keys from your developer portal dashboard settings tab.

Simulated Triggers

Use designated test amounts or customer numbers to trigger specific failure states and error responses.

Full Callback Rails

Webhooks are fully operational inside sandbox. Configure callback URLs to receive immediate simulated event payloads.

Safety

No transactions affect live mobile wallets or bank credit lines. Safely verify client setups and loops.

Get Sandbox Keys Review Wallet Liquidity
Sandbox Environment Guide
Base URL: https://sandbox.api.vixzz.com/v1 To test authorization failure: Provide invalid Consumer Secret. To test insufficient funds: Trigger payout amount >= 1,000,000 minor units. To test card redirect: Submit collection with payment_channel: card.