Collection result postback

If you are integrated with our APIs, you can opt to sign up for our result postback service. This will ensure you get transaction results sent to you the moment we process them. In web development, a postback is an HTTP POST from a client to a server in response to an original server message to the client. In this case, we play the role of client sending your server results as they become available.

Like a webhook or callback, this web service allows our server to post to yours on events. It is a fire-and-forget message, with no automated retry attempts. If you need us to resend missed results we can provide them or investigate why they might be missing.

In order to consume this service, you will need to host an endpoint that supports JSON and expects the payload that we will deliver. We can support various authentication approaches, but please do let us know about your endpoint well in advance through an encrypted email so we will know what form it takes and what our credentials are for Sandbox and Production environments.

We will also provide you with a few of our IP addresses that you may need to whitelist on your server to receive our communications. As part of setting us this service, you should also schedule an SIT slot with us to confirm the proper connectivity of the service in Sandbox and Production environments. Ideally connectivity testing should be done as soon as possible.

In order to use this service your end point must at minimum:

  • be reachable at port 443 (HTTPS)

  • respond within 5 seconds

  • respond with a 2XX status code

  • handle for duplicate post backs for the same event

It is critical you prevent duplicates from the post back service from being processed. From time to time, these may occur as result files are re-transmitted from the bank or due to any number of other operational reasons.

A sample of our postback payload is presented below:

{
"Type": "CollectionResults",
"Value":
[
{
"CollectionIdentification": string,
"MandateIdentification": string,
"ContractReference": string,
"CollectionReference": string,
"DebtorAccountNumber": string,
"DebtorBranchCode": string,
"CollectionAmount": string,
"ActionDate": dateTime,
"RequestedActionDate": dateTime,
"ForDate": dateTime,
"ResultCode": string,
"ResultDate": dateTime,
"ResultDescription": string,
"ResultType": string,
"ShortName": string,
"CollectionInstrument": string
}
]
}

Pro tip: if you need to quickly generate a URL you can do this using RequestBin or Mockbin.