Client POST API

Version 3

Back to Developers

Client POST API

Version 3

1.0 Introduction

Paythru is a service provider offering a range of services to merchants enabling them to accept payments for goods and services within websites and mobile applications. The range of services includes a variety of different payment types as well as number of APIs offering the merchant a choice of integration options.

The integration options include both 'direct' methods where Paythru simply process payment details captured and submitted by the merchant as well as 'hosted' methods where Paythru host the customer facing interface and process the details provided by the customer.

This API enables merchants to host their own card payment interfaces in online environments whilst also minimising their PCI DSS Compliance obligations. The card entry form hosted by the merchant is configured to post the customer's card details to Paythru. Paythru then redirect the customer to a URL on the merchant's servers so the entire checkout experience is hosted by the merchant.

The API also offers the means to submit payment card details for tokenisation as well as for payment.

1.1 Scope

This document describes the web services available to merchants wishing to conduct payments on behalf of their customers.

1.2 Audience

This document is aimed largely at developers tasked with integrating with Paythru on behalf of a merchant. This document is technical in nature and only offers a high level view of Paythru's business processes. Readers who are to implement the API should have a good understanding of HTTP, XML, as well as a server-side scripting language capable of performing requests to the API e.g. ASP.NET, PHP or Java. It is also assumed that readers of this document have already created an account with Paythru, and Paythru have configured their account to accept the requests on behalf of the merchant.


2.0 API Overview

2.1 Introduction

This API is specifically designed for merchants wishing to maintain control of the 'look and feel' of their card payment web interfaces by hosting the pages themselves. It is also intended for merchants wishing to minimise their PCI DSS compliance obligations by not storing or transmitting cardholder data.

Paythru offer an alternative integration approach to merchants who prefer to simply redirect their customers to an externally hosted payment interface. Paythru also provide direct processing methods to whom card storage and transmission is not an issue.

Merchants using this API are required to develop the user interface themselves and host it on their own servers. When the customer submits the card entry form however, the card data is sent to Paythru rather than to the merchant ensuring the merchant is not directly exposed to the card data. Paythru process the card data, and then redirect the customer to a URL on the merchant's servers offering the merchant complete control of the entire payment experience.

If desired, the merchant may request that the card data submitted by the customer is to be temporarily stored by Paythru, and not processed immediately, allowing the merchant to present an intermediate review page to the customer before they commit to the purchase.

The data submitted by the customer is validated by Paythru. If any of the data fails validation (for example, if the card expiry date is in the past), the customer will be returned to the card entry form where they may make appropriate changes before resubmitting the form.

Whenever a card form is submitted, Paythru provide a 'masked' version of the data back to the merchant for repopulation in the form, or for presenting to the customer to review. Since this data is sufficiently masked, it will not breach the merchant's PCI DSS compliance.

Please note that this API is used only to send data from the customer to Paythru. Actions performed using the provided data such as payment processing and card tokenisation will require use either Paythru's Gateway API or Card Tokenisation API as appropriate.

Merchants wishing to use this API within a website must have a valid SSL certificate and use the SSL certificate for all their checkout pages.

2.2 API Requests

The Paythru Gateway API accepts HTTP POST method requests over an SSL connection (HTTPS). The key-value parameters sent in body of the request must be encoded using the application/form-url-encoded Internet media type.

The API is used in two stages. A 'session' must first be initiated in a request from the merchant's servers. Once the session has been initiated, requests may be submitted from the customer's browser that include the session key returned in the session initiation request.

The data returned in the response to the initiate method request can be encoded in a choice of either XML or JSON encoding. The response to the post form method request will usually be an HTTP 303 (See Other) response code instructing the browser to redirect the customer to the appropriate URL on the merchant's servers.

2.3 Request URL

Requests to this API should be sent to a URL constructed in the following manner:

https://ws.paythru.com/v{version number}/session/{method name}/{response encoding}

The {version number} segment within the URL should be replaced with the version of the API. The current version of the API is 3.

The {method name} segment within the URL should be replaced with the method of the API being requested.

The last segment of the URL - {response encoding} indicates whether the response from the web service should be encoded in XML or JSON.

Example URL

For example, a request to the initiate payment session method of version 3 of the API with the response encoded in JSON should be sent to the following URL:

https://ws.paythru.com/v3/session/initiate/json

Please note that if the response encoding segment of the URL is not provided, the response will be encoded in XML.

2.4 API Responses

Requests to the initiate session methods of this API processed successfully will be responded to with a 200 (OK) HTTP response code. The data contained within the body of the response will be encoded in either XML or JSON encoding types a requested.

XML encoded responses

The response parameters within an XML encoded response will be returned as XML elements, the name of which will be the parameter name, and the value contained within, its associated value. All the response data elements will be contained within a root element named 'paythruResponse'.

HTTP/1.1 200 OK Content-Length: xxx Content-Type: application/xml <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <responseParameter>Response value</responseParameter> ... </paythruResponse>

JSON encoded responses

The response parameters within a JSON encoded response will be returned as properties of a single JSON object, the name of which will be parameter name and the value, its associated value.

HTTP/1.1 200 OK Content-Length: xxx Content-Type: application/json {"responseParameter":"response Value", ...}

Requests to the post form method of this API processed successfully will be responded to with a 303 (See other) HTTP response code. The location header will be set to the appropriate URL provided by the merchant

The query string of the URL will be appended with base 64 encoded data that may be used for form repopulation and form validation error purposes. This data (once base 64 decoded) will be encoded in either XML or JSON as requested.

HTTP/1.1 303 See Other Location: http://yourdomain.com/yourpath?formId=7565&data=BASE64ENCODEDDATA...

Requests that are unable to be processed will be responded to with either the HTTP response code 400 (Bad Request), 401 (Unauthorized) or 403 (Forbidden) depending on the nature of the error.

2.5 Authentication

Requests to the initiate methods of this API require authentication. Two request parameters (apiKey and apiPassword) are required to be sent with each request to the service. These parameters will be provided by Paythru when the account is created.

If more than 5 requests are made containing invalid credentials within the same day, Paythru will not accept any further requests from the originating IP address for a period of one minute. After 10 requests failing authentication, the IP address will be blocked for 5 minutes.

2.6 Signing the request

Requests to the initiate method of this API must be signed by constructing a hash the request parameters and the shaKey (provided by Paythru) using the following steps:

  • Arrange all request parameters in order by parameter name (not including the shaSignature parameter)
  • Remove parameters with no value
  • Concatenate the parameter name, an equals symbol, the parameter value and your shaKey
  • Concatenate all resulting strings in order
  • Hash the resulting string using SHA512

The value of the hash must be provided in the shaSignature parameter within each request.

The following example indicates how to construct the signature for an auth method request using shaKey of HXUWeWG9gFa2ZHH1cQ:

Arrange parameters in alphabetical order by parameter name...

apiKey: tPkMAb7Hxxu6eGxLW1cW apiPassword: dBD82Go26Wsxyw1N6W1H errorPageUrl: https://yourdomain.com/error merchantCustomerReference: NULL

...remove the parameters with no value...

apiKey: tPkMAb7Hxxu6eGxLW1cW apiPassword: dBD82Go26Wsxyw1N6W1H errorPageUrl: https://yourdomain.com/error

...concatenate the parameter names, an '=' symbol, parameter value and shaKey. If the value is an array, JSON encode the value first (if the array contains numeric data types [int, float, double etc.] they must first be cast as string)...

apiKey=tPkMAb7Hxxu6eGxLW1cWHXUWeWG9gFa2ZHH1cQ apiPassword=dBD82Go26Wsxyw1N6W1HHXUWeWG9gFa2ZHH1cQ errorPageUrl=https://yourdomain.com/errorHXUWeWG9gFa2ZHH1cQ

...concatenate the strings in order...

apiKey=tPkMAb7Hxxu6eGxLW1cWHXUWeWG9gFa2ZHH1cQapiPassword=dBD 82Go26Wsxyw1N6W1HHXUWeWG9gFa2ZHH1cQerrorPageUrl=https://your domain.com/errorHXUWeWG9gFa2ZHH1cQ

...hash the resulting string using SHA512. This is your shaSignature for the request.

adb2698cab518ff05ff78769797ce91231488557c98805ad2d5e8f5d81ed 65ffc09c60593a5a203be99765cb320bbde54d02e7d4a47f81f9faf2e948 f7bb628b

2.7 Handling Post Form Response

The response to the Post Form method will always be a HTTP 303 redirect. Some of the data entered by the customer will be sent back to the merchant encrypted as the 'data' parameter of the query string in the redirect URL. Below are the list of possible GET parameters

Name Description Format
formId The formId passed in the request Alpha numeric characters
data Input data of the customer. The data will be masked and encrypted using AES-256 CBC Alpha numeric characters
iv The IV used for encryption Alpha numeric characters
  • Encryption Method AES-256 CBC
  • Encryption Key is same as the API Key
  • IV used for encryption will be a GET parameter
  • The string after decryption will be JSON encoded or XML depending on the response encoding in the request URL

2.8 API integration and testing

Upon request, Paythru can provide credentials to an API test service suitable for integration development work and testing. The test service acts as an exact replica of the live API although payment results are simulated and no transactions are actually submitted to the banks/card schemes.

Please contact Paythru to apply for test service credentials or for any further information regarding the service.


3.0 Methods

3.1 Initiate method

Description

A session must first be initiated by the merchant for each customer wishing to make a payment. A request must be sent from the merchant's servers to the 'initiate' method to achieve this. The initiate request returns a Session Key. The session key is used in every subsequent request to identify the payment session. The session key is valid for 30 minutes from time of initiation.

Request URL

https://ws.paythru.com/v3/session/initiate

Request parameters

Name Description Format
apiKey The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword The API Password provided by Paythru used for authentication. Alpha-numeric characters
errorPageUrl The merchant's page to redirect to when there is an error during the post form method. Valid URL
merchantCustomerReference A unique reference generated by the merchant to identify their customer. This parameter is optional. Alpha-numeric characters
shaSignature The merchant's signature for the request. Please refer to section 2.6 for details of how to construct the signature 128 Alpha numeric characters

Response parameters

Name Description Format
sessionKey A session key to be used in the subsequent postForm requests. (See section 3.3) 32 alpha numeric characters

Example Requests

HTTP Request

POST /v3/session/initiate HTTP/1.1 Host: ws.paythru.com Content-Length: 750 Content-Type: application/x-www-form-urlencoded apiKey=tPkMAb7Hxxu6eGxLW1cW &apiPassword=dBD82Go26Wsxyw1N6W1H &errorPageUrl=https%3A%2F%2Fyourdomain.com%2Ferror &merchantCustomerReference=userRef8347754938 &shaSignature=d81eaad76c4b5496e638aff882f4d4b1564c7c7e0969dc 2033eab654abc5ddeb8522924e964ce00ac7637eca41ec810f5cf29258dd 4affc187311e04e5f6ecf5

Example Responses

HTTP Response (XML)

HTTP/1.1 200 OK Content-Length: 170 Content-Type: application/xml <?xml version="1.0" encoding="utf-8"?> <paythruResponse> <sessionKey>4f848dbe9ed274a59e9f3a111688827e</sessionKey> </paythruResponse>

HTTP Response (JSON)

HTTP/1.1 200 OK Content-Length: 72 Content-Type: application/json { "sessionKey": "7bda870c20a3883d6093ee9a09e1d661", }

HTTP Response - Error (XML)

HTTP/1.1 400 Bad Request Content-Type: application/xml Content-Length: 125 <?xml version="1.0" encoding="UTF-8"?> <paythruResponse> <errorCode>133</errorCode> <traceCode>010706133</traceCode> <errorMessage>Error page URL not supplied</errorMessage> </paythruResponse>


3.3 Post Form Method

Description

The post form method enables the customer's card and other details to be sent to Paythru.

Within web implementations, the method is usually requested by delivering an HTML form to the customer with the action of the form set to the request URL shown below. The request is then initiated by the customer completing and submitting the form. Within native app implementations, the data collected from the user interface would usually require posting to Paythru using an HTTP client.

By default, all card data and customer data submitted within the request will be temporarily stored against the session. Multiple requests may be made to the post form method if this data is collected across a number of pages.

The response to a successful request to the post form function will be a HTTP 303 page redirect. The customer will be redirected to one of the URLs set by the merchant shown below

  • currentPageUrl: If there are validation errors in the request parameters, the HTTP redirect will be to the URL specified in currentPageURL with the user input and the validation errors.
  • nextPageUrl: If all the request parameters are successfully validated, the HTTP redirect will be to the URL specified in the nextPageUrl.
  • errorPageUrl: If any of the required fields are missing, the redirect will be to be errorPageUrl from the initiate request.

Please note that if the sessionKey is invalid or not provided, the customer will be redirected to a Paythru error page since it would not be possible to resolve the URLs above.

The query string of the URL that the customer is redirected to will be appended with a formId parameter. The value of the formId parameter will be set to that of the formId parameter within the request.

The redirect URL will also contain a data parameter with a value JSON encoded or XML string depending on the response encoding in the request URL. Refer Section 2.7 for steps to decrypt the data.

Once all the required data has been submitted to the server, further actions such as payment processing and card tokenisation may be performed using the data. Please refer to Paythru's Gateway API and Card Tokenisation API for more details.

Request URL

https://ws.paythru.com/v3/session/postform

Request parameters

Name Description Format
cardNumber The full primary account number (PAN) of the card number. This parameter is optional although may be required for transaction approval. 12-19 numeric characters
cardExpiryMonth The month of the customer's card expiry date. This parameter is optional although may be required for transaction approval. MM (e.g. '01' representing January)
cardExpiryYear The year of the customer's card expiry date. This parameter is optional although may be required for transaction approval. YY or YYYY
cardCV2 The CV2 security code (a.k.a. CSC, CVV, CVV2, CVC) as printed on the card. This parameter is optional although may be required for transaction approval. 3-4 numeric characters
cardholdersName The cardholder's name as printed on their card. This is submitted with the transaction and may therefore be used by the card issuer to determine the authenticity of the request. This parameter is optional although may be required for approval of the transaction. Alpha and symbol characters
cardDescription A name for the card. This parameter is optional and will be used only if the card is tokenised. Alpha and symbol characters
cardholderAddressPropertyName The property name or number of the cardholder's address (used for transaction address verification purposes) Up to 50 alpha numeric characters and symbols
cardholderAddressLine1 The first line of the cardholder's address (used for transaction address verification purposes) Up to 50 alpha numeric characters and symbols
cardholderAddressLine2 The second line of the customer's address (used for transaction address verification purposes) Up to 50 alpha numeric characters and symbols
cardholderAddressLine3 The third line of the customer's address (used for transaction address verification purposes) Up to 50 alpha numeric characters and symbols
cardholderAddressTown The town or city of the customer's address (used for transaction address verification purposes) Up to 50 alpha numeric characters and symbols
cardholderAddressCounty The county, province or state or the customer's address (used for transaction address verification purposes) Up to 50 alpha numeric characters and symbols
cardholderAddressPostcode The postal code of the customer's address (used for transaction address verification purposes) Up to 8 alpha numeric characters and symbols
cardholderAddressCountry The country of the customer's address (used for transaction address verification purposes) Up to 50 alpha numeric characters and symbols
sessionKey The session key identifying the customer's payment session. This is returned by Paythru in the response of the initiate request. The Session Key should be included in the form as a hidden field Up to 32 alpha numeric characters
formId This string will be returned in the URL whenever the user is redirected from Paythru. The form id should be included in the form as a hidden field. This parameter is optional. Up to 32 alpha numeric characters
nextPageUrl The URL on the merchant's servers where the user will be redirected after capturing the data. This field is optional if processPayment flag is set to 1. (If process payment is set to 1, the redirect will be to approved or declined page depending on the result of the transaction.) Valid URL
currentPageUrl The URL on the merchant's servers where the user will be redirected if the data cannot be validated. Valid URL
collect* Merchants wishing to collect any extra data from the customer may include additional parameters prefixed with 'collect' (e.g. collectDateOfBirth or collectSaveCard). The data entered by the customer will be encoded and returned along with the rest of the data in the query string of the nextPageUrl or currentPageUrl. Alpha numeric characters and symbols

In addition to the parameters above, a number of optional parameters may also be provided relating to details of the customer. These additional parameters are simply recorded against any resulting transaction or card token. Please refer to appendix 5.3 for the list of additional parameters that may be provided.

Response parameters

A successful request to the post form method will result in an HTTP 303 (See other) response code. The data parameter appended to the query sting of the URL that the customer is redirected to will contain the following parameters for the various request types. Refer Section 2.7 for steps to decrypt the data.

Successful submission of card data

The following parameters are returned following a valid card data is entered by the customer. This data would be appended to nextPageUrl. The data returned may therefore be used to present a review page.

Name Description Format
cardholdersName The value of the cardholdersName as input by the customer. Alpha and symbol characters
cardNumber The masked value of the cardNumber as input by the customer. Only the first 6 and the last 4 digits of the card number will be returned. The remaining characters will be substituted with asterisk characters. 12-19 numeric and asterisk characters
cardExpiryMonth The value of the cardExpiryMonth as input by the customer. MM (e.g. '01' representing January)
cardExpiryYear The value of the cardExpiryYear as input by the customer. YYYY
cardCV2 This field will be returned with no value. The value of the cardCV2 may not be repopulated into the card entry form. NULL

Validation error response

The following parameters are returned when invalid card data is entered by the customer. This data would be appended to currentPageUrl. The data returned may therefore be used to present repopulate the card entry form and to display the appropriate error messages.

Name Description Format
cardholdersName The value of the cardholdersName as input by the customer. Alpha and symbol characters
cardNumber The masked value of the cardNumber as input by the customer. Only the first 6 and the last 4 digits of the card number will be returned. The remaining characters will be substituted with asterisk characters. 12-19 numeric and asterisk characters
cardExpiryMonth The value of the cardExpiryMonth as input by the customer. MM (e.g. '01' representing January)
cardExpiryYear The value of the cardExpiryYear as input by the customer. YYYY
cardCV2 This field will be returned with no value. The value of the cardCV2 may not be repopulated into the card entry form. NULL
errors > {field} > errorCode The code indicating the type of error. Please refer to appendix 5.1 for a full list of error codes and associated messages. 3 numeric characters
errors > {field} > traceCode The trace code of the error. The trace code should be used in any communication with Paythru to assist in determining the cause of the error. 8 numeric characters
errors > {field} > errorMessage The human readable error message Up to 100 characters

Error response

The following parameters are returned when a request is badly formatted. The data will be appended to the errorPageUrl.

Name Description Format
errorCode The code indicating the type of error. Please refer to appendix 5.1 for a full list of error codes and associated messages. 3 numeric characters
traceCode The trace code of the error. The trace code should be used in any communication with Paythru to assist in determining the cause of the error. 8 numeric characters
errorMessage The human readable error message Up to 100 characters

Example HTML form

The following HTML provides an example of a form that would be embedded within the merchant's payment card entry page.

<form action="https://ws.paythru.com/v3/session/postform/" method="post" enctype="application/x-www-form-urlencoded"> <div> <label> Cardholder's name </label> <input type="text" name="cardholderName" /> </div> <div> <label> Card number </label> <input type="text" name="cardNumber" /> </div> <div> <label> Expiry date </label> <select name="cardExpiryMonth"> <option value="01">Jan</option> <option value="02">Feb</option> <option value="03">Mar</option> <option value="04">Apr</option> <option value="05">May</option> <option value="06">Jun</option> <option value="07">Jul</option> <option value="08">Aug</option> <option value="09">Sep</option> <option value="10">Oct</option> <option value="11">Nov</option> <option value="12">Dec</option> </select> <select name="cardExpiryYear"> <option value="13">2013</option> <option value="14">2014</option> <option value="15">2015</option> <option value="16">2016</option> <option value="17">2017</option> <option value="18">2018</option> <option value="19">2019</option> </select> <div> <label> Card number </label> <input type="text" name="cardNumber" /> </div> <div> <label> Security code </label> <input type="text" name="cardCV2" /> </div> <input type="hidden" name="nextPageUrl" value="https://yourdomain.com/review?user=1234"/> <input type="hidden" name="currentPageUrl" value="https://yourdomain.com/cardEntry?user=1234"/> <input type="hidden" name="formId" value="7565"/> <input type="hidden" name="sessionKey" value="e195e7ded11234ff12346cb2dbd715f1"/> </form>

Example Requests

Please note that all examples use XML encoding type.

Card entry request (Response encoding: JSON)

The following example illustrates a request submitted from a card entry form. The card details will be temporarily stored and the customer will be redirected to the 'nextPageUrl'.

POST /v3/session/postform/xml HTTP/1.1 Host: ws.paythru.com Content-Length: 750 Content-Type: application/x-www-form-urlencoded cardholderName=Mr+John+Smith &cardNumber=4444333322221111 &cardExpiryMonth=12 &cardExpiryYear=2014 &cardCV2=123 &nextPageUrl=https%3A%2F%2Fyourdomain.com%2Freview%3Fuser%3D1234 &currentPageUrl=https%3A%2F%2Fyourdomain.com%2FcardEntry%3Fuser%3D1234 &formId=7525 &sessionKey=e084629a407711234b3889287fde1234

Example Responses

Please note that all examples use XML encoding type.

Successful card entry request

HTTP/1.1 303 See Other Location: https://yourdomain.com/review?user=1234&formId=7565 &data=PHBheXRocnVSZXNwb25zZT48Y2FyZGhvbGRlcnNOYW1lPk1yIEpvaG4 gU21pdGg8L2NhcmRob2xkZXJzTmFtZT48Y2FyZE51bWJlcj4xMjM0MTIqKioq KioxMjM0PC9jYXJkTnVtYmVyPjxjYXJkQ1YyPjwvY2FyZENWMj48Y2FyZEV4c GlyeU1vbnRoPjEyPC9jYXJkRXhwaXJ5TW9udGg%2BPGNhcmRFeHBpcnlZZWFy PjExPC9jYXJkRXhwaXJ5WWVhcj48ZXJyb3JzPjxjYXJkTnVtYmVyPjxlcnJvc kNvZGU%2BMTA4PC9lcnJvckNvZGU%2BPHRyYWNlQ29kZT4wMTA3MDYxMDg8L3 RyYWNlQ29kZT48ZXJyb3JNZXNzYWdlPkludmFsaWQgY2FyZCBud

The value in the data parameter can be Base 64 decoded to reveal the following XML data:

<paythruResponse> <cardholdersName>Mr John Smith</cardholdersName> <cardNumber>123412******1234</cardNumber> <cardCV2></cardCV2> <cardExpiryMonth>12</cardExpiryMonth> <cardExpiryYear>11</cardExpiryYear> </paythruResponse>

Please note that in the return data, the value of the card number will be masked and the CV2 of the card will not be populated.

Invalid card entry request

HTTP/1.1 303 See Other Location: https://yourdomain.com/error?user=1234&formId=7565 &data=PHBheXRocnVSZXNwb25zZT48Y2FyZGhvbGRlcnNOYW1lPk1yIEpvaG 4gU21pdGg8L2NhcmRob2xkZXJzTmFtZT48Y2FyZE51bWJlcj4xMjM0MTIqKi oqKioxMjM0PC9jYXJkTnVtYmVyPjxjYXJkQ1YyPjwvY2FyZENWMj48Y2FyZE V4cGlyeU1vbnRoPjEyPC9jYXJkRXhwaXJ5TW9udGg%2BPGNhcmRFeHBpcnlZ ZWFyPjExPC9jYXJkRXhwaXJ5WWVhcj48ZXJyb3JzPjxjYXJkTnVtYmVyPjxl cnJvckNvZGU%2BMTA4PC9lcnJvckNvZGU%2BPHRyYWNlQ29kZT4wMTA3MDYx MDg8L3RyYWNlQ29kZT48ZXJyb3JNZXNzYWdlPkludmFsaWQgY2FyZCBudW1i ZXI8L2Vycm9yTWVzc2FnZT48L2NhcmROdW1iZXI%2BPGNhcmRDVjI%2BPGVy cm9yQ29kZT4xMTA8L2Vycm9yQ29kZT48dHJhY2VDb2RlPjAxMDcwNjExMDwv dHJhY2VDb2RlPjxlcnJvck1lc3NhZ2U%2BSW52YWxpZCBjYXJkIENWMjwvZX Jyb3JNZXNzYWdlPjwvY2FyZENWMj48Y2FyZEV4cGlyeVllYXI%2BPGVycm9y Q29kZT4xMDk8L2Vycm9yQ29kZT48dHJhY2VDb2RlPjAxMDcwNjEwOTwvdHJh Y2VDb2RlPjxlcnJvck1lc3NhZ2U%2BSW52YWxpZCBjYXJkIGV4cGlyeTwvZX Jyb3JNZXNzYWdlPjwvY2FyZEV4cGlyeVllYXI%2BPC9lcnJvcnM%2BPC9wYX l0aHJ1UmVzcG9uc2U%2B

The value in the data parameter can be base64 decoded to get the below XML data

<paythruResponse> <cardholdersName>Mr John Smith</cardholdersName> <cardNumber>123412******1234</cardNumber> <cardCV2></cardCV2> <cardExpiryMonth>12</cardExpiryMonth> <cardExpiryYear>11</cardExpiryYear> <errors> <cardNumber> <errorCode>108</errorCode> <traceCode>010706108</traceCode> <errorMessage>Invalid card number</errorMessage> </cardNumber> <cardCV2> <errorCode>110</errorCode> <traceCode>010706110</traceCode> <errorMessage>Invalid card CV2</errorMessage> </cardCV2> <cardExpiryYear> <errorCode>109</errorCode> <traceCode>010706109</traceCode> <errorMessage>Invalid card expiry</errorMessage> </cardExpiryYear> </errors> </paythruResponse>

Please note that in the return data, the value of the card number will be masked and the CV2 of the card will not be populated.

Error

HTTP/1.1 303 See Other Location: https://yourdomain.com/error?formId=9856&data=PHBh eXRocnVSZXNwb25zZT48ZXJyb3JDb2RlPjEzNDwvZXJyb3JDb2RlPjx0cmFj ZUNvZGU+MDEwNzA0MTM0PC90cmFjZUNvZGU+PGVycm9yTWVzc2FnZT5OZXh0 IHBhZ2UgVVJMIG5vdCBzdXBwbGllZDwvZXJyb3JNZXNzYWdlPjwvcGF5dGhy dVJlc3BvbnNlPg==

The value in the data parameter can be base64 decoded and then json decoded to get the below data

<paythruResponse> <errorCode>134</errorCode> <traceCode>010704134</traceCode> <errorMessage>Next page URL not supplied</errorMessage> </paythruResponse>


4.0 Error Handling

If the server is unable to process the request, an error is thrown. The nature of the error is returned as an error code and error message encoded in the expected response encoding format.

Error response format

The error reponse will contain the following parameters:

Name Description Format
errorCode The code indicating the type of error 3 numeric characters
traceCode The trace code of the error. The trace code should be used in any communication with Paythru to assist in determining the cause of the error. 8 numeric characters
errorMessage The human readable error message Up to 100 characters

For example, if an XML response has been requested from the API, the error will be returned in XML encoding.

Example XML error response

HTTP/1.1 401 Unauthorized Content-Type: text/json; charset=utf-8 Content-Length: 183 <?xml version="1.0" encoding="utf-8"?> <paythruResponse> <errorCode>102</errorCode> <traceCodeCode>010702102</traceCode> <errorMessage>Invalid API credentials</errorMessage> </paythruResponse>

See Appendix 5.1 for possible error messages.


5.0 Appendix

5.1 Error codes and messages

Error code Error message
101 No data sent
102 Invalid API credentials
103 Invalid function call
104 Invalid return type
105 Cannot find API settings for merchant
106 Permission denied to access this function
107 Invalid transaction value
108 Invalid card number
109 Invalid card expiry
110 Invalid card CV2
111 Currency not supported
119 No response from bank
120 Currency not supplied
121 This IP has been blocked for 1 minute because of too many failed attempts
122 This IP has been blocked for 5 minutes because of too many failed attempts
123 SHA Signature could not be verified
125 Invalid merchant reference
129 Invalid session key
133 Error page URL not supplied
134 Next page URL not supplied
135 Current page URL not supplied
136 Session expired

5.3 Optional Fields

Below are the optional fields that can be passed to the PostForm method

The data values are stored by Paythru against the transaction or token as appropriate for reporting and reconciliation purposes only.

Name Description Format
customerTitle The customer's title (e.g. Mr) Up to 12 alpha numeric characters and symbols
customerFirstName The customer's first name (e.g. John) Up to 50 alpha numeric characters and symbols
customerSurname The customer's surname (e.g. Smith) Up to 50 alpha numeric characters and symbols
customerEmail The email address of the customer Up to 50 alpha numeric characters and symbols
customerMobile The mobile phone number of the customer Up to 14 alpha numeric characters and symbols
customerLandline The telephone number of the user Up to 14 alpha numeric characters and symbols
customerAddressPropertyName The property name or number of the customer's address Up to 50 alpha numeric characters and symbols
customerAddressLine1 The first line of the customer's address Up to 50 alpha numeric characters and symbols
customerAddressLine2 The second line of the customer's address Up to 50 alpha numeric characters and symbols
customerAddressLine3 The third line of the customer's address Up to 50 alpha numeric characters and symbols
customerAddressTown The town or city of the customer's address Up to 50 alpha numeric characters and symbols
customerAddressCounty The county, province or state or the customer's address Up to 50 alpha numeric characters and symbols
customerAddressPostcode The postal code of the customer's address Up to 8 alpha numeric characters and symbols
customerAddressCountry The country of the customer's address Up to 50 alpha numeric characters and symbols