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

HeaderTypeStatusDescription
AuthorizationstringRequiredBearer token with b2c.payout scope.
Idempotency-KeystringRequiredUnique UUID to prevent duplicate disbursements during retries.

Body Parameters (JSON)

ParameterTypeStatusDescription
recipientAccountstringRequired13-digit recipient account number starting with 38 (e.g. 3892018471920).
amountnumberRequiredDisbursement amount in local currency units.
currencystringRequired3-letter ISO currency code (e.g. KES).
encryptedPinstringRequiredDeveloper 4-digit business transaction PIN encrypted using Vixzz RSA-2048 public key.
purposestringOptionalDisbursement 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"
}