Enterprise API

Version 5

Back to Developers

Enterprise API

Version 5

1.0 Introduction

Paythru is a specialist payments provider that gives merchants everything they need to start making money from mobile or desktop payments. Paythru can be used for every conceivable product or service, from charitable donations, to clothes, food and holiday insurance.

Paythru is a payment system that works on all mobile handsets and browsers, on all networks and with every bank, anywhere in the world. There is no limit to the amount a customer can spend using Paythru, other than how much they have in the bank or on their credit card.

Paythru provides Level 1 PCI DSS compliant mobile payment service. Our compliance means we can transact and store customers' card details securely, so they don't need to pre-register or have an e-wallet to transact.

Merchants with are able to sell goods, services & content to their customers without having to handle the card details directly. Owing to Paythru's PCI compliant environment, user's card details are optionally stored securely upon completion of a transaction, allowing users to send repeat payment instructions from their devices, without re-sending card details.

1.1 Scope

This document describes the web services available to merchants within the Paythru Enterprise suite of products. The document does not discuss any credit and debit card processing methods, as, within the Paythru Enterprise suite, the card payments are handled internally.

This API does offer the means to (for example) create "Add to basket" and "Buy now" buttons for their websites or embed "Buy now" URL links within SMS messages. These buttons will refer the user to Paythru's Hosted Payment Pages. This API also offers methods to deal with repeats and refunds of existing transactions and methods to send SMS messages and perform address lookups.

Merchants wishing to process card details captured via their own interfaces should refer to the Paythru Gateway API.

The gettoken method refers to Paythru Payment Tokens. Paythru Payment Tokens represent an instance of a proposed purchase of items between a user and a merchant. A Paythru Payment Token can be created using the Paythru Enterprise API, and then passed to the user in the form of a URL which is redeemed by the user. Paythru Payment Tokens should not be mistaken to be a means of payment.

1.2 Audience

This document is aimed largely at developers tasked with integrating 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 Paythru Enterprise API should have a good understanding of HTTP, XML, as well as a server-side scripting language to make calls 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 deposit funds into their nominated merchant account. Test accounts are available to this API. The URL, username and password for the test account will be different to the live account. No payments are actually taken in the test account.

Live URL: https://api.paythru.com

Test URL: https://api.demo.paythru.com

All the examples in the document use the live server URL. To use the sandbox account, the format of the request will be the same except for the change in the URL.


2.0 Typical Usage

2.1 Get token method

Tokens generated using the Enterprise API are typically created just prior to sending out an SMS or when a user clicks a "Buy now" button on a merchant's website. Merchants are also able to set tokens up with data other than the user and the items. For example, the token may also contain a limit to the number of times it may be redeemed. It also may be set to expire after a certain time; this may be useful for an outbound campaign that contains an offer only valid for that day.

WEBSITE

The following example identifies the flow of a typical user buying an item from a merchant's mobile website using the Paythru Enterprise API.

  • Merchant's web server delivers mobile web page with "Buy now" buttons.
  • User clicks "Buy now" against a product.
  • Merchant's web server calls "gettoken" method of Paythru Enterprise API with details of product (e.g. name, price, barcode) and details of user (where known) (e.g. name, mobile phone number, address).
  • Paythru API server responds with Paythru Payment Token.
  • Merchant web server sends HTTP Redirect to user, redirecting them to the token URL. (Paythru Hosted Payment Pages)
  • User either completes the required payment form or logs in. (if account holder)
  • Optionally some data about the transaction is sent to a callback URL supplied when generating the token
  • Success/Failure message delivered to user.
  • If not account holder, user creates account. (optional)
  • Customer is returned to Merchant's website.

If a merchant wishes to add "Add to basket" functionality, the merchant should avoid generating the token until they have collected the complete set of items and the user chooses to 'check-out' their 'basket'.

MOBILE APPLICATION

The following example identifies the process flow of a merchant with a mobile application making purchase within the application.

  • User clicks "Buy now" inside the application.
  • The application makes a request to the Merchant's web server with the details of the product.
  • Merchant's web server calls "gettoken" method of Paythru Enterprise API with details of product (e.g. name, price, barcode) and details of user (where known) (e.g. name, mobile phone number, address).
  • The Paythru API server responds with a Paythru Payment Token.
  • The merchant's web server returns the token to the application.
  • The application opens up the mobile web browser, loading the token URL (Paythru Hosted Payment Pages). Please contact us for implementation details.
  • User either completes the required payment form or logs in. (if account holder)
  • Optionally some data about the transaction is sent to a callback URL supplied when generating the token
  • Success/Failure message delivered to user.
  • If not account holder, user creates account. (optional)
  • User is returned to Merchant's application, along with the transaction key. Where possible, this is done automatically. Please contact us for implementation details.
  • Merchant's application makes an API request to check the status of the transaction to confirm it was a "success". See section 2.8 and 3.8 for details.

OUTBOUND SMS

The following example identifies the process flow of a merchant sending an outbound SMS campaign to encourage users to buy products.

  • The merchant makes a call to the Paythru Enterprise API from their CRM system detailing the user and the items.
  • The Paythru API server responds with a Paythru Payment Token.
  • The merchant makes a call to the Paythru Enterprise API (or their choice of SMS Gateway Provider's API) to send the SMS to the user with the token URL embedded within the body of the message.
  • The user receives the SMS and clicks the link within the SMS.
  • The user is directed to Paythru's Hosted Payment Pages and with the items in their basket and their personal details pre-populated in the payment form.
  • The user purchases the item
  • Optionally some data about the transaction is sent to a callback URL supplied when generating the token

If items are 'virtual' such as mobile content, the user may be directed to the merchant's mobile website after payment to download.

2.2 Repeat method

After using a Paythru Payment Token to make a transaction the repeat method may be used to do another transaction on the same card details as the original. An example is as follows.

  • The merchant needs to charge the user for a subsequent transaction.
  • Using the previous transaction's unique key, the merchant does a repeat transaction.
  • The merchant then saves the new transaction's unique key for future use such as a refund.

2.3 Refund transaction

After using a Paythru Payment Token to make a transaction or doing a repeat transaction, the refund method may be used to refund the full or less than the full amount of the original transaction. An example is as follows.

  • The merchant needs to refund the user for a previous transaction.
  • Using the previous transaction's unique key, the merchant does a refund transaction.
  • The merchant then saves the new transaction's unique key for future use such as repeats.

2.4 Capture transaction

If the merchant has made a pre-auth transaction with Paythru either through a Hosted Payment Pages transaction or some other means, they will likely wish to capture the reserved funds at some point. Often used where the availability of a purchase is subject to change.

  • The merchant has a pre-auth transaction with reserved funds
  • Using the previous transaction key, the merchant performs a capture of the funds (note: the amount captured must be equal to or less than the reserved amount)
  • The merchant then saves the new transaction key for future use.

2.5 Cancel transaction

If the merchant has made a pre-auth transaction with Paythru either through a Hosted Payment Pages transaction or some other means, they may wish to cancel the reservation of funds. Often used where the requested item is no longer available.

  • The merchant has a pre-auth transaction with reserved funds
  • Using the previous transaction key, the merchant performs a cancel of the funds.
  • The merchant may choose to save the transaction key for record purpose

2.6 Send SMS

If the merchant has SMS enabled on their account, they can use our SMS service to distribute Payment Tokens generated by this API to their users.

  • The merchant needs to send out an SMS to a user or group of users, such as an alert that goods have been shipped or information about an offer.
  • Using the user's mobile phone number, the merchant sends the SMS.

2.7 Address lookup

When not using the Paythru's payment pages the merchant might want to look up an address. An example is as follows.

  • The merchant needs to find a full address from the house name/number and postcode.
  • The merchant provides the house name/number to Paythru by means of the address lookup method.
  • Paythru returns the full address to the merchant.

2.8 Transaction lookup

The merchant might want to look up a transaction key to check its status, transaction value, etc. An example is as follows.

  • The merchant needs to find if a transaction is success
  • The merchant provides the transaction key to Paythru by means of the transaction lookup method.
  • Paythru returns the details of the transaction.

2.9 Cancel token method

The merchant might want to cancel a token so that users will not be able to redeem the token again. A typical use is as follows:

  • The merchant generates a token for a particular item using the gettoken method.
  • The merchant realises that the item is no longer in stock and wants to prevent users from redeeming the token to purchasing the item.
  • The merchant passes the token id to the cancel token method.
  • Paythru sets the token to expire and returns a success.
  • When the user redeems the token, they will get a message that the token is expired.


3.0 Methods

The API accepts HTTP requests with SSL (HTTPS) to the Request URL with the parameters passed as POST name/value pairs.

3.1 gettoken method

The gettoken method is used to set up a payment with Paythru prior to referring the customer to Paythru's hosted payment pages. A callback data is sent to the merchant when token is used for a purchase.

REQUEST

Request URL: https://api.paythru.com/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 send. 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 buy the items. If this parameter is not provided, the default value will be the merchants default value, usually set to 1 week. Unix timestamp
token_uses The number of times a token can be used for purchase. The internal counter is only incremented when the token's items are purchased. If this parameter is not provided, the default value will be the merchants default value, usually set to 1. The Token uses can be set to infinite by providing the value '-1' 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 redemptions for the life of the token. Integer [max value 127]
success_url The URL the customer will be directed to after successfully purchasing the token's items. If this parameter is not provided, the default value will be the merchant's default value. See appendix 4.7 for more detail. String
cancel_url The URL that users may return to if they wish to cancel their purchase. If this parameter is not provided, the default value will be the merchant's default value. String
currency The currency that the token items may be paid for 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 4.2) and also our reporting interfaces. String
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. 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. 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. 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. Char (16)
salutation The salutation of the user to be set in the token e.g. Mr, Miss or Dr. Char (10)
first_name The first name of the user to be set in the token. Char (32)
surname The surname of the user to be set in the token. Char (32)
email The email of the user String
date_of_birth The date of birth of the user to be set in the token. This should be supplied in the format DDMMYYYY e.g. 30061970 Char (8)
mobile_phone The mobile 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. 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. Accepts only Alpha 2 code of ISO 3166-1. http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm 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. String
redemption_redirect_url The URL the user will be redirected to when the token is redeemed String
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. String
payment_method The method of payment. Possible values are card, and amt. Defaults to card. See Appendix 4.6 for details. String
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'. It denoted the category of the transaction. Possible values are 'donation', 'debt', 'booking'. Char (10)
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 us 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. String

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

3.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: https://api.paythru.com/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>

3.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: https://api.paythru.com/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>

3.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: https://api.paythru.com/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>

3.5 cancel method

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

REQUEST

Request URL: https://api.paythru.com/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>

3.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: https://api.paythru.com/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>

3.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. This method does NOT interface with Paythru's hosted payment pages at all.

REQUEST

Request URL: https://api.paythru.com/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>

3.8 transaction_lookup method

The transaction lookup method is used to retrieve details about the transaction when you supply the transaction key. This method does NOT interface with Paythru's hosted payment pages at all.

REQUEST

Request URL: https://api.paythru.com/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>

3.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 when they try to redeem the token.

REQUEST

Request URL: https://api.paythru.com/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>


4.0 Appendix

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

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

4.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
3DSecureInvoked Indicates whether a 3Dsecure transaction was attempted

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

4.2.2 PAYMENT METHOD - AMT

The table below lists the callback data sent to the merchant for AMT 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
payDResponseCode The response code from payD
payDResponseMessage The response message from payD
items0name Item name
items0price Item price
items0quantity Item quantity
items0reference Item reference
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.

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

4.4 Transaction type

Possible transaction type in the callback

Transaction Type
Auth
PreAuth
Release
CancelPreAuth
Refund
Credit
3DSecureCheck
3DSecureAuth
CaptureRelease
Unknown

4.5 Payment method

The payment_method parameter for the gettoken function accepts 3 values: "card", "amt" and defaults to 'card' if a value is not provided.

CARD

If the payment method is set to 'card' the user will be asked to enter their card details and this will be used to perform the transaction in as secure environment.

AMT

Authenticated Mobile Transaction is mainly used in South Africa where SIM cards and pin technology is used to turn mobile phones into secure encrypted point-of-sales terminals.

4.6 Transaction status for transaction lookup

Possible transaction status in transaction lookup function

Transaction Status Description
Success If the transaction went through 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.

4.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 is immediately sent directly 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 that you 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.

5.0 Version History

5.1 Version History

Version Changes Published
1 First issue Oct 2009
2 Second issue Apr 2010
3 Added applet and callback URL parameters to gettoken. Not Published
4 Added repeat transaction Added refund transaction Added SMS sending Added address lookup List of error codes expanded with codes 12 to 16 Not Published
5 Added cancel transaction Added capture transaction Added token pre-auth support Added schedule payments Added transaction category Callback appendix added Cancel token function added Apr 2012

5.2 Revision History of Version 5

Version 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