Skip to content Skip to footer
Sign In
Close

UTA API – Developer Specification

The API has been designed to enable a third party developer to integrate a payment gateway where
a user can use their UTA account to pay for a donation.


The overall user experience is shown below:

Technical Detail:

UTA will provide the charity with a and which are used to form the gateway url.

All campaigns use the same endpoint: https://app.utauk.org/api

A sample url is shown below:
 https://app.utauk.org/api?campaign=1086&transid=65874&cid =146&donation=18.00&hashed=e03c8b7f4d1c50872fa569b539f3339ccdf74f57fcdaf5c8f7fa45e583f4e299

This is formed as follows:

https://app.utauk.org/api Endpoint
campaign=1086 The given campaign ID
transid=65874 The unique transaction id of the sending system
cid=146 The user’s UTA account number
donation=18.00 The donation amount formatted to two decimal places, with no thousand separator
hashed=e03c8b7f4d1c50872fa569b539f3339ccdf74f57fcdaf5c8f7fa45e583f4e299 The hashed parameters

As part of the security mechanism, the hash is checked upon receipt to confirm it is valid and an error page is displayed if it is incorrect. The hash is created by use of hash_hmac function using the sha256 algorithm and the hash string provided to the charity.

Hence as an example, the hash in this case would be calculated by taking the parameter string of:

?campaign=1086&transid=65874&cid=146&donation=18.00

and the hash string of a1c38a07-aabc-4b60-b as follows:

hash_hmac(“sha256″,”
?campaign=5842&transid=567&cid=27&donation=18.00″,”a1c38a07-aabc-4b60-b”)

By sending the user to this url, they will be presented with the authentication screen similar to that
show in figure 1.

Figure 2 Invalid campaign id supplied
Figure 2 Invalid campaign id supplied
If an invalid campaign id is provided, an error screen will be displayed per figure 2
Figure 2 Invalid campaign id supplied
Figure 2 Invalid campaign id supplied
Similarly, if the client account is incorrect or the hash is incorrect, a further screen will be displayed per figure 3
Figure 3 Invalid client account or hash supplied
Figure 3 Invalid client account or hash supplied

There are three outcomes from the authentication screen:

1. The user enters their password correctly and clicks the Donate button to authenticate
2. The user clicks the Cancel button to cancel and return to the referring site
3. The user enters an incorrect password three times and is rejected



Each of the three routes will provide a return code to the referring site.

As part of the deployment process, the charity (or their developer) will supply to UTA a return url which they will be able to process and determine the return state.


The return url will be supplied with parameters and hashed in the same way as the gateway url.

This is formed as follows (using example details)

https://dsdev.com/ab/ipn Return url
campaign=1086 The given campaign ID
transid=65874 The unique transaction id of the sending system
cid=146 The user’s UTA account number
donation=18.00 The donation amount formatted to two decimal places, with no thousand separator
intid=1478 The UTA transaction id
rtncode The return code
hashed=e03c8b7f4d1c50872fa569b539f3339ccdf74f57fcdaf5c8f7fa45e583f4e299 The hashed parameters
Once again the hash_hmac function is used to produce the hash in the same way as above, hence in this case, it would be generated as below:

hash_hmac(“sha256″,”?campaign=1086&transid=65874&cid=146&donation=18.00&intid=25&rtncode=1″,”a1c38a07-aabc-4b60-b”)

The valid return codes which are to be processed by the receiving application are:

0 Transaction was successful
1 The user clicked the Cancel button
2 The user entered an incorrect password three times

It is the responsibility of the charity to ensure that upon receipt, the url is parsed, the hash calculated independently and verified against the hash provided and then then return code actioned as required.