Initiate C2B Payment
Initiates an incoming payment challenge across Paybill, Merchant, or hosted checkout by specifying the collection type in the request body. Dispatches a 6-digit OTP code directly to the user's 13-digit account starting with 38.
POST/v1/c2b/paymentsLive & Sandbox
Request Headers
| Header | Type | Status | Description |
|---|---|---|---|
Authorization | string | Required | Bearer vxz_tok_* (OAuth 2.0 Scoped Bearer Token) |
Content-Type | string | Required | application/json |
Idempotency-Key | string | Recommended | Unique key for this operation, 8–80 characters. Send it to make retries safe: repeating the same key returns the original result instead of performing the operation twice. Without it the API derives a key from the request body and replays the original result for a few minutes, so an accidental double submit is still ignored. |
Body Parameters (JSON)
| Parameter | Type | Status | Description |
|---|---|---|---|
type | string | Required | Payment channel type: paybill, merchant, or checkout. |
businessCode | string | Required | Your registered Paybill number or Merchant code (e.g. 882190). |
accountNumber | string | Required | 13-digit customer account number starting with 38 (e.g. 3810482910482). |
amount | number | Required | Payment value in local currency (e.g. 2500.00 KES). |
currency | string | Required | 3-letter ISO code: KES, USD. |
reference | string | Required | Merchant invoice, bill, or order reference (e.g. INV-98124). |
description | string | Optional | Short statement description displayed to customer. |
callbackUrl | string | Optional | HTTPS webhook URL to receive real-time settlement callbacks. |
Request Code Snippets (cURL, Node, Python, PHP, Go)
Request Example
curl -X POST https://developer.vixzz.com/v1/c2b/payments \
-H "Authorization: Bearer vxz_tok_c2b_8f9k3m9s2a1l" \
-H "Content-Type: application/json" \
-d '{
"type": "paybill",
"businessCode": "882190",
"accountNumber": "3810482910482",
"amount": 2500,
"currency": "KES",
"reference": "INV-98124",
"description": "Store Checkout Payment",
"callbackUrl": "https://example.com/vixzz/callback"
}'JSON Return Response Body (200 OK)
Response (Challenge Dispatched)
{
"success": true,
"transactionId": "TXN_C2B_84920199",
"challengeId": "OTP_CHG_94820194",
"status": "PENDING_OTP_AUTHORIZATION",
"type": "paybill",
"accountNumber": "3810482910482",
"amount": 2500,
"currency": "KES",
"otpExpiresIn": 300,
"message": "6-digit authorization OTP dispatched to user account 3810482910482",
"timestamp": "2026-09-07T02:30:00.158Z"
}