Skip to content

App Implementation

Version: 3

1.0 Introduction

Paythru's API's are currently designed to be used during web-based user journeys, but it is possible to make them work for in-app use. This documentation aims to provide an overview of the interactions required to make this work.

This document assumes that you would use the Client POST API to collect cards from customers, the Gateway API to process the transactions and the Tokenisation API to store cards for future use.

This integration method relies on server-to-server calls for carrying sensitive credentials. You will require a mechanism to authenticate genuine requests from your app to you own server, this is outside of the scope for this document.

2.0 Integration overview

2.1 Integration breakdown

At the point you need to collect payment card information from a consumer, take the following actions:

  1. Your app first makes a call to your own server, via an appropriate authentication mechanism. The authentication mechanism used between your app and your server is outside of the scope of this document, but the authentication provided by our payment API's is not suitable for use directly from a mobile application.
  2. You server, having authenticated the call from the app, calls the Client POST API /v3/session/initiate method to get back a sessionKey, which it provides back to the app.
  3. The app presents a payment form to the customer and submits the results directly to the Client POST API /v3/session/postform method using the sessionKey obtained via the call to your server. By sending the card data directly your app is processing cardholder data and would need to be compliant with (at least) requirement 6 of the PCI standards, but your server will not be processing, storing or transmitting cardholder data and so could remain out of scope for PCI or SAQ A eligible.
  4. The Client POST API /v3/session/postform/ajaxpost method will respond with a Location http header to issue a redirect command. Your app must intercept this redirect, inspect the Location header and check the value within. It will either be the errorPageUrl from your Client POST API /v3/session/initiate call or one of the nextPageUrl/currentPageUrl values from your Client POST API /v3/session/postform call in the previous step. Use this to route your logic to an error message or onto the next step.
    • The postform method responds with encrypted information in the querystring of the Location http header (the data parameter). This information will need to be decrypted on your own server to establish whether the postform submission was accepted successfully or whether there were errors. See "Handling Post Form Response" on the Client POST API for more detail.
  5. If the redirect takes you to the value supplied as your currentPageUrl then the payment card details were successfully stored in the session, you can now issue a server-to-server call to the appropriate Gateway API method (/v3/transaction/authSessionKey, /v3/transaction/preauthSessionKey, /v3/transaction/verifySessionKey or /v3/transaction/initiate3DSecureSessionKey) to process a payment.
  6. If you also want to tokenise the card for future re-use you can call the Tokenisation API /v3/token/tokeniseTransactionKey method with the transactionKey value.
Back to top