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 URLhttps://api.vixzz.com/v1

Key Features

IntegrationOAuth 2.0 Security

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

Real-timeDirect Settlement

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

ReliabilityIdempotent Payouts

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

SafetySigned 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

Authenticate to request a Bearer token.
Submit a collection or payout payload.
Handle redirect URLs or wait for mobile prompt.
Listen to webhook events for status updates.
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 <token>` 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.

POSTcallback_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 URLhttps://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 Business Console

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.