The TonePay Standard Interface is the interface that integrates your back-end systems into our TonePay system. Most of the magic happens at our end, but there are a couple of things your developers need to do.
(1) Lookups
In order to process a payment, we need to know one key piece of information - how much the end-client needs to pay. So the TonePay Standard Interface allows TonePay to query your system (via a web service) to determine the end-client's outstanding balance.
(2) Postbacks
Once the payment is complete, you want to know about it; so we use the TonePay Standard Interface to post back the result of a successful transaction into your system. (See below for how you can use a pre-shared key to increase the security of this process.)
The TonePay Standard Interface is designed to be simple and straightforward for you to implement, using a basic HTTPS GET/ POST and a simple XML Responses. It can be easily and quickly implemented at your end in almost any language - .NET, Java, PHP, etc. etc.
The TonePay Standard Interface can (and should) be secured via HTTPS; and access limited by IP Address and an authentication token - e.g. a user name and password combination.
(1) Lookups
A Lookup allows the caller (your client) to enter a numeric reference (or references) via the telephone keypad, which we use to call a service on your site to determine the balance owed. As well as passing in the numeric reference, you can supply us with an authentication token (e.g. user name and password combination) which we use to access to the service.
Example Get
https://example.com/services/lookup_balance.php?id=123456
Example Response
˂result status="OK"˃
˂id˃123456˂/id˃
˂balance˃2500˂/balance˃
˂/result˃
If the "status" attribute is anything other than "OK" we will assume that this status is an ERROR - so your interface might return:
˂result status="Account '123456' Not Found" /˃
If the result is successful, we will parse this response into a series of name-value variable pairs which we can use during the payment / postback process. The variable names don't matter, but...
NB: THE BALANCE AMOUNT IS NORMALLY EXPRESSED IN PENNIES!
(This means that if the balance is £25.00, you would return this as "2500", as shown above!)
(2) Postbacks
A Postback allows us to inform you of the result of a successful payment. We can also pass back the ids or references which you passed us in the Lookup phase earlier. (Note that only successful payments are posted.) The Postback process will look for a standard response (see below) and will retry 10 times, at 30 minute intervals, if this response is not received.
Example Post
https://example.com/services/postback.php?id=123456&amount=2500&ref=MP987654
Note again that the amount is expressed in PENNIES!
We can post back an alphanumeric Payment Reference ("ref" in the example above, but the name can be configured) which can be used to identify the payment uniquely within our system. It is very important that you keep a record of this ID alongside the payment, as it will allow us to track the transaction if there are any problems or queries. Please allow for a payment reference of up to 20 characters.
If possible you should use Payment Reference as a unique key, and in the event of a duplicate posting still return an "OK" status to us - this ensures that if (for some reason) we don't register the success status the first time, we will on the second attempt.
Standard Response
˂result status="OK"˃˂/result˃