Skip to main content

Vendor API

The Vendor API is available for vendors to authorize, pay and query Paynow BillPay payments and requires an 'API' user credentials to access it.

Please contact Paynow support to have a user created for you.

Overview​

List Billers​

Lists all billers available on your account. Use this to update your application's biller/product database. The response includes products, artwork, meta descriptions, and supporting information for each biller.

Auth​

Different billers process payments differently. The Auth stage sends the product information and customer identifier to the biller. The auth response returns payment details for confirmation before paying.

Pay​

After a successful Auth, send a Pay request to complete the transaction. A successful result provisions the service/product to the customer (e.g. vouchers are returned in the response).

Webhook​

BillPay uses your webhook URL to notify your application of biller configuration changes. Use this with the List Billers endpoint to keep your application's database in sync.

Dual Currency​

The BillPay API supports dual currency biller payments: ZWG and USD.

If a biller offers products denominated in a currency other than ZWG or USD, the value will be converted to USD using an interbank exchange rate (provided by visa.com).

  • Vendors must have a prefunded ZWG wallet for products that do not require forex
  • Vendors must have a prefunded USD wallet for products that require forex
  • Products requiring forex have RequiresForexPayment set to true
  • The RequiresForexPayment flag must be set during Auth and Pay requests as an acknowledgement by the vendor

Authentication​

All API requests use HTTP basic authentication. Every HTTP request must have the Authorization header set.

The Authorization header is constructed as follows:

  1. Combine username and password with a colon: username:password
  2. Base64 encode the string: dXNlcm5hbWU6cGFzc3dvcmQ=
  3. Prepend the method: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
  4. Set the header: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example: For credentials Aladdin / OpenSesame:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

HTTP Response Codes​

200 (OK)​

A 200 response code is returned for successfully processed requests. This does NOT mean the result was successful. The Status field of the response should be inspected to determine the outcome.

  • TechnicalNarration — for technical troubleshooting, should not be shared with the customer
  • Narration — should be passed back to the customer as it may contain useful information

400 (Bad Request)​

A 400 response code is returned for requests that fail validation. The response body contains validation details:

{
  "Message": "The request is invalid.",
  "ModelState": {
    "request.MemberNumber": [
      "The member number is required"
    ],
    "request.Products": [
      "Product validation failed. There must be at least one product"
    ]
  }
}