Skip to content

Client POST API

Version: 3

1.0 Introduction

The Client POST API is Paythru's processing solution for partially merchant hosted eCommerce transactions, allowing merchants greater control over the payment journey for their customers and sending the payment details to Paythru for processing.

This API allows you to host the card payment interface, but set the form action to post the data to Paythru. The relevant PCI compliance obligation for this API is SAQ A-EP. If you do wish to lower your PCI obligations further to SAQ A you can investigate the route offered by our Remote Fields Implementation.

We have also published some guidance on how to use the Client POST API inside a native Android or iOS mobile application.

1.1 API URL

Environment URL
Live https://ws.paythru.com
Staging (or sandbox) https://ws.demo.paythru.com

The examples in the document use relative URLs, which must be prepended with a URL from the above table depending on the environment in use. To use the sandbox account, the format of the request will be the same but you will need to change the URL you send requests into. Note that credentials are not shared between Staging and Live.


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:

/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:

/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 encrypted data that may be used for form repopulation and form validation error purposes. This data (once decrypted) will be encoded in either XML or JSON as requested. Section 2.7 explains more about the decryption process.

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

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:

  1. Arrange all request parameters in order by parameter name (not including the shaSignature parameter)
  2. Remove parameters with no value
  3. Concatenate the parameter name, an equals symbol, the parameter value and your shaKey
  4. Concatenate all resulting strings in order
  5. 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.

adb2698cab518ff05ff78769797ce91231488557c98805ad2d5e8f5d81ed65ffc09c60593a5a203be99765cb320bbde54d02e7d4a47f81f9faf2e948f7bb628b

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
  1. Encryption Method AES-256 CBC
  2. Encryption Key is same as the API Key
  3. IV used for encryption will be a GET parameter
  4. 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

/v3/session/initiate

Request parameters

Name Mandatory Description Format
apiKey Yes The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword Yes The API Password provided by Paythru used for authentication. Alpha-numeric characters
errorPageUrl Yes The merchant's page to redirect to when there is an error during the post form method. Valid URL (url encoded)
merchantCustomerReference No A unique reference generated by the merchant to identify their customer. Alpha-numeric characters
shaSignature Yes 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. 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

  1. 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.
  2. nextPageUrl: If all the request parameters are successfully validated, the HTTP redirect will be to the URL specified in the nextPageUrl.
  3. 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

/v3/session/postform

Request parameters

Name Mandatory Description Format
cardNumber Yes The full primary account number (PAN) of the card number. 12-19 numeric characters
cardExpiryMonth Conditional The month of the customer's card expiry date. Field is mandatory unless cardExpiryDate is populated. Numeric two digit month
cardExpiryYear Conditional The year of the customer's card expiry date. Field is mandatory unless cardExpiryDate is populated. Numeric two or four digit year
cardExpiryDate Conditional The month and year of the customer's card expiry date. Field is mandatory unless both cardExpiryMonth and cardExpiryYear and card are populated. Numeric two digit month followed by two or four digit year (e.g. MMYY or MMYYYY)
cardCV2 No 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
cardholderName No 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 No A name for the card. This parameter is optional and will be used only if the card is tokenised. Alpha and symbol characters
cardholderAddressPropertyName No The property name or number of the cardholder's address (used for address verification) Up to 50 alpha numeric characters and symbols
cardholderAddressLine1 No The first line of the cardholder's address (used for address verification) Up to 50 alpha numeric characters and symbols
cardholderAddressLine2 No The second line of the customer's address (used for address verification) Up to 50 alpha numeric characters and symbols
cardholderAddressLine3 No The third line of the customer's address (used for address verification) Up to 50 alpha numeric characters and symbols
cardholderAddressTown No The town or city of the customer's address (used for address verification) Up to 50 alpha numeric characters and symbols
cardholderAddressCounty No The county, province or state or the customer's address (used for address verification) Up to 50 alpha numeric characters and symbols
cardholderAddressPostcode No The postal code of the customer's address (used for address verification) Up to 8 alpha numeric characters and symbols
cardholderAddressCountry No The country of the customer's address (used for address verification) Up to 50 alpha numeric characters and symbols
sessionKey Yes 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 No 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. Up to 32 alpha numeric characters
nextPageUrl Yes The URL on the merchant's servers where the user will be redirected after capturing the data. Valid URL
currentPageUrl Yes The URL on the merchant's servers where the user will be redirected if the data cannot be validated. Valid URL
collect* No 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 additional parameters may be provided relating to details of the customer. These additional parameters are 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 string will contain the following parameters. Refer to Section 2.7 for steps to decrypt the data.

Successful submission of card data

The following parameters are returned following successful form validation. This data would be appended to nextPageUrl. The data returned may therefore be used to present a review page.

Name Description Format
cardholderName The value of the cardholderName 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 asterisks. 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 repopulate the card entry form and to display the appropriate error messages.

Name Description Format
cardholderName The value of the cardholderName 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 asterisks. 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/xml" 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>  
  <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=UlAgUVVVDn5HGMBC7dK5Tv%2BebmLhoc%2F7OrwPfSpKQ0us6ORdIXzC91
VREpoVrM8eqUgO4pGt0IYCxK%2Bi6VSuhlN8ZEg6K%2BzUT5B22PjFzOEetF0YW
worN9SjFRkXDRkl1C0sVnDL6qxw%2Fja7%2BvBqnhbpmBaKoEbE9uAmxAc2s8%2B2
wn82k8wHoVIk0lIbmkYmI5%2F72J7cMRTxGA22MOhGpkYedNZ4FNkSYfpx1RpRGqL
3Y1Igh3cwLt87CI%2F2O9NLRarTDv7iCW%2FOQTBHGo%2BzW%2FXK6zsuLMdHSxY
emZhys8Q%3D&iv=1ff2f1d19cffd18f

The value in the data parameter can be decrypted (see section 2.7 for decryption process) to reveal the following XML data:

<paythruResponse>
  <cardholderName>Mr John Smith</cardholderName>
  <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=qjGMBSe172gJTd45MUZKHeKb%2BCZzz9c7lvc3ewq7ndeOg85XWUHts%2
FWoIo8sZx%2FAEn7pDLR1ZJfEhF2y4JXupfEl0MHYJn5RWCbPEq02xRI%2FSjn9
LDIzl9%2Bsm6960fUb8jh6yUDhIWii0o9ApfsQ2gA16J3wrI0VGVhJ71aJ9AVuC3
MGfDIHZMmjgADGl%2FCGmex7xK%2F2FDWqV0ALzf%2FQodZMYsxAuBMjLDvfGk9a
CuEs59qNgNejU37EZX6gldC4%2BaEYZR0YblNbL5457m7sfpEV1clSXxO%2BB8F
%2F0GQ%2FNKIIWqWuBMi8w%2BZZQD2B%2Fj8OgO4c%2Fe7N3vITa6NwjQnPpWpR1
BcfZNffwh3UtqJtaMyLGKY6GMKdTEsAxe6mcheF88HduY5ksKb2ljulJQ654vQ%2
BkZzyvoalyT9bGTUS0o9cCwTXpU%2FzwLNJZ%2F4t1ejC532Zzn2%2Bow3%2FTcsL
iTYEeF%2BN5MD8Qef%2F3At40fN3nXdRa2iv%2FLxmSnnGTWVq1rg4aS2Dzph7BB
y0toC0nFid0MKAJd%2BqZsGRlSIr24rIeNWaFcmJdQsw64mhZyHKhRdgrFYFNI4K8
hwWwcIMZbFTEtmGR4aVSGIWnPQuGr2IWjYz0eZJyL5PkmXsJNfPiqYV%2FAeqe5R
px1nXT98X7KPNN62B2irXUyiM0erfErK%2FHlTfKZe%2BGsA8j6lAWRqCe30wITY1
JnGoAPvdue8tNAp7bqO70%2F8uBJ%2Buzzx0bTZuDayRAO2EPW0T4I23ncCPb4ENQ
wELZcoX3hMziq05bWKAyGIYEtrxDS4AtBcRV9I3Lw2mp0G9%2Bp6TZ2B%2ByRlcT
4r1JOF&iv=c8431320c68e1bd5

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

<paythruResponse>
  <cardholderName>Mr John Smith</cardholderName>
  <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=LIZ1kJ3071UGf5Ap336PT2w9vvDFvy%2Fa8DM7FvWW2wwE5Zz7k%2BMW
WoF9RBxLeUFkEGoiFUzmdeR4OlWZs%2BBU8gSPlhq1gZcBI%2FWmq94pNll8KILAuY
Vh%2BGQya3EcQSxQCEVbyQxw9fnS0SXTzuqGpiCzST5ONVID9AXS8N6DBOk1IlBJMG
D4dqNJL82QIAolh1XLfJDNTmFSHZmmtFGDlw%3D%3D&iv=1b87e82aa8e37238

The value in the data parameter can be decrypted 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
Back to top