Go2Pay API > Introduction

Go2Pay is a payment system which allows you to take credit (and debit) card payments. It can be used to integrate a secure, compliant payment system into a web site, or to "order" payments which your customers can make later, from their PC or mobile device, or even over the phone or with a Chip+PIN terminal - see below.

You can then later go back and check the status of these payments.

Go2Pay is more secure than traditional web-based payment methods, because you send the initial payment "order" request via a secure, back-end channel, which generates a cryptographically random, tamper-proof hyperlink which the customer uses to make payment.

There are 3 "steps" in the process.

1) Add

You add a new order to the system, by calling our API, telling us the order reference and how much the payment is for. We send you back the payment link (which you pass to your customer, either by redirecting them immediately over the web, or by sending it to them e.g. via email or SMS) and an "ID" which you save alongside your reference. If you are a TonePay customer, you can also Add a "Call Centre" payment, which returns a 3-digit code which allows you to transfer the caller into an ATP process.

Call Add() in the API.

2) Pay

Your customer then pays the order, using the payment link.

3) Query

You use the "ID" we sent you earlier to query the status of the payment via our API - has the payment been authorised or declined? (NB You can only QUERY payment orders made by the same user which was used to ADD the order.)

Call Query() in the API.

Why Query?

Why do I need to "Query"? Why not just send back the result in the payment return, via a form post or query string?

This is a much more secure implementation - APIs that rely on the payment result being posted-back directly in the form or query string can be manipulated by the end-user to spoof the payment result.

Postbacks

For unattended payments - e.g. payments sent in an email, where the end-customer might pay any time within the next month - there is also the option for you to receive a postback to a URL configured on your side, once a successful payment has been made - if you are interested in this option, please contact us to discuss how this can be configured.

It is NOT recommended to use postbacks for "attended" payments, where a result is required immediately - it is better to poll directly, using the Query() functionality, under these circumstances.

Usage

The Http Services Interface is a REST-style API which can return data in either query-string, JSON or XML format.

Return Status

The payment status is an enum, defined in C# as:

public enum PaymentStatus
{
	Updating = -9999,
	Awaiting = -999,
	Verifying = -888,
	Pending = 0,
	Authorised = 1,
	Declined = -1,
	Error = 2,
	Cancelled = 3,
	Expiring = 7,
	Expired = 8,
	Abandoned = 9
}

Adding a Return URL

You can append a "Return URL" to a Go2Pay link which will direct the client back to your system once payment is complete, so that you can check the result (using the Query() method on the API) and respond accordingly.

For a "link" payment the Add() method will return a hyperlink in the "sms" return value:

https://go2pay.uk/?Qga6Zou6v3

To implement a "Return URL", just append an ampersand separator followed by the URL, so in principle:

https://go2pay.uk/?Qga6Zou6v3&http://my-site.com/pay/return.php?id=1234

NB - In practice, you will need to "URL Encode" the "Return URL", so the link will actually be:

https://go2pay.uk/?Qga6Zou6v3&http%3A%2F%2Fmy-site.com%2Fpay%2Freturn.php%3Fid%3D1234

In-App Payments

We have example applications for both iOS and Android - please contact us if you would like these!

Go2Pay can be used for "In-App" payments, allowing you take 3D Secure payments within your app.

The method described below uses Android object names, but the approach is the same for iPhone apps.

The method involves hosting the payment link in a custom Web View Client which overrides the URL loading process using shouldOverrideUrlLoading() meaning that we can intercept a specially crafted "return url" to know when the payment process has completed.

1. Call "Add" in the API to add a new payment.
2. Append the special return url to the "Go2Pay" link - e.g. "http://exit.to.app/".
3. Load the full link in the Web View Client.
4. In shouldOverrideUrlLoading() check for the special url, which will be called once the payment is complete.
5. If the special url is found, close the web view and use the "Query" method in the API to check the status of the payment.

Chip+PIN

If you have a "Cloud EPOS" Chip+PIN terminal from, you can create a Chip+PIN Payment Order, by calling Add() and passing "to" = "EPOS" in the parameters. This will return the Cloud Payment Reference which you enter into the terminal to proceed with the Chip+PIN payment.