Webhooks & Additional Features
Webhook (Auto-Push) Biller Configuration
Vendors should provide a webhook (callback URL) that BillPay will use to notify the vendor of any changes to biller configurations (e.g. fees changed, biller enabled/disabled).
Contact Paynow support to register your webhook URL.
To protect your webhook against spoofing attacks, authenticate incoming requests using the "Bearer" scheme with basic authentication. Share your bearer token with the BillPay team for configuration.
BillPay will send a JSON POST request to your webhook with the list of biller codes whose configs have changed. You should then query the List Billers endpoint to retrieve the updated configurations.
If your webhook does not respond with 200 OK, BillPay will resend the request every 30 seconds, up to 3 attempts.
Example webhook request:
Header: Content-type: application/json
["CODE1", "CODE2"]
Auto Invoice Biller Payments
Some billers require (by law) the vendor to generate an invoice for each member payment. BillPay can do this automatically via CloudESD fiscal signature service.
Auto Invoice is asynchronous — it runs after a successful payment for a biller that requires vendor invoicing. BillPay assigns a VendorInvoiceReference, generates an invoice, and exports it to CloudESD to obtain a fiscal signature.
- VendorFiscalSignature — data to be displayed as a QR code on the invoice
- VendorFiscalMetadata — verification code, device ID, receipt counters, and device serial number (required on the customer's invoice)
Because this is asynchronous, send a Status inquiry for the payment to retrieve the VendorInvoiceReference, VendorFiscalSignature, and VendorFiscalMetadata.
Target Statistics
Billers (e.g. charities) may have a target amount set, either monetary or generic units.
GET https://billpay.paynow.co.zw/api/payment/TargetStats?billercode=<BillerCode>
With optional currency filter:
GET https://billpay.paynow.co.zw/api/payment/TargetStats?billercode=<BillerCode>¤cy=<CurrencyCode>
TargetStats Response
| Field | Data Type | Description |
|---|---|---|
| TargetAmount | Decimal | Total amount to achieve the target |
| TargetUnits | Integer | Quantity to purchase to achieve the target |
| TargetAchievedSinceDate | DateTime (nullable) | Date from which stats have been taken |
| TargetAchievedAmount | Decimal | Amount paid so far |
| TargetAchievedUnits | Integer | Units purchased so far |
| PayerCount | Integer | Number of payers |
If a biller is not configured for target statistics, BillPay will reply with a 200 OK response with an empty body.
Feed
Display a list of people who recently made payment to a biller. Useful for charities/fundraisers. The biller must have AllowFeed enabled.
GET https://billpay.paynow.co.zw/api/payment/feed?billercode=<BillerCode>
With optional currency filter:
GET https://billpay.paynow.co.zw/api/payment/feed?billercode=<BillerCode>¤cy=<CurrencyCode>
Returns the last 20 payments:
| Field | Data Type | Description |
|---|---|---|
| Date | DateTime | Date of payment |
| MemberNumber | String | Member identifier |
| Amount | Decimal | Amount paid |
| MetaData | List | Key-value pairs of product metadata |
Pagination
To get the next 20 (older) results, use the before query string parameter with the Unix time (milliseconds since Epoch) of the oldest record from the previous list:
GET https://billpay.paynow.co.zw/api/payment/feed?billercode=<BillerCode>&before=<unixLongDate>