Protocol Basics

The Billpay Service Interface is an HTTP based protocol. A detailed description of the supported operations and definitions can be found in the Specification section.


All communication shall be secured by establishing an SSL encrypted transport. Basic HTTP authentication shall be used to authenticate clients with the service, and is required for all requests.


The outcome of a request shall be determined by examining the HTTP status code of the response.

Status type

Three outcomes for a transaction are possible and can be classed as follows: successful, unknown, and failed. HTTP status codes fall under one of the possible outcomes as indicated below.

HTTP Status Codes Status type
200, 201, 202 successful
500, 504, timeout unknown
400, 501, 503, all others failed

A timeout occurs when the client has not received a response to a request after the agreed upon interval. Unless otherwise agreed, this interval shall be 60 seconds. Any response received after the timeout should be logged but otherwise ignored.


In addition to the HTTP status code, non-successful response bodies shall contain an ErrorDetail object, if possible, to describe the failure in more detail. It should be noted though, that responses in some failure scenarios will contain an empty response body, and therefore no ErrorDetail object will be present.


To ensure that loss of transactional data is minimized, it is required that clients store advice messages (see Transaction flows) in persistent storage and queue them until a final status type is received. A final response is one of either the successful or failed status types. If no response is received, or a response with an unknown status type is received, advice messages shall be queued and the message at the head of queue repeated on an interval until a final status type is received. For high throughput systems it shall be acceptable to send several advice messages in parallel, and as such, advices may be received out of order at the server.

The above applies to the following operations:

  • confirmPayment
  • reversePayment
  • confirmRefund
  • reverseRefund