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 (50) |
| 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) |
| 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. If set to 'VerifyCard' then the generated token will be used to collect and verify a card. |
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) |
| recurrence_type | For 3DSecure transactions, the recurrence type of the payment should be set. See Appendix 3.9 for more details. | single/first |
| terminal_key | Available values for this field are available either via your reporting interface access or from Paythru Tech Support. The appropriate key should be provided to nominate the account that should be used for the transaction. You may be able to omit this field if you have a terminal nominated as default, but it is recommended that the field is always supplied. | Char |
| paymentScheduleReference | If the token is collecting a card for a schedule or processing a declined scheduled payment add the linked schedule reference here. See the scheduled payments API for more detail. | Char |
| paymentScheduleRunDate | If the token is processing a declined scheduled payment add the linked schedule run date here. See the scheduled payments API for more detail. | yyyy-mm-dd |
| tokenAction | Flag the action the token is performing. This has specific use-cases and should not be used otherwise. See Appendix 3.10. |
Use-specific values |
*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
¤cy=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 customer's 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. British Sterling (£) uses '.' as the decimal separator ("1,000.00"). Euro (€) uses ',' as the decimal separator ("1.000,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: 178
<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
<status>Success</status>
<token>df338jd</token>
<value>1,000.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¶
- Auth
- PreAuth
- Release
- CancelPreAuth
- Refund
- Credit
- 3DSecureCheck
- 3DSecureAuth
- CaptureRelease
- Unknown
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¶
- ecomm - E-commerce
E-commerce transactions are designed for Merchants who which to accept payments via a website, such as a shopping cart payment. E-commerce transactions can use advance fraud detection such as 3-D Secure.
Due to MasterCard stipulations the Gateway will not allow Maestro cards to be for new e-commerce transactions without the use of 3-D Secure.
- moto - Mail Order/Telephone Order
Mail Order/Telephone Order transactions are designed for Merchants who wish to build their own virtual terminal system to enter remote order details. You will need to ensure when processing such transactions, that their Acquirer understands the transaction is a MOTO transaction. The reason for this is because the Acquirer will have different requirements in order to classify a transaction as secure, e.g. 3-D Secure is often required for internet transactions, but impossible for MOTO transactions.
3.9 Recurrence Type¶
In order to comply with scheme regulations it is necessary to flag to Paythru whether any given transaction is intended to be the first in a sequence, and whether any transaction is placed with stored credentials.
| Value | Result |
|---|---|
| single | The transaction is intended to be a one-off. Use this if you have no intention to store the card for future use. |
| first | The transaction is intended to be the first in a sequence of transactions. Use this if you plan to store the card for future re-use. If you intend to store the card for future use, you must make this clear to the user. |
3.10 Token Action parameter¶
The token action parameter has specific use-cases. This should be used when creating enterprise tokens to work with payment schedules.
| Value | Description |
|---|---|
| collectCardForSchedule | The user will be able to view a schedule description and make a payment based on the item's value. Upon successful payment, the user's card will be saved for future scheduled payments corresponding to the schedule. |
| updateCardForSchedule | After a successful payment, the card against the payment schedule will be replaced with the new card |
| retryDeclinedScheduledPayment | After the payment is successful, the scheduled payment run that had failed would be marked as complete. |
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 |
| 14 | Increased trans_reference maximum length from 32 to 50 | April 2020 |
| 15 | Updated terminal_key usage description. Added linking fields for new payment schedules API. | April 2021 |
| 16 | Added Appendix for token action parameter on get token method. | Feb 2024 |