Create Payout
Send funds directly to a recipient's 13-digit account starting with 38. All disbursements require developer RSA-2048 encrypted PIN authorization and an Idempotency-Key header to prevent double payouts.
POST/v1/b2c/payoutsLive & Sandbox
Request Headers
| Header | Type | Status | Description |
|---|---|---|---|
Authorization | string | Required | Bearer token with b2c.payout scope. |
Idempotency-Key | string | Required | Unique UUID to prevent duplicate disbursements during retries. |
Body Parameters (JSON)
| Parameter | Type | Status | Description |
|---|---|---|---|
recipientAccount | string | Required | 13-digit recipient account number starting with 38 (e.g. 3892018471920). |
amount | number | Required | Disbursement amount in local currency units. |
currency | string | Required | 3-letter ISO currency code (e.g. KES). |
encryptedPin | string | Required | Developer 4-digit business transaction PIN encrypted using Vixzz RSA-2048 public key. |
purpose | string | Optional | Disbursement classification (e.g. developer_payroll). |
Request Code Snippets (cURL, Node, Python, PHP, Go)
Request Example
curl -X POST https://developer.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 '{
"recipientAccount": "3892018471920",
"amount": 50000,
"currency": "KES",
"encryptedPin": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3f9...",
"purpose": "developer_payroll",
"callbackUrl": "https://example.com/v1/webhook"
}'JSON Return Response Body (200 OK)
Response
{
"id": "b2c_3n8x",
"transactionId": "TXN_B2C_99201841",
"status": "COMPLETED",
"recipientAccount": "3892018471920",
"recipientName": "Amina Mohamed",
"amount": 50000,
"currency": "KES",
"fee": 15,
"remainingWalletBalance": 434985,
"completedAt": "2026-09-07T02:30:00.142Z"
}