Callback notifications

Back to APIs

Integrate with Paythru's callback notifications and benefit from real-time updates to your IT systems whenever your customers make payments.

Closing the loop

Paythru's agile approach to payment processing means that customers make payments in a diverse range of situations. For example, payments may be made by customers in a car park after parking their car, in a restaurant whilst dining out, responding to advertisements, SMS and email campaigns, or simply purchasing goods from your website or app.

Whilst Paythru offers a comprehensive web reporting suite to all its merchants – 'Insight', many merchants rely on Paythru's callback notifications to provide real-time updates to their own IT systems. The service may used to satisfy a wide variety of business requirements. As examples, a car park operator would need to establish if customers had paid for their parking ticket before they exited the car park, and a restaurant owner would need to ensure that customers had paid for their meals before leaving the restaurant. It would be too impractical in both examples for the businesses to perform manual checks using a web interface. Other merchants may choose to integrate with callback notifications to reduce the effort required to update their CRM system, fulfil their customers' orders or simply provide better customer service.

What exactly is a callback notification?

A callback notification is a message sent from Paythru's servers to your servers on the event of a customer attempting a payment. The message is delivered using the same protocol used to deliver web pages (HTTP) although it is sent from one server to another rather than from a web browser. Use of HTTP in this manner is often referred to as a 'web service'. Using HTTP ensures that Paythru's callback notifications are easy to integrate with since most organisations already have suitable web servers available to receive the notifications.

What data is sent?

Paythru provide as much data about the payment as possible. The data includes details of the customer, the items purchased as well as of details of the actual transaction. Callback notifications are sent following both approved and declined transactions. For card payments, some details of the payment card used are also provided including a 'token' that the merchant may use to conduct subsequent payments with the same card reducing their PCI compliance obligations.

The precise data sent within callback notifications differs by payment method used.

What format is the data sent in?

Paythru's callback notifications are sent using the HTTP POST request method. The content body of the request contains 'URL encoded' 'key-value' pairs of data. This form of URL encoding is often used within POST requests when data is submitted from a form on a website. Once decoded, the keys are used to differentiate each data item and its associated value.

How secure are callback notifications?

Callback notifications may be sent using TLS and SSL encryption standards (HTTPS) if necessary. This encryption ensures that the data cannot be intercepted or modified whilst in transit.

Paythru can provide upon request a list of IP addresses that the callback notifications may be sent from if it is important to validate the authenticity of the request's origin.

OK, so how do I integrate with callback notifications?

As with any systems integration, integrating Paythru's callback notifications will require some development effort to complete. Usually, this will require a script to be written and deployed to your web server(s). ASP, ASP.NET, Java, Perl, PHP and Python are all examples of scripting languages commonly used by web servers. The script would be written to process the data appropriately for individual requirements. For example the script may be written to perform tasks such as inserting the data into a CRM database, or sending a 'thank you' email to the customer, or triggering a request to a warehouse for order fulfilment.

The script must also acknowledge the receipt of the notification. This is achieved by the server returning an HTTP '200 OK' response (this is the standard response returned by web servers indicating the request was successful).

If you are using Paythru's Enterprise API, the address that the callback notification is sent to may be set uniquely for each request. If you would like callback notifications to be delivered for payments initiated without the API, as with SMS campaigns sent from Insight for example, please provide Paythru with your preferred 'Callback URL'.

Example Callback notification request

POST /path/to/script.php HTTP/1.1
Host: example.merchant.com
Content-Length: 154
Content-Type: application/x-www-form-urlencoded

addressPropertyName=Paythru+Ltd.&address1=Bell+Lane+Office+Village&address2=Bell+Lane&address3=0&addressTown=Amersham&addressCounty=Buckinghamshire&addressPostcode=HP6+6GL&addressCountry=UnitedKingdom&cardLastFour=1111&cardExpiryMonth=01&cardExpiryYear=15&items0Name=Test+item&items0Price=299&items0Quantity=1&items0Reference=12345678&personTitle=Mr&personFirstName=John&personSurname=Smith&personMobileNumber=07900123456&personHomePhone=&personEmail=&transactionKey=4573ee2851bbc1741dbca8988af4290b&transactionTime=2013-10-08T12%3A53%3A20%2B01%3A00&transactionStatus=Success&transactionValue=299.00&transactionType=Auth&transactionCurrency=GBP&transactionAuthCode=20200&transactionClass=&transactionReference=12345678&transactionToken=nx700Nfr&transactionMaid=&transactionIpAddress=178.78.109.82

Example Callback notification response

HTTP/1.1 200 OK
Content-Type: text/plain;charset=utf-8
Content-Length: 0