PrintPay B2C API Integration
Automated B2C payouts, balance verification, status polling, and STK deposits.
Integration Overview
Integrate PrintPay Business-to-Customer (B2C) operations to manage live wallet balance checks, insufficient balance validation, instant wallet top-ups via M-Pesa STK Push with dynamic fee deductions, automated disbursement payouts, asynchronous status polling with complete success and failure reason logs, and real-time webhook callback notifications.
B2C Endpoint Checklist
| Operation | Method | Clean Endpoint URL | Purpose |
|---|---|---|---|
| Check Balance | POST | ... | Retrieve live B2C wallet balance |
| Top-Up Wallet | POST | ... | Deposit funds via M-Pesa STK Push |
| Check Top-Up Status | GET | ... | Poll live status of wallet top-up |
| Disbursement Payout | POST | ... | Send instant B2C payouts (validates balance) |
| Check Payout Status | POST | ... | Poll live status of processing disbursement |
| Result Webhook | POST | ... | Receive async payout confirmations |
1. Authentication Security Headers
All API requests to PrintPay endpoints require server-to-server authentication headers:
Your unique merchant wallet identifier from your dashboard sidebar.
Your secret API security credential generated in your B2C wallet settings.
2. Check B2C Wallet Balance
POST{
"status": "success",
"wallet_id": "WALLET_XYZ123",
"balance": 24500
}
{
"status": "error",
"message": "Invalid Wallet ID or Security Credential"
}
3. Wallet Top-Up (STK Push)
POST{
"status": "success",
"checkout_id": "ws_CO_221020261200000001",
"message": "STK push sent. Check your phone."
}
{
"status": "error",
"message": "Printpay gateway not configured."
}
4. Check Top-Up Status (Polling)
GET{
"status": "completed",
"success": true,
"failed": false,
"mpesa_receipt": "QWE123RTY4",
"message": "Wallet successfully credited",
"amount": 500
}
{
"status": "failed",
"success": false,
"failed": true,
"mpesa_receipt": "N/A",
"message": "The user cancelled the request.",
"amount": 500
}
5. B2C Payout / Disbursement
POST{
"status": "success",
"conversation_id": "Ag_20261023_...",
"message": "Disbursement initialized successfully!"
}
{
"status": "error",
"code": "insufficient_balance",
"message": "Required: KES 1,014, Available: KES 500."
}
6. Check Payout Status (Polling)
POST{
"status": "success",
"transaction_status": "COMPLETED",
"result_code": 0,
"result_desc": "The service request is processed successfully.",
"receipt": "QWE123RTY4"
}
{
"status": "success",
"transaction_status": "FAILED",
"result_code": 2001,
"result_desc": "The initiator information is invalid."
}
7. Result Webhook Callback
POSTConfigure this URL in your backend handler to receive asynchronous confirmation payloads when a disbursement completes or fails.