Biller Integration Notes

Integration notes for non-standard billers or billers that require particular attention during integration.

Test Biller

This biller simulates various test responses, because many billers do not have reliable test environments.

note

All successful PAY responses from the Test Biller will contain ReceiptHtml and ReceiptSmses, which is not always the case for live billers. Check for existence before displaying or sending to the customer.

Member Number Test Cases

Any member number can be used during Auth and Pay. Prefixing the member number with the following will simulate the described response:

Prefix	Test Case	Description
AT	Auth Timeout	AUTH responds after 120 seconds. Recommended timeout: 60 seconds.
AF	Auth Failure	Simulates an invalid member number response from the biller
PT	Payment Timeout	PAY responds after 120 seconds. You must do a status inquiry.
PF	Payment Failure	PAY returns a Failed status with a permanent (non-retryable) error
PP	Payment Pending	PAY returns a BeingPaid status. You must continue status inquiries until a final status is determined. Transitions to Paid after 24 hours.
PFF	Payment Flagged	PAY returns a Flagged status. Follow-up status inquiries recommended as payment will eventually resolve to success or failure.
USD	Forex Required	Can be combined with other prefixes (e.g. PF-USD-1234). Only valid if the product indicates it sometimes requires forex.

Examples:

• 12345 — successful Auth response
• AT12345 — response after 120 seconds (timeout simulation)
• AF12345 — immediate auth failure

If the member number contains USD (and the product sometimes requires forex), then RequiresForexPayment will be set to TRUE. Otherwise FALSE.

Test Products

Code	Description
AI	Variable price, AUTH returns price, part payment permitted (e.g. council bill payment)
AM	Variable price, AUTH returns price, full payment required (e.g. medical aid policy)
AA	No fixed price, AUTH does not return price, customer chooses amount (e.g. airtime, ZETDC). Must respect MinPrice/MaxPrice.
RV	Fixed price, returns vouchers in PAY response. Quantity can be specified (e.g. ZETDC tokens).
FP	Fixed price, requires forex payment

Which Products for Which Billers

Test Product	Billers	Test
AI	Council billers (City of Harare, Bulawayo)	Show balance, let customer choose amount
AM	Nyaradzo	Show balance, require full payment
AA	Airtime, ZETDC	Ask customer how much to purchase
RV	TelOne, EVD	Display/send vouchers to customer
FP	Nurses Council, some universities	Show products with fixed prices

---

ZETDC Prepaid

Success

A successful payment response will contain:

• One or more ReceiptSMS entries if multiple tokens are returned
• One or more ReceiptHtml entries if multiple tokens are returned

warning

Vendors MUST send all SMS(es) to the customer individually and display/print all ReceiptHtml entries individually — not combined into one.

Pending/Timeout

During high load, the biller may timeout. BillPay will return a Pending response. Recommended web service timeout: 60 seconds.

Status inquiry intervals:

• 1st inquiry: no less than 120 seconds after timeout/pending
• Subsequent inquiries: no less than 180 seconds

Test Meter Numbers

note

Only available on the BillPay test environment.

Any valid meter number can be used. Special cases:

• Single debt: 37132567431
• Double debt: 37125980740
• Double token: 37132229735
• Token Resend: Use amount of $177.77 with any meter number

---

Paynow As A Billpay Biller (PaaBB)

For more information, please refer to the separate document which specifically addresses financial institution integrations.

---

Pink Lotto

Request

A user can make one or more bets in the same transaction. Numbers are submitted in the BetInfo metadata field.

1. Quantity must equal the count of bet sets (sets of 6 numbers)
2. BetInfo format: {setOf6}${setOf6}$ — each set is appended with $ (including the last)
3. Each set: {num};{num};{num};{num};{num};{num} — semicolon separated
4. Each number: two-digit format (01 through 45)

{
  "Products": [
    {
      "Code": "DRAW",
      "Metadata": [
        { "BetInfo": "01;02;03;04;05;06$35;19;16;06;03;11$35;19;16;06;03;11$" }
      ]
    }
  ]
}

RegData (optional) — for new Pink Lotto user registration:

{
  "Phone": "0733405542",
  "Password": "mypassword",
  "Name": "Sam",
  "Email": "sam@zimba.com",
  "Dob": "1990-09-10",
  "Question1": "Where is Harare?",
  "Question2": "Zimbabwe",
  "Answer1": "Where is Jo'burg",
  "Answer2": "SA"
}

Success

• One or more ReceiptSMS / ReceiptHtml entries for multiple bets/tickets
• DisplayData summarizes multiple tokens into one set of fields

Test Member Numbers

Registered mobile numbers: 0733405532 through 0733405536

---

Paynow EVD (Vouchers)

This biller does not have or require a "member number" — use the customer's mobile number instead.

• AUTH ensures vouchers are in stock and reserves them
• PAY issues the previously reserved vouchers

Stock Errors

Custom error messages are returned as JSON in the TechnicalNarration field:

Out of Stock:

{
  "Status": "OutOfStock",
  "OutOfStock": ["africom-50"],
  "InsufficientStock": null
}

Insufficient Stock:

{
  "Status": "InsufficientStock",
  "InsufficientStock": { "africom-50": 1 },
  "OutOfStock": null
}

Example AUTH Request

{
  "BillerCode": "EVD",
  "MemberNumber": "a@b.com",
  "Reference": "b56163df-69d3-48cc-8631-69ddff0fb3c1",
  "TotalAmount": "722",
  "Products": [
    {
      "Code": "telone-adsl-home-basic",
      "Quantity": "1",
      "Price": 722,
      "RequiresForexPayment": false
    }
  ],
  "Action": "AUTH"
}

Example PAY Response

{
  "Action": "Pay",
  "BillerCode": "EVD",
  "Reference": "b56163df-69d3-48cc-8631-69ddff0fb3c1",
  "MemberNumber": "a@b.com",
  "Products": [
    {
      "Quantity": 1,
      "Code": "telone-adsl-home-basic",
      "Name": "TelOne ADSL - Home Basic",
      "Price": 722,
      "RequiresForexPayment": false,
      "Vouchers": [
        {
          "SerialNumber": "50072200000066",
          "Batch": "5007220000",
          "VoucherCode": "4789000000000544",
          "ValidDays": 30,
          "ExpiryDate": "2022-07-31T00:00:00"
        }
      ]
    }
  ],
  "TotalAmount": 722,
  "Status": "Paid",
  "MemberName": "a@b.com",
  "BillerPaymentReference": "79d7a395-73c5-42ea-afc4-cc4afe9931b8",
  "BillPayReference": "EVD-220131100847476",
  "Currency": "ZWG",
  "WalletDebitReference": "D36",
  "WalletBalanceAfterDebit": -12422
}

---

Paynow Airtime

Any valid mobile number (Econet, NetOne, Telecel, or Africom) can be used as the "member number".

• AIRTIME — credits a ZWG monetary value to the subscriber's prepaid balance
• AIRTIME_USD — credits a USD monetary value (only Econet supported at time of writing)

Other products are mobile bundles. The applicable network is included in the product name.

---

Liquid Home - Pay As You Go

Liquid Home PAYG payments require a Service Login metadata field. The Service Login is not the same as the account ID (e.g. LIT-123456) — it is assigned by Liquid Home when a service is added to a customer's account.

Retrieving Service Logins

Query the Member Information API using the customer's LIT ID:

GET https://billpay.paynow.co.zw/api/payment/member?billerCode={billerCode}&memberNumber={litId}

The AccountDetails field from the response will contain:

• Account Currency (first entry)
• Service logins (following entries)

{
  "AuthData": {
    "MemberName": "John Doe",
    "AccountDetails": {
      "Account Currency": "ZWG",
      "test@test.com": "FIB_PAYG",
      "2631234567890": "LTE_PAYG",
      "2638677187782": "VOIP_NUMBER"
    }
  }
}

warning

A Liquid account denominated in USD can only purchase USD products. A ZWG account can purchase both USD and ZWG products.

Product codes are prefixed with currency and service (e.g. USD_FIB_PAYG_MEDIUM, USD_LTE_PAYG_30_100GB).

Example Payment Request

{
  "Products": [
    {
      "Code": "USD_FIB_PAYG_TEST",
      "Metadata": {
        "Service Login": "test@test.com"
      }
    }
  ]
}

Test Account Numbers

Any live account number works. Example with VOIP service: 84829 (Webdev)