Payment Response

The response from BillPay includes all the fields from the payment request plus the following additional fields.

Payment Response Fields

Field	Data Type	Description
Status	String	See Statuses below
MemberName	String	The member name
Products	List<ProductResponse>	Products in the response
Narration	String	Populated for a Failed status
TechnicalNarration	String	Technical error description (if any)
BillPayReference	String	Unique reference generated by BillPay
AuthData	AuthResponseData	Auth response data
PaymentData	PaymentResponseData	Payment data after completion
BillerPaymentReference	String	Biller's payment reference (after payment)
VendorServiceFeeCurrency	String	3-character ISO currency code for service fee
VendorServiceFee	Decimal (nullable)	Service fee charged to the vendor
Currency	String	Currency of vendor wallet debited
WalletDebitReference	String	Vendor's wallet debit reference
WalletBalanceAfterDebit	Decimal (nullable)	Wallet balance after debit
WalletDebitReversed	DateTime (nullable)	Date/time of reversal, or null
WalletBalanceAfterReversal	Decimal (nullable)	Wallet balance after reversal
VendorInvoiceReference	String	Invoice reference (if auto invoice enabled)
VendorFiscalSignature	String	Invoice fiscal signature (if auto invoice enabled)
VendorFiscalMetadata	String	Invoice fiscal metadata (if auto invoice enabled)
VendorReversalReference	String	Unique reversal reference (if reversed/refunded)

Product Response

Field	Data Type	Description
Name	String	Product name
Code	String	Product code
Quantity	Integer	Quantity of product
Department	String	Product department (if specified)
Price	Decimal	Product price (observe if AUTH returns price)
AccountBalance	Decimal (nullable)	Product account balance if available
RequiresForexPayment	Boolean	Whether forex payment is required
Vouchers	Array of ProductVoucherData	Vouchers if the product has any
Metadata	Array of Key/Value Pairs	Any metadata submitted
VendorCommission	Decimal (nullable)	Commission earned by vendor (in payment currency)

AuthResponseData

Field	Data Type	Description
MemberName	String	The name of the member
MemberAddress	String	The address of the member
AccountDetails	Dictionary<string, string>	Key-value pairs of account details
AccountBalances	Dictionary<string, string>	Key-value pairs of non-monetary balances
AccountBalance	Decimal (nullable)	Monetary account balance if any

AccountDetails example:

{
  "National Id": "AB-CDEF123",
  "Place of Birth": "Harare"
}

AccountBalances example:

{
  "Data": "1.75GB",
  "Days": "12"
}

PaymentResponseData

Field	Data Type	Description
ReceiptHtml	String array	Formatted receipt HTML (may include images with fully qualified URLs). May contain multiple entries (e.g. ZETDC prepaid). If populated, the vendor must share each entry individually.
DisplayData	Dictionary<string, string>	Fields to show the customer after payment (e.g. in email, summary page)
ReceiptSmses	String array	SMS text to send to customer. May contain multiple entries. If populated, the vendor MUST send each SMS individually.

ProductVoucherData

Field	Data Type	Description
SerialNumber	String	Serial number of the voucher
Pin	String	Voucher pin
ValidDays	Integer (nullable)	Number of days the voucher is valid
Batch	String	Voucher batch
VoucherCode	String	Token/pin/code the user must enter to activate the service
ExpiryDate	DateTime (nullable)	Expiry date of the voucher

Sample Auth Response

{
  "Action": "Auth",
  "BillerCode": "COB",
  "Reference": "08be48c6-2624-4a06-95eb-be79ff5d6ef5",
  "MemberNumber": "ABC123",
  "Products": [
    {
      "Quantity": 1,
      "Code": "USD",
      "Name": "USD Bill Payment",
      "Price": 100,
      "RequiresForexPayment": true
    }
  ],
  "TotalAmount": 100,
  "Status": "Authorized",
  "MemberName": "Bulawayo Guy",
  "BillPayReference": "COB-211129114124239",
  "AuthData": {
    "MemberName": "Bulawayo Guy",
    "AccountDetails": {
      "Favourite Burger": "Macdonalds"
    }
  }
}

Sample Pay Response

{
  "Action": "Pay",
  "BillerCode": "COB",
  "Reference": "08be48c6-2624-4a06-95eb-be79ff5d6ef5",
  "MemberNumber": "ABC123",
  "Products": [
    {
      "Quantity": 1,
      "Code": "USD",
      "Name": "USD Bill Payment",
      "Price": 100,
      "RequiresForexPayment": true
    }
  ],
  "TotalAmount": 100,
  "Status": "Paid",
  "MemberName": "Bulawayo Guy",
  "BillerPaymentReference": "0740000022",
  "BillPayReference": "COB-211129114124239",
  "AuthData": {
    "MemberName": "Bulawayo Guy",
    "AccountDetails": {
      "Favourite Burger": "Macdonalds"
    }
  },
  "Currency": "USD"
}

Statuses

Status	Description
Authorized	Payment has been successfully authorized and can now be paid
BeingProcessed	Payment is still being processed. Check status at 180 second intervals
Paid	Payment is successful
Reversed	Payment has been reversed/refunded
Failed	Payment has failed
Flagged	Unexpected result from the biller, flagged for BillPay support. Check status at 600 second intervals