Enterprise API

Version: 5


1.0 Overview

The Enterprise API is Paythru's processing solution for redirect based eCommerce transactions, allowing merchants to take payments from their customers without the need to deal with complex Payment Card Industry (PCI) compliance requirements by redirecting the customer to Paythru hosted pages to collect payment data.

The primary method of the Enterprise API, gettoken, is the entry point to our Hosted Payment Pages (HPP). Paythru's Hosted Payments Pages is a set of web pages which can process payments from card details entered by the customer. By redirecting your user to our Hosted Payment Pages you can lower your PCI obligations to SAQ A.

1.1 API URL

Environment URL
Live https://api.paythru.com
Staging (or sandbox) https://api.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 Methods

The API accepts HTTP requests over SSL (HTTPS) with the parameters passed as POST key=value pairs.

2.1 gettoken method

The gettoken method is used to set up a checkout with Paythru prior to directing the customer to Paythru's Hosted Payment Pages.

REQUEST

Request URL: /gettoken

Name Description Format (max characters)
api_key* The key is used to identify the requesting merchant, which is supplied to the merchant by Paythru. Char (32)
api_password* The password for the API key, which is supplied to the merchant by Paythru. Char (32)
version* The version of the API. Currently on 5. Integer
token_start The time from which the token will be active. If this parameter is not provided, the default value will be the time the request is sent. Unix timestamp
token_expiry The time that the token expires. Paythru's Hosted Payment Page will issue a warning if a user attempts to redeem an expired token and the user will not be able to complete checkout. If this parameter is not provided, the default value will be the merchants default value, usually set to +1 week from token_start. Unix timestamp
token_uses The number of times a token can be used for an approved transaction. The counter is only decremented when an approved transaction is completed against the token. If this parameter is not provided, the default value will be the merchants default value, usually set to -1 (meaning infinite uses). Integer
[max value 127]
token_redemptions The number of times a token URL can be visited. One visit to the token URL counts as 1 redemption. Default is to allow infinite (-1) redemptions for the life of the token. Integer [max value 127]
success_url The URL the customer will be directed to after an approved transaction. If this parameter is not provided, the default value will be the merchant's default value. See appendix 3.7 for more detail. Char
cancel_url The URL that users may return to if they choose to cancel their checkout. If this parameter is not provided, the default value will be the merchant's default value. Char
currency The currency that the transaction will be processed in. If this parameter is not provided, the default value will be the merchant's default value. Merchants will require each currency configured on their account. Char (3)
trans_reference A reference to be stored against the transaction. This will be reported in the callback (see appendix 3.2) and also our reporting interfaces. Char (32)
payment_source The source of the payment. See appendix 3.8 for more details ecomm / moto
item_name** The name of an item to add to the token. If multiple items are to be set, this field should be appended with an ID in square brackets to identify the item. i.e. item_name[0]=Example%20mug&item_name[1]=VAT Char (128)
item_price** The amount for a single unit of the item as a decimal value.
For example, handling pounds sterling the following conversions should be expected:
'5.95' = £5.95
'5' = £5.00
'0.95' = £0.95
If multiple items are to be set, this field should be appended with an ID in square brackets to identify the item. i.e. item_price[0]=10.00&item_name[1]=2.00
Currency
item_quantity The quantity of an item to add to the token. If multiple items are to be set, this field should be appended with an ID in square brackets to identify the item. i.e. item_quantity[0]=1&item_quantity[1]=2.00.
If quantity is absent or 0, Paythru will assume a quantity of 1
Integer
item_reference The merchant's reference number of an item to add to the token. If multiple items are to be set, this field should be appended with an ID in square brackets to identify the item. i.e. item_reference[0]=A%20simple%20mug&item_name[1]=sales%20tax Char (16)
salutation The salutation of the user e.g. Mr, Miss or Dr. Char (10)
first_name The first name of the user. Char (32)
surname The surname of the user. Char (32)
email The email address for the user. Char
date_of_birth The date of birth of the user. This should be supplied in the format DDMMYYYY e.g. 30061970 Char (8)
mobile_phone The mobile phone number of the user. This should be supplied numerals only without a leading zero and prefixed with the country code. E.g. 447891234567 Integer
home_phone The home phone number of the user to be set in the token. This should be supplied numerals only without a leading zero, and prefixed with the country code. E.g. 441494415161 Integer
property_name The property name of the user's billing address. This should be left blank if the property does not have a name. Char (50)
address_1 The first line (street level) of the user's billing address. Char (150)
address_2 The second line of the user's billing address. Char (150)
town The town or city of the user's billing address. Char (100)
county The county, state or province of the users billing address. Char (50)
postcode The postal or zip code of the user's billing address. Char (15)
country The country of the user's billing address. Only accepts the alpha-2 code format of ISO 3166-1. Char (2)
callback_url A URL residing on your servers to which Paythru will send some basic data when a transaction is successfully completed. The callback URL allows data to be sent to port 80 or 443. See Appendix for details of the data passed to this URL. Char
redemption_redirect_url The URL the user will be redirected to when the token is redeemed Char
auto_redirect If 1, the user will be redirected to the success_url on a successful transaction. If 0, Paythru's default pages are displayed. See appendix 4.7 for more detail. Int (1)
applet If you have multiple applets configured with Paythru you can switch between them by providing the applet name. Char
trans_type Defaults to Auth
If set to 'PreAuth' then the transaction resulting from redemption of the generated token is treated as a pre-auth.
Char (10)
trans_cat Defaults to 'purchase'.
Denotes the category of the transaction. Possible values are 'donation', 'debt', 'booking'.
Char (10)
trans_class Any description necessary to identify the type of transaction in the Partner portal and data exports. For example, "Donation", "Promotion", "Subscription" etc. Char (32)
3D_secure Defaults to 0
If set to 1 and the merchant supports 3DSecure/Verify by Visa then the transaction resulting from redemption of the generated token is treated as a 3DSecure/Verify by Visa transaction. Merchants will need to discuss setup with Paythru to allow this.
Int (1)
terminal_key Merchants with more than one merchant account will be issued with a 'terminal key' for each account by Paythru. The appropriate key should be provided to nominate the account that should be used for the transaction. If no key is provided, Paythru will use the merchant's default account. Char

*Denotes a required parameter

** Required if any of the parameters are present

RESPONSE

The response content is returned as XML formatted data. The data may be regarded as a receipt to confirm the request has been parsed correctly. Merchants may also choose to save the data to a database or log file for tracking and reporting purposes. If merchants simply wish to refer their customer to the Paythru Payment Pages however, they should simply extract the redemption_url parameter and refer the customer to it.

Name Description
token:
merchant The merchant name.
applet Name of the applet that is used.
tokenid The unique id for the relationship of user, item and merchant data. This enables Paythru to identify specific users.
redemption_url The URL with the tokenid appended to the end of it. This should be given through to the user to access Paythru's Hosted Payment Page to perform the required transactions.
token_start The time from which the token will be active.
token_expiry The time that the token expires. Paythru's Hosted Payment Page will issue a warning if a user attempts to redeem an expired token and the user will not be able to buy the items.
uses The number of times the token's items can be purchased.
redemptions The number of times the token URL can be visited.
success_url The URL the customer will be directed to after successfully purchasing the token's items.
cancel_url The URL that users may return to if they wish to cancel their purchase.
callback_url The URL that Paythru will programmatically send a response to on a successful transaction for the token, if specified.
trans_type The transaction type passed in the request. Default: auth
trans_cat The transaction category passed in the request. Default: purchase
currency The currency in which the token items may be paid for.
creation The time of creation of the token by Paythru.
items:
name The name of an item added to the token.
price The price of an item added to the token.
quantity The quantity of an item added to the token.
reference The merchant's reference number of an item added to the token.
user - address:
property_name The property name of the user's billing address.
address_1 The first line (street level) of the user's billing address.
address_2 The second line of the user's billing address.
town The town or city of the user's billing address.
county The county, state or province of the user's billing address.
postcode The postal or zip code of the user's billing address.
country The country of user's billing address.
user:
salutation
first_name The first name of the user to be set in the token.
surname The surname of the user to be set in the token.
date_of_birth The date of birth of the user to be set in the token.
mobile_phone The mobile phone number of the user to be set in the token.
home_phone The home phone number of the user to be set in the token.

EXAMPLE USAGE OF GETTOKEN

The following example shows an HTTP POST request for user John Smith to buy an 'Example mug' from our Example shop. The token_uses is set to -1, so John will be able to buy this product indefinitely.

REQUEST:
POST /gettoken HTTP/1.1
Host: api.paythru.com
Content-Length: 156
Content-Type: application/x-www-form-urlencoded

api_key=xxxxxxx
&api_password=xxxxxxxx
&version=5
&token_uses=-1
&item_name=Example+mug
&item_price=2.99
&currency=GBP
&salutation=Mr
&first_name=John
&surname=Smith
RESPONSE:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 592

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
<token>
<tokenid>Jn6DzAb4</tokenid>
<merchant>Example</merchant>
<redemption_url>https://example.paythru.mobi/t/Jn6DzAb4</redemption_url>
<token_start>2010-05-21T10:28:21Z</token_start>
<token_expiry>2010-05-27T10:28:21Z</token_expiry>
<uses>-1</uses>
<trans_type>auth</trans_type>
<trans_cat>purchase</trans_cat>
<currency>GBP</currency>
<creation>2010-05-21T10:28:21Z</creation>
</token>
<user>
<salutation>Mr</salutation>
<first_name>John</first_name>
<surname>Smith</surname>
</user>
<items>
<item>
<name>Example mug</name>
<price>2.99</price>
</item>
</items>
</paythruResponse>

2.2 repeat method

The repeat method is used to set up an actual payment or reservation of funds with Paythru where a previous successful transaction has already been done. The previous transaction key is necessary to identify which card to debit. This function will debit the customers' card and credit merchant's account with the specified amount. This method does NOT interface with Paythru's hosted payment pages at all.

REQUEST

Request URL: /repeat

Name Description Format (max characters)
api_key* The key is used to identify the requesting merchant, which is supplied to the merchant by Paythru. Char (32)
api_password* The password for the API key, which is supplied to the merchant by Paythru. Char (32)
version* The version of the API. Currently on 5. Integer
prev_trans_key* The trans_key of the original transaction from which you want to use the card details and user information. Integer
trans_type* This may be either 'Auth' or 'PreAuth'. Auth, used for any normal transaction, validates the card and debits the specified amount immediately.
PreAuth, used for situations where the product sold is currently out of stock and cannot be shipped, validates the card and the bank then suspends the specified amount in the end user's account for a limited period of time. This must be captured by a 'Capture' request on this original transaction within 10 days or the Pre Auth will be voided automatically.
Char (32)
trans_value* Any amount as a decimal value.
For example, handling pounds sterling the following conversions should be expected:
'5.95' = £5.95
'5' = £5.00
'0.95' = £0.95
Currency
trans_class Any description necessary to identify the type of transaction in the partner.paythru.com portal, and data exports. For example, "Donation", "Promotion", "Subscription" etc. Char (32)

*Denotes required parameter

RESPONSE

The response content is returned as XML formatted data. The data may be regarded as a receipt to confirm the request has been parsed correctly. Merchants should save the data to a database or log file for tracking and reporting purposes.

Name Description
trans_type The transaction type specified by you in the request.
trans_value The amount specified by you in the request.
prev_trans_key The trans_key of the original transaction from which the card details and user information was used for the current transaction. You specified this field in the request.
trans_class Any description necessary to identify the type of transaction in the partner.paythru.com portal, and data exports. For example, "Donation", "Promotion", "Subscription" etc. You specified this field in the request.
system_action This indicates what action the Paythru system used for this transaction. In this case it will be 'REPEAT'.
status Status flag to indicate success or failure. '1' = success and '0' = fail.
trans_key The Paythru unique identifier for this transaction. This should be used for any subsequent transactions such as a refund.
auth_code The Unique Identifier issued by the bank for this transaction.
EXAMPLE

The following example shows an HTTP POST request to do a repeat transaction with a key of 'abcde1234567890fghijkl' with value 2.56. This value may be any new value.

REQUEST:
POST /repeat HTTP/1.1
Host: api.paythru.com
Content-Length: 154
Content-Type: application/x-www-form-urlencoded

api_key=xxxxxxx
&api_password=xxxxxxxx
&version=5
&prev_trans_key=abcde1234567890fghijkl
&trans_type=Auth
&trans_value=2.56
&trans_class=Test+Transaction+Repeat
RESPONSE:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 376
<?xml version="1.0" encoding="utf-8"?>

<paythruResponse>
 <trans_type>auth</trans_type>
 <trans_value>10</trans_value>
 <prev_trans_key>4223dddd08d16testtest89fa4527483d</prev_trans_key>
 <trans_class>apitest</trans_class>
 <system_action>REPEAT</system_action>
 <status>1</status>
 <trans_key>431ba0cd55testtest5085cb569ddc260a</trans_key>
 <auth_code>20200</auth_code>
</paythruResponse>

2.3 refund method

The refund method is used to refund in part or in full the amount of a previous successful transaction. The previous transaction key is necessary to identify which card to credit. Crediting end user's card and debiting merchant's account with the specified amount. This method does NOT interface with Paythru's hosted payment pages at all.

REQUEST

Request URL: /refund

Name Description Format (max characters)
api_key* The key is used to identify the requesting merchant, which is supplied to the merchant by Paythru. Char (32)
api_password* The password for the API key, which is supplied to the merchant by Paythru. Char (32)
version* The version of the API. Currently on 5. Integer
prev_trans_key* The trans_key of the original transaction from which you want to use the card details and user information. Integer
trans_value* Any amount as a decimal value.
For example, handling pounds sterling the following conversions should be expected:
'5.95' = £5.95
'5' = £5.00
'0.05' = £0.05
Note: Some banks do not support partial refunds or require special permissions to support them. Please notify us if you intend to use Partial refunds
currency
trans_class Any description necessary to identify the type of transaction in the partner.paythru.com portal, and data exports. For example, "Donation", "Promotion", "Subscription" etc. Char (32)

*Denotes required parameter

RESPONSE

The response content is returned as XML formatted data. The data may be regarded as a receipt to confirm the request has been parsed correctly. Merchants should save the data to a database or log file for tracking and reporting purposes.

Name Description
trans_type This value will be refund.
trans_value Any amount as a decimal value.
For example, handling pounds sterling the following conversions should be expected:
'5.95' = £5.95
'5' = £5.00
'0.05' = £0.05
prev_trans_key The trans_key of the original transaction of which the card details and user information was used for the current transaction. You specified this field in the request.
trans_class Any description necessary to identify the type of transaction. Present if you specified this field in the request.
system_action This indicates what action the Paythru system used for this transaction. In this case it will be 'REFUND'.
status Status flag to indicate success or failure. '1' = success and '0' = fail.
trans_key The Paythru unique identifier for this transaction. This should be used for any subsequent transactions such as a refund.
auth_code The Unique Identifier issued by the bank for this transaction.
EXAMPLE

The following example shows an HTTP POST request to refund transaction with key of 'abcde1234567890fghijkl' with value 2.56. This value must be equal to or smaller than the original transaction value.

REQUEST:

POST /refund HTTP/1.1
Host: api.paythru.com
Content-Length: 126
Content-Type: application/x-www-form-urlencoded
api_key=xxxxxxx&api_password=xxxxxxxx&version=5&prev_trans_key=abcde1234567890fghijkl&trans_value=2.56&trans_class=Test+Refund
RESPONSE:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 382

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
<trans_type>refund</trans_type>
<trans_value>2.56</trans_value>
<prev_trans_key>abcde1234567890fghijkl</prev_trans_key>
<trans_class>API Testing</trans_class>
<system_action>REFUND</system_action>
<status>1</status>
<trans_key>lkjihgf0987654321edcba</trans_key>
<auth_code>370031</auth_code>
</paythruResponse>

2.4 capture method

The capture function is used to take the funds from a pre-auth transaction and deposit them in their designated merchant account.

REQUEST

Request URL: /capture

Name Description Format (max characters)
api_key* The key is used to identify the requesting merchant, which is supplied to the merchant by Paythru. Char (32)
api_password* The password for the API key, which is supplied to the merchant by Paythru. Char (32)
version* The version of the API. Currently on 5. Integer
prev_trans_key* The trans_key of the original transaction from which you want to use the card details and user information. Integer
trans_value* The amount to be captured from the pre-auth. Must be equal to or less than the amount reserved. currency
trans_class Any description necessary to identify the type of transaction in the partner.paythru.com portal, and data exports. For example, "Donation", "Promotion", "Subscription" etc. Char (32)

*Denotes required parameter

RESPONSE

The response content is returned as XML formatted data. The data may be regarded as a receipt to confirm the request has been parsed correctly. Merchants should save the data to a database or log file for tracking and reporting purposes.

Name Description
trans_type This value will be capture.
trans_value Any amount as a decimal value.
For example, handling pounds sterling the following conversions should be expected:
'5.95' = £5.95
'5' = £5.00
'0.05' = £0.05
prev_trans_key The trans_key of the original transaction of which the card details and user information was used for the current transaction. You specified this field in the request
trans_class Any description necessary to identify the type of transaction. Present if you specified this field in the request
system_action This indicates what action the Paythru system used for this transaction. In this case it will be 'CAPTURE'
status Status flag to indicate success or failure. '1' = success and '0' = fail
trans_key The Paythru unique identifier for this transaction. This should be used for any subsequent transactions such as a refund
auth_code The Unique Identifier issued by the bank for this transaction
EXAMPLE

The following example shows an HTTP POST request to refund transaction with key of 'abcde1234567890fghijkl' with value 10. This value must be equal to or smaller than the original transaction value.

REQUEST:
POST /capture HTTP/1.1 
Host: api.paythru.com 
Accept: */* 
Content-Length: 143 
Content-Type: application/x-www-form-urlencoded
api_key=xxxxxxxxxxxx&api_password=xxxxxxxxxxxxxx&version=5&prev_trans_key=abcde1234567890fghijkl&trans_value=100&trans_class=API+Testing+Capture 
RESPONSE:
HTTP/1.1 200 OK 
Date: Mon, 14 Jun 2010 14:38:43 GMT 
Server: Apache X-Powered-By: PHP/5.2.13 
Content-Length: 364 
Connection: close 
Content-Type: text/xml 

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
<trans_type>capture</trans_type>
<trans_value>100</trans_value>
<prev_trans_key>abcde1234567890fghijkl</prev_trans_key>
<trans_class>API Testing Capture</trans_class>
<system_action>CAPTURE</system_action>
<status>1</status>
<trans_key>lkjihgf0987654321edcba</trans_key>
<auth_code>372315</auth_code>
</paythruResponse> 

2.5 cancel method

The cancel function is used to remove the reservation of the funds from a pre-auth transaction.

REQUEST

Request URL: /cancel

Name Description Format (max characters)
api_key* The key is used to identify the requesting merchant, which is supplied to the merchant by Paythru. Char (32)
api_password* The password for the API key, which is supplied to the merchant by Paythru. Char (32)
version* The version of the API. Currently on 5. Integer
prev_trans_key* The trans_key of the pre-auth of which you want to cancel the reservation of the funds. Integer
trans_value* The amount to be cancelled from the pre-auth. Must be equal to or less than the amount reserved. currency
trans_class Any description necessary to identify the type of transaction in the partner.paythru.com portal, and data exports. For example, "Donation", "Promotion", "Subscription" etc. Char (32)

*Denotes required parameter

RESPONSE

The response content is returned as XML formatted data. The data may be regarded as a receipt to confirm the request has been parsed correctly. Merchants should save the data to a database or log file for tracking and reporting purposes.

Name Description
trans_type This value will be cancel.
trans_value Any amount as a decimal value.
For example, handling pounds sterling the following conversions should be expected:
'5.95' = £5.95
'5' = £5.00
'0.05' = £0.05
prev_trans_key The trans_key of the original transaction of which the card details and user information was used for the current transaction. You specified this field in the request
trans_class Any description necessary to identify the type of transaction. Present if you specified this field in the request
system_action This indicates what action the Paythru system used for this transaction. In this case it will be 'CANCEL'
status Status flag to indicate success or failure. '1' = success and '0' = fail
trans_key The Paythru unique identifier for this transaction. This should be used for any subsequent transactions such as a refund
auth_code The Unique Identifier issued by the bank for this transaction
EXAMPLE

The following example shows an HTTP POST request to cancel transaction with key of 'abcde1234567890fghijkl' with value 100. This value must be equal to or smaller than the original transaction value.

REQUEST:
POST /cancel HTTP/1.1 
Host: api.paythru.com 
Accept: */* 
Content-Length: 143 
Content-Type: application/x-www-form-urlencoded
api_key=xxxxxxxxxxxx&api_password=xxxxxxxxxxxxxx&version=5&prev_trans_key=abcde1234567890fghijkl&trans_value=100&trans_class=API+Testing+Cancel 
RESPONSE:
HTTP/1.1 200 OK 
Date: Mon, 14 Jun 2010 14:38:43 GMT 
Server: Apache X-Powered-By: PHP/5.2.13 
Content-Length: 364 
Connection: close 
Content-Type: text/xml 

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
<trans_type>cancel</trans_type>
<trans_value>100</trans_value>
<prev_trans_key>abcde1234567890fghijkl</prev_trans_key>
<trans_class>API Testing Cancel</trans_class>
<system_action>CANCEL</system_action>
<status>1</status>
<trans_key>lkjihgf0987654321edcba</trans_key>
<auth_code>372315</auth_code>
</paythruResponse> 

2.6 sms method

The sms method is used to send SMS' to end user's mobile phones. This method does NOT interface with Paythru's hosted payment pages at all.

REQUEST

Request URL: /sms

Name Description Format (max characters)
api_key* The key is used to identify the requesting merchant, which is supplied to the merchant by Paythru. Char (32)
api_password* The password for the API key, which is supplied to the merchant by Paythru. Char (32)
version* The version of the API. Currently on 5. Integer
msisdn* Any mobile phone number in a valid format with international such as "00447891234567" or "+447891234567". Char (15)
message* Any message or notification of the type string that is no longer than 160 characters. Char (160)

*Denotes required parameter

RESPONSE

The response content is returned as XML formatted data. The data may be regarded as a receipt to confirm the request has been parsed correctly. Merchants should save the data to a database or log file for tracking and reporting purposes.

Name Description
sms:
msisdn The mobile phone number in the proper international format.
message The message that you have sent.
status Status flag to indicate success or failure. '1' = success and '0' = fail.
messid The unique identifier of this SMS.
EXAMPLE

The following example shows an HTTP POST request to send an SMS to the United Kingdom mobile phone number of 07891234567. The proper country code (44) is appended to construct the MSISDN.

REQUEST:
POST /sms HTTP/1.1
Host: api.paythru.com
Content-Length: 110
Content-Type: application/x-www-form-urlencoded
api_key=xxxxxxx&api_password=xxxxxxxx&version=5&msisdn=447891234567&message=Hello+paythru.+http://paythru.mobi
RESPONSE:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 257

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
<sms>
<msisdn>447891234567</msisdn>
<message>Hello paythru. http://paythru.mobi</message>
<status>1</status>
<messid>2F3FC22C-AB12-4A84-8E9E-1A6008C2FF6A</messid>
</sms>
</paythruResponse>

2.7 address method

The address method is used to retrieve the full address when you supply the house number/name and the post code. This is a UK only feature.

REQUEST

Request URL: /address

Name Description Format (max characters)
api_key* The key is used to identify the requesting merchant, which is supplied to the merchant by Paythru. Char (32)
api_password* The password for the API key, which is supplied to the merchant by Paythru. Char (32)
version* The version of the API. Currently on 5. Integer
property_name* Any valid house number or name. Char (32)
postcode* Any valid United Kingdom postcode. Char (15)

*Denotes required parameter

RESPONSE

The response content is returned as XML formatted data. The data returned will be the matched address details, assuming the lookup was successful, see the Error Codes appendix for failure cases.

Name Description
address:
status Status flag to indicate success or failure. '1' = success and '0' = fail.
address_1 The first line of the full address. This might consist of the house number/name and the street name.
address_2 The second line of the full address.
town The town or city name of the address.
county The county or province of the address.
postcode The postal or zip code of the address.
EXAMPLE

The following example shows an HTTP POST request for an address lookup for property number/name of Badminton Court at postcode HP7 0DD.

REQUEST:
POST /address HTTP/1.1
Host: api.paythru.com
Content-Length: 94
Content-Type: application/x-www-form-urlencoded
api_key=xxxxxxx&api_password=xxxxxxxx&version=5&property_name=Badminton+Court&postcode=HP7+0DD
RESPONSE:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 286
<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
<address>
<status>1</status>
<address_1>Morley House</address_1>
<address_2>Badminton Court</address_2>
<town>Amersham</town>
<county>Buckinghamshire</county>
<postcode>HP7 0DD</postcode>
</address>
</paythruResponse>

2.8 transaction_lookup method

The transaction lookup method is used to retrieve details about the transaction when you supply the transaction key.

REQUEST

Request URL: /transaction_lookup

Name Description Format (max characters)
api_key* The key is used to identify the requesting merchant, which is supplied to the merchant by Paythru. Char (32)
api_password* The password for the API key, which is supplied to the merchant by Paythru. Char (32)
version* The version of the API. Currently on 5. Integer
trans_key * The transaction key. Char (32)

*Denotes required parameter

RESPONSE

The response content is returned as XML formatted data. The data returned will be the matched with the transaction details, assuming the lookup was successful, see the Error Codes appendix for failure cases.

Name Description
status Status of the transaction. (Appendix 4.6)
token The standard token associated with this transaction
value The total amount that was paid in the standard currency denomination, e.g. sterling (£). Includes '.' as the separator, e.g."100.00"
currency The currency in which amount was paid. ISO 4217 code e.g. GBP
EXAMPLE

The following example shows an HTTP POST request for a transaction lookup

REQUEST:
POST /transaction_lookup HTTP/1.1
Host: api.paythru.com
Content-Length: 94
Content-Type: application/x-www-form-urlencoded
api_key=xxxxxxx&api_password=xxxxxxxx&version=5&trans_key=mhjdbfkj32bk23j423jkndf8987s
RESPONSE:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 286

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
<status>Success</status>
<token>df338jd</ token >
<value>10.00 </ value >
<currency>GBP</ currency >
</paythruResponse>

2.9 canceltoken method

The cancel token method is used to cancel a token that is no longer needed. Once cancelled, the users will get a token-expired message if they try to redeem the token.

REQUEST

Request URL: /canceltoken

Name Description Format (max characters)
api_key* The key is used to identify the requesting merchant, which is supplied to the merchant by Paythru. Char (32)
api_password* The password for the API key, which is supplied to the merchant by Paythru. Char (32)
version* The version of the API. Currently on 5. Integer
tokenid * The token id of the token to cancel. This id is returned by the gettoken method when a token is created. String

*Denotes required parameter

RESPONSE

The response content is returned as XML formatted data. The data returned will denote if the token was cancelled successfully. See the Error Codes appendix for failure cases.

Name Description
status Status of the transaction. 1='success' and 0='failure'
EXAMPLE

The following example shows an HTTP POST request for a cancel token

REQUEST:
POST /canceltoken HTTP/1.1
Host: api.paythru.com
Content-Length: 94
Content-Type: application/x-www-form-urlencoded
api_key=xxxxxxx&api_password=xxxxxxxx&version=5&tokenid=mhjdbf
RESPONSE:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 286

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
<status>1</status>
</paythruResponse>

3.0 Appendix

3.1 Error codes

If the request sent to the API is not valid, the Paythru API server will respond with an error code within the returned XML.

EXAMPLE ERROR RESPONSE:
<?xml version="1.0" encoding="utf-8" ?>
<paythruResponse>
<errorcode>1</errorcode>
</paythruResponse>
Error Code Description
1 No data sent
3 No merchant key sent (or invalid key)
5 No valid item data or valid user data passed
6 Missing or invalid password
7 Item name passed without matching price tag (or price passed without matching item name)
8 Item name or price missing for the supplied item.
9 Invalid token supplied for update.
10 Currency provided either not valid or not supported by merchant.
11 Version number not supplied or not valid.
12 Attempt to load an alternative merchant not supported.
13 Loading an alternative merchant failed, hierarchy not satisfied.
14 Applet does not exist or does not belong to the specified child merchant.
15 Applet does not exist or does not belong to the specified parent merchant.
16 Message and/or mobile number missing from SMS.
17 House number/name and/or postcode missing from address lookup request.
18 Previous transaction Key is missing from the request.
19 The value of the transaction is missing from the request.
20 The type of the transaction is missing from the request.
21 Refund transaction failed.
22 Repeat transaction failed.
23 Capture transaction failed.
24 Cancel transaction failed
xxxxxx15 Required Parameters missing
xxxxxx30 Permission denied to access this function
xxxxxx25 Cannot find API settings for merchant
xxxxxx31 Invalid Frequency
xxxxxx32 Invalid Interval
xxxxxx66 Invalid token id
xxxxxx93 Invalid terminal key
xxx Unhandled error.

3.2 Callback data

The callback data is sent to the callback URL specified in the gettoken method. The data would be a post data with the key-value pair.

3.2.1. PAYMENT METHOD - CARD

Callback data is sent to the merchant when token is used for a purchase. The table below lists the callback data sent to the merchant for card transactions

Callback index Description
personTitle Title of customer
personFirstName First name of customer
personSurname Surname of customer
personMobileNumber Mobile number of customer
personHomePhone Home Phone of customer
personEmail Email of customer
addressPropertyName Property name of customer address
address1 Address 1 of customer address
address2 Address 2 of customer address
address3 Address 3 of customer address
addressTown Town of customer address
addressCounty County of customer address
addressPostcode Postcode of customer address
addressCountry Country of customer address
transactionKey Transaction Key to identify the transaction
transactionTime The time of transaction
transactionStatus The status of the transaction (Appendix 4.3)
transactionValue The total value of the transaction (Formatted in the standard currency denomination)
transactionType The type of transaction (Appendix 4.4)
transactionCurrency The currency of the transaction (in isoCode)
transactionAuthCode The auth code returned by the bank
transactionClass Some identifier to the transaction
transactionReference The transaction reference passed in gettoken method
transactionToken The token id of the token used for this transaction
items0name Item name
items0price Item price
items0quantity Item quantity
items0reference Item reference
cardLastFour The last 4 digits of the card number
cardExpiryMonth The expiry month of the card
cardExpiryYear The expiry year of the card
transactionIpAddress IP address of the user

Note: If multiple items are present in the basket, they will be listed in the callback data as items0name, items1name, etc.

3.3 Transaction status for callback

Possible transaction status in the callback

Transaction Status Description
Success If the transaction went through successfully.
Failure If the transaction failed; this can be because of any reason such as invalid card, insufficient funds, etc.
Pending If the transaction is taking too long to respond, the bank returns a state indicating that the transaction is still in progress.
Connection Error If is any issue in the network while communicating with the bank or the bank's server is not responding.
Blacklisted If the transaction was placed with a card that was blacklisted by the merchant. This feature can be enabled for a merchant on request.

3.4 Transaction type for callback

Possible transaction type in the callback

Transaction Type

3.6 Transaction status for transaction lookup

Possible transaction status in transaction lookup function

Transaction Status Description
Success The transaction was processed successfully.
Approved The transaction was processed successfully.
Failed If the transaction failed; this can be because of any reason such as invalid card, insufficient funds, etc.
Pending If the transaction is taking too long to respond, the bank returns a state indicating that the transaction is still in progress.
Connection Error If is any issue in the network while communicating with the bank or the bank server is not responding.
Blacklisted If the transaction was placed with a card that was blacklisted by the merchant. This feature can be enabled for a merchant on request.

3.7 A note on success_url and auto_redirect

When using the gettoken() method of the Enterprise API you can provide a success_url which the user is redirected back to on payment completion. If you do not set auto_redirect, or supply auto_redirect as 0, the user will be presented with a payment success screen hosted by Paythru upon which a link to success_url will be present for the user to click.

If, however, you set the auto_redirect value to 1 then the user will be immediately redirected to the supplied success_url.

Setting auto_redirect to 1 also allows us to append the resulting Transaction Key to the success_url when redirecting the user

So, if your URL is supplied to us as:

https://www.example.org/paythru/successfulPayment?t=1234567890

We will actually redirect the user to:

https://www.example.org/paythru/successfulPayment?t=1234567890&transKey=mhjdbfkj32bk23j423jkndf8987s

Whilst it is possible for you to maintain a session either by appending your own identifier to the success_url or by making use of cookie-based sessions, you can also send the transactionKey into the transaction_lookup function to find out more about the transaction which was placed.

3.8 Payment Source


4.0 Revision History

4.1 Revision History of Version 5

Revision Changes Published
1 First issue of v5 Apr 2012
2 Supports schedule payments
Added transaction category
May 2012
3 Callback Appendix added May 2012
3.1 Changes in the documentation:
gettoken function now returns 'token_start' and 'token_expiry' instead of 'starts' and
'expires'.
schedule_start explained more clearly.
Jun 2012
3.2 Schedule description has notes about the HTML tags that it allows. Jun 2012
4 New function added - transaction lookup Jul 2012
4.1 Amended introduction. Jul 2012
5 Added a field 'trans_reference' for gettoken method. Jul 2012
6 Added fields 'country' for gettoken method. Jul 2012
6.1 Added Appendix for transaction status and transaction type. Jul 2012
7 Added new function canceltoken
Added new function eft_lookup
Added new parameter in gettoken function 'payment_method'
Added new callback Appendix
Aug 2012
8 Added new payment method 'instanteft'
Detailed explanation about schedule payments.
Nov 2012
8.1 - 8.2 Changed document footer.
Grammatical changes.
May 2013
8.3 Internal changes to SMS handler Jun 2013
9 Disabled Scheduled payments Jul 2013
10 Added 3DSecure parameters and callback values Jul 2013
11 Added a field 'terminal_key' for changing an account Oct 2013
11.1 Added Appendix 4.7 Nov 2013
12 Removed references to EFT. Reallocated appendix 4 items, appendix 4.7 newly added Sep 2016
13 Simplified introductory text, renumbered chapters, added paymentSource, removed AMT, added Approved as a possible transStatus response for callbacks Oct 2019