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.

This API enables merchants to host their own card payment interfaces in online environments whilst also lowering 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:

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'.

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

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:

...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)...

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)

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

cardholderName

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

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

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 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.