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

HeaderTypeStatusDescription
AuthorizationstringRequiredBearer vxz_tok_* (OAuth 2.0 Scoped Bearer Token)
Content-TypestringRequiredapplication/json
Idempotency-KeystringRecommendedUnique 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)

ParameterTypeStatusDescription
typestringRequiredPayment channel type: paybill, merchant, or checkout.
businessCodestringRequiredYour registered Paybill number or Merchant code (e.g. 882190).
accountNumberstringRequired13-digit customer account number starting with 38 (e.g. 3810482910482).
amountnumberRequiredPayment value in local currency (e.g. 2500.00 KES).
currencystringRequired3-letter ISO code: KES, USD.
referencestringRequiredMerchant invoice, bill, or order reference (e.g. INV-98124).
descriptionstringOptionalShort statement description displayed to customer.
callbackUrlstringOptionalHTTPS 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"
}