Payment Schedule API¶
Version: 3
1.0 Overview¶
1.1 API URL¶
2.0 API Overview¶
This API is web service. All functionality of the API is accessed by performing HTTP POST method requests directly from the merchant's web servers using an SSL connection.
2.1 API Requests¶
The Paythru Payments API accepts HTTP POST method requests using an SSL connection (HTTPS). The key-value parameters sent in body of the request must be encoded using the application/form-url-encoded Internet media type.
The data returned in the response to the HTTP request can be encoded in a choice of either XML or JSON encoding.
The request must be submitted from the merchant's servers to Paythru's servers using the URL below. Under no circumstances should requests be made to the API directly from the customer's web browser or mobile application.
2.2 Request URL¶
| Environment | URL |
|---|---|
| Live | https://ws.paythru.com |
| Staging (or sandbox) | https://ws.demo.paythru.com |
The examples in the document use relative URLs, which must be prepended with a URL from the above table depending on the environment in use. To use the sandbox account, the format of the request will be the same but you will need to change the URL you send requests into. Note that credentials are not shared between Staging and Live.
Requests to the Paythru Scheduled Payments API should be sent to a URL constructed in the following manner:
/v{version number}/schedule/{method name}/{response encoding}
The {version number} segment within the URL should be replaced with the version of the API. The current version of the API is 3.
The {method name} segment within the URL should be replaced with the method of the API being requested.
The last segment of the URL - {response encoding} indicates whether the response from the web service should be encoded in XML or JSON.
Example URL¶
For example, a request to the auth method of version 3 of the API with the response encoded in JSON should be sent to the following URL:
/v3/schedule/auth/json
Please note that if the response encoding segment of the URL is not provided, the response will be encoded in XML.
2.3 API Responses¶
Requests to the API processed successfully will be responded to with a 200 (OK) HTTP response code. The data contained within the body of the response will be in either XML or JSON format as requested. Requests that are unable to be processed will be responded to with either the HTTP response code 400 (Bad Request), 401 (Unauthorized) or 403 (Forbidden) depending on the nature of the error.
XML encoded responses¶
The response parameters within an XML encoded response will be returned as XML elements, the name of which will be the parameter name, and the value contained within, its associated value. All the response data elements will be contained within a root element named 'paythruResponse'.
<?xml version="1.0" encoding="UTF-8"?>
<paythruResponse>
<responseParameter>Response value</responseParameter>
...
</paythruResponse>
JSON encoded responses¶
The response parameters within a JSON encoded response will be returned as properties of a single JSON object, the name of which will be parameter name and the value, its associated value.
{"responseParameter":"response Value", ...}
2.4 Authentication¶
All requests made to the API require authentication. Two request parameters (apiKey and apiPassword) are required to be sent with each request to the service. These parameters will be provided by Paythru when the account is created.
If more than 5 requests are made containing invalid credentials within the same day, Paythru will not accept any further requests from the originating IP address for a period of one minute. After 10 requests failing authentication, the IP address will be blocked for 5 minutes.
2.5 Signing the request¶
All requests to this API must be signed by constructing a hash of the request parameters and the shaKey (provided by Paythru) using the following steps:
- Arrange all request parameters in alphabetical order by parameter name (not including the shaSignature parameter)
- Remove parameters with no value
- Concatenate the parameter name, an equals symbol, the parameter value and your shaKey
- Concatenate all resulting strings in order
- Hash the resulting string using SHA512
See gateway API documentation for more details about signing the request
2.6 API integration and testing¶
Upon request, Paythru can provide credentials to an API test service suitable for integration development work and testing. The test service acts as an exact replica of the live API although payment results are simulated and no transactions are actually submitted to the banks/card schemes.
Please contact Paythru to apply for test service credentials or for any further information regarding the service.
2.7 API Throughput¶
It is important to note that Paythru API's have a default maximum throughput of 100 requests per minute. This limit is flexible, and designed to protect the platform rather than limit your genuine usage. If you expect to exceed this limit because of a high number of users, or because you are doing batch processing with asynchronous calls or multiple threads (single, synchronous, threads we would not expect to encounter this limit) please contact Paythru support to talk through your expectations so we can adjust your throughput limits accordingly.
3.0 Methods¶
3.1 Create¶
The create method is used to create a new payment schedule
URL
/v3/schedule/create/json
Request parameters
| Name | Description | Format (max characters) |
|---|---|---|
| apiKey† | The API Key provided by Paythru used for authentication. | Alpha-numeric characters |
| apiPassword† | The API Password provided by Paythru used for authentication. | Alpha-numeric characters |
| description | A description for the schedule | Alpha-numeric characters (255) |
| merchantReference | The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. | |
| repeatPattern† | The repeat pattern for the schedule (See Appendix 5.2) | |
| startDate† | The date to start the schedule. This has to be a date in the future | yyyy-mm-dd |
| endDate | The date to end the schedule | yyyy-mm-dd |
| maximumRuns | Maximum runs allows in the schedule | Integer |
| currency† | The ISO 4217 currency (e.g. GBP) that the schedule should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. | 3 alpha characters |
| paymentAmount‡ | The amount taken for each schedule run. The value should be specified in the currency's smallest subunit. Either payment amount or total amount should be set. | Integer |
| totalAmount‡ | The total amount to be collected using the schedule. Either payment amount or total amount should be set. If only total amount is set, the payment amount is calculated using the end date or maximum runs. | Integer |
| manualPayments | Manual payment runs that is different to the schedule. E.g. 2021-03-15:1000,2021:05:03:500In this example, £10 will be taken on 15th Mar 2021 and £5 on 3rd May 2021 |
|
| paymentExceptions | Schedule dates that should be excluded E.g. 2021-02-15,2021-03-15In this example, the schedule run will be skipped for 15th Feb 2021 and 15th Mar 2021 |
|
| cardKey | The reference of the card token to be used for the scheduled payments. If card key is not set, the schedule is created with a status of 'pending' and it won't be started | Alpha numeric and symbol characters |
| terminalKey | The terminal which should be used for the scheduled payments | Alpha numeric and symbol characters |
| campaignKey† | The campaign to link to the schedule | Alpha numeric characters |
| shaSignature† | The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature | 128 Alpha numeric characters |
† denotes a required field
‡ denotes a conditional field, read the description column to find out the details
Response parameters
| Name | Description | Format |
|---|---|---|
| reference | The payment schedule reference | Alpha-numeric (16) |
| status | The status of the reference (See Appendix 5.3) | Integer |
Example response
{
"reference":"WsM4ftuj9OuFw5TR",
"status":0
}
3.2 Edit¶
This method is used to edit an existing schedule
URL
/v3/schedule/edit/json
Request parameters
| Name | Description | Format |
|---|---|---|
| apiKey† | The API Key provided by Paythru used for authentication. | Alpha-numeric characters |
| apiPassword† | The API Password provided by Paythru used for authentication. | Alpha-numeric characters |
| reference† | The payment schedule reference to be updated | Alpha-numeric characters (16) |
| description | A description for the schedule | Alpha-numeric characters (255) |
| merchantReference | The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. | |
| repeatPattern | The repeat pattern for the schedule (See Appendix 5.2). This cannot be changed once the schedule has started. | |
| startDate | The date to start the schedule. This has to be a date in the future. This cannot be changed once the schedule has started. | yyyy-mm-dd |
| endDate | The date to end the schedule | yyyy-mm-dd |
| maximumRuns | Maximum runs allows in the schedule | Integer |
| currency | The ISO 4217 currency (e.g. GBP) that the schedule should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. This cannot be changed once the schedule has started. |
3 alpha characters |
| paymentAmount | The amount taken for each schedule run. The value should be specified in the currency's smallest subunit. Either payment amount or total amount should be set. | Integer |
| totalAmount | The total amount to be collected using the schedule. Either payment amount or total amount should be set. If only total amount is set, the payment amount is calculated using the end date or maximum runs. | Integer |
| manualPayments | Manual payment runs that is different to the schedule. E.g. 2021-03-15:1000,2021:05:03:500In this example, £10 will be taken on 15th Mar 2021 and £5 on 3rd May 2021 |
|
| paymentExceptions | Schedule dates that should be excluded E.g. 2021-02-15,2021-03-15In this example, the schedule run will be skipped for 15th Feb 2021 and 15th Mar 2021 |
|
| cardKey | The reference of the card token to be used for the scheduled payments. If the schedule status is 'pending' and a valid card key is provided, the status is set to 'not started'. | Alpha numeric and symbol characters |
| terminalKey | The terminal which should be used for the scheduled payments | Alpha numeric and symbol characters |
| campaignKey | The campaign to link to the schedule | Alpha numeric characters |
| shaSignature† | The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature | 128 Alpha numeric characters |
† denotes a required field
Response parameters
| Name | Description | Format |
|---|---|---|
| result | "OK" will be returned as the result if the request was successful. (Unsuccessful requests will result in an error.) | 2 alpha characters |
Example response
{
"result":"OK"
}
3.3 Look up¶
The lookup method is used to get details of an existing schedule
URL
/v3/schedule/lookup/json
Request parameters
| Name | Description | Format (max characters) |
|---|---|---|
| apiKey† | The API Key provided by Paythru used for authentication. | Alpha-numeric characters |
| apiPassword† | The API Password provided by Paythru used for authentication. | Alpha-numeric characters |
| reference† | The payment schedule reference | Alpha-numeric characters (16) |
| shaSignature† | The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature | 128 Alpha numeric characters |
† denotes a required field
Response parameters
| Name | Description | Format |
|---|---|---|
| reference | The reference of the schedule | |
| description | Description of the schedule | |
| repeatPattern | Repeat pattern (See Appendix 5.2) | |
| repeatPatternString | Human readable text for repeat pattern (See text in Appendix 5.2) | |
| startDate | Start date of the schedule | yyyy-mm-dd |
| endDate | End date of the schedule | yyyy-mm-dd |
| maximumRuns | Maximum number of runs allowed for the schedule | Integer |
| currency | The ISO 4217 currency (e.g. GBP) that the schedule is conducted in | 3 alpha characters |
| paymentAmount | The amount set to be taken for each schedule run | Integer |
| totalAmount | The total amount set to be collected using the schedule | Integer |
| calculatedPaymentAmount | If payment amount is not set, we would calculate the amount for each run. If payment amount is set, this field would return null | Integer |
| calculatedTotalRepaymentAmount | If total amount is not set, we would calculate the total amount if there is an end date or maximum runs set. | Integer |
| totalIncludesManualPayments | ||
| cardKey | The card key linked to the payment card | Alpha-numeric characters |
| terminalKey | The terminal which is used for the scheduled payments | |
| totalRuns | Total number of runs in the schedule. If there is no end date or maximum runs defined, this field would return null | Integer |
| completedRuns | Number of runs that are completed | |
| nextRunAt | The time of upcoming run | Unix timestamp |
| nextRunAmount | The amount taken for the next run | Integer |
| createdAt | The time the schedule was created | Unix timestamp |
| cardStatus | ||
| alertMessage | ||
| status | The current status of the schedule | |
| extraParameters | An array containing optional parameters linked to the schedule | |
| manualPayments | An array containing a list of manual payments for the schedule. Each item in the array would show the date and amount for the scheduled run | |
| paymentExceptions | An array containing the exceptions to the schedule | |
| campaignKey | The campaign associated with the schedule | |
| futureRuns | An array containing a list of the upcoming runs (max 10 runs). Each item in the array would show the date and amount for the scheduled run | |
| finalRunAt | The time of the final run of the schedule | Unix timestamp |
Example response
{
"reference":"WsM4ftuj9OuFw5TR",
"description":"",
"repeatPattern":"month",
"repeatPatternString":"Month - Specific date",
"startDate":"2020-06-27",
"endDate":null,
"maximumRuns":"36",
"currency":"GBP",
"paymentAmount":null,
"totalAmount":50000,
"calculatedPaymentAmount":1363,
"calculatedTotalRepaymentAmount":null,
"totalIncludesManualPayments":true,
"cardKey":"34babc03-345d-6c65-cd56-3b2854c19ab7",
"terminalKey":"default",
"totalRuns":34,
"completedRuns":4,
"nextRunAt":1601182800,
"nextRunAmount":1363,
"createdAt":1593077137,
"cardStatus":null,
"alertMessage":"2",
"status":"1",
"extraParameters":null,
"manualPayments":[
{
"date":"2020-07-15",
"amount":5000
}
],
"paymentExceptions":[
"2020-12-27",
"2021-12-27",
"2022-12-27"
],
"campaignKey":null,
"futureRuns":[
{
"date":1601182800,
"amount":1363
},
{
"date":1603774800,
"amount":1363
},
{
"date":1606453200,
"amount":1363
},
{
"date":1611723600,
"amount":1363
},
{
"date":1614402000,
"amount":1363
},
{
"date":1616821200,
"amount":1363
},
{
"date":1619499600,
"amount":1363
},
{
"date":1622091600,
"amount":1363
},
{
"date":1624770000,
"amount":1363
},
{
"date":1627362000,
"amount":1363
}
],
"finalRunAt":1685163600
}
3.4 Get future payments¶
This method is used to get the date and amount of the upcoming scheduled payments.
URL
/v3/schedule/getFuturePayments/json
Request Parameters
| Name | Description | Format (max characters) |
|---|---|---|
| apiKey | The API Key provided by Paythru used for authentication. | Alpha-numeric characters |
| apiPassword | The API Password provided by Paythru used for authentication. | Alpha-numeric characters |
| reference | The payment schedule reference | Alpha-numeric characters (16) |
| limit | Maximum number of payments dates to be returned (defaults to 10) | Integer |
| offset | Number of results to be skipped from the start (defaults to 0) | Integer |
| shaSignature | The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature | 128 Alpha numeric characters |
Response Parameters
| Name | Description | Format |
|---|---|---|
| futureRuns | Array containing details of the upcoming payment details | Alpha-numeric characters |
| futureRuns > date | The date-time of the scheduled payment | Unix timestamp |
| futureRuns > amount | The payment amount to be taken on the day | Integer |
Example response
{
"futureRuns":[
{
"date":1601182800,
"amount":1363
},
{
"date":1603774800,
"amount":1363
},
{
"date":1606453200,
"amount":1363
},
{
"date":1611723600,
"amount":1363
},
{
"date":1614402000,
"amount":1363
}
]
}
3.5 Get runs¶
This method is used to get the details of the completed runs of the schedule
URL
/v3/schedule/getRuns/json
Request parameters
| Name | Description | Format (max characters) |
|---|---|---|
| apiKey† | The API Key provided by Paythru used for authentication. | Alpha-numeric characters |
| apiPassword† | The API Password provided by Paythru used for authentication. | Alpha-numeric characters |
| reference† | The payment schedule reference | Alpha-numeric characters (16) |
| shaSignature† | The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature | 128 Alpha numeric characters |
Response parameters
| Name | Description | Format |
|---|---|---|
| runs | Array containing details of each run | |
| runDate | The date of the scheduled payment of the run | yyyy-mm-dd |
| amount | The amount of the scheduled payment | Integer |
| status | Current status of the run (See Appendix 5.4) | |
| transactions | Array containing details of the transaction linked to the run | |
| checkoutKey | The checkout key linked to the transaction | Alpha-numeric characters |
| amount | The amount attempted for the transaction | Integer |
| transactionKey | The transaction key | Alpha-numeric characters (32) |
| message | The result of the transaction | Alpha-numeric characters |
| timestamp | The time the transaction took place | Unix timestamp |
| status | The status of the transaction (See Appendix 5.5) | Integer |
Example response
{
"runs":[
{
"runDate":"2020-06-30",
"amount":"1200",
"status":"3",
"transactions":[
{
"checkoutKey":null,
"amount":"1200",
"transactionKey":null,
"message":"Error: Invalid terminal key",
"timestamp":"1598439024",
"status":"3"
},
{
"checkoutKey":"7MRHxF5X",
"amount":"1200",
"transactionKey":"c93c5e657d7d18b9df7aac33bb8a134d",
"message":"Transaction status: Approved",
"timestamp":"1607942618",
"status":"1"
}
]
},
{
"runDate":"2020-07-28",
"amount":"1200",
"status":"1",
"transactions":[
{
"checkoutKey":null,
"amount":"1200",
"transactionKey":null,
"message":"Error: Invalid terminal key",
"timestamp":"1598439144",
"status":"3"
},
]
},
{
"runDate":"2020-08-25",
"amount":"1200",
"status":"4",
"transactions":[
{
"checkoutKey":null,
"amount":"1200",
"transactionKey":null,
"message":"Error: Invalid terminal key",
"timestamp":"1598518402",
"status":"3"
},
{
"checkoutKey":null,
"amount":"1200",
"transactionKey":"dcffb93fa8ffd5e93ce2aed6d257c033",
"message":"Transaction status: Approved",
"timestamp":"1598518405",
"status":"1"
},
{
"checkoutKey":"IEKFo8NI",
"amount":"1200",
"transactionKey":"a4eeda72d6e9920696c742889d39dc29",
"message":"Transaction status: Approved",
"timestamp":"1607942885",
"status":"1"
},
]
}
]
}
3.6 Disable¶
This method is used to disable payment schedule. All scheduled payment will be paused.
URL
/v3/schedule/disable/json
Request parameters
| Name | Description | Format (max characters) |
|---|---|---|
| apiKey† | The API Key provided by Paythru used for authentication. | Alpha-numeric characters |
| apiPassword† | The API Password provided by Paythru used for authentication. | Alpha-numeric characters |
| reference† | The payment schedule reference | Alpha-numeric characters (16) |
| shaSignature† | The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature | 128 Alpha numeric characters |
Response parameters
| Name | Description | Format |
|---|---|---|
| result | "OK" will be returned as the result if the request was successful. (Unsuccessful requests will result in an error.) | 2 alpha characters |
Example response
{
"result":"OK"
}
3.7 Enable¶
This method is used to enable a payment schedule that has been disabled.
URL
/v3/schedule/enable/json
Request parameters
| Name | Description | Format (max characters) |
|---|---|---|
| apiKey† | The API Key provided by Paythru used for authentication. | Alpha-numeric characters |
| apiPassword† | The API Password provided by Paythru used for authentication. | Alpha-numeric characters |
| reference† | The payment schedule reference | Alpha-numeric characters (16) |
| shaSignature† | The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature | 128 Alpha numeric characters |
Response parameters
| Name | Description | Format |
|---|---|---|
| result | "OK" will be returned as the result if the request was successful. (Unsuccessful requests will result in an error.) | 2 alpha characters |
Example response
{
"result":"OK"
}
3.8 Delete¶
This method is used to delete a payment schedule. Once deleted, the schedule the action cannot be undone and no future payments will be taken for the schedule.
URL
/v3/schedule/delete/json
Request parameters
| Name | Description | Format (max characters) |
|---|---|---|
| apiKey† | The API Key provided by Paythru used for authentication. | Alpha-numeric characters |
| apiPassword† | The API Password provided by Paythru used for authentication. | Alpha-numeric characters |
| reference† | The payment schedule reference | Alpha-numeric characters (16) |
| shaSignature† | The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature | 128 Alpha numeric characters |
Response parameters
| Name | Description | Format |
|---|---|---|
| result | "OK" will be returned as the result if the request was successful. (Unsuccessful requests will result in an error.) | 2 alpha characters |
Example response
{
"result":"OK"
}
¶
{
"result":"OK"
}
4.0 Error Handling¶
If the server is unable to process the request, an error is thrown. The nature of the error is returned as an error code and error message encoded in the expected response encoding format.
Error response format¶
All errors are returned with either the HTTP response code 400 (Bad Request), 401 (Unauthorized) or 403 (Forbidden) depending on the nature of the error.
The error response will contain the following parameters:
| Name | Description | Format |
|---|---|---|
| errorCode | The code indicating the type of error | 3 numeric characters |
| traceCode | The trace code of the error. The trace code should be used in any communication with Paythru to assist in determining the cause of the error. | 8 numeric characters |
| errorMessage | The human readable error message | Up to 100 characters |
For example, if an JSON response has been requested from the API, the error will be returned in JSON encoding.
Example JSON error response¶
{
"errorCode":"102",
"traceCode":"011318102",
"errorMessage":"Invalid API credentials"
}
See Appendix 5.1 for possible error messages.
5.0 Appendix¶
5.1 Error codes and messages¶
| Error code | Error message |
|---|---|
| 101 | No data sent |
| 102 | Invalid API credentials |
| 103 | Invalid function call |
| 104 | Invalid return type |
| 105 | Cannot find API settings for merchant |
| 106 | Permission denied to access this function |
| 111 | Currency not supported |
| 120 | Currency not supplied |
| 121 | This IP has been blocked for 1 minute due to excessive failed attempts |
| 122 | This IP has been blocked for 5 minutes due to excessive failed attempts |
| 123 | SHA Signature could not be verified |
| 124 | Invalid terminal key |
| 146 | Invalid card key |
| 147 | Card key not found |
| 187 | Invalid integer for parameter [field name] |
| 188 | Invalid amount for parameter [field name] |
| 189 | Invalid schedule reference |
| 190 | Invalid schedule start. Start should be in the future and in the format YYYY-MM-DD |
| 192 | Cannot edit [field name] after the start of the schedule |
| 193 | Invalid payment exception date: [date] |
| 194 | Invalid manual payment date: [date] |
| 195 | Cannot update manual payment in the past: [date] |
| 196 | [field name] cannot be set if the repeat pattern is manual |
| 198 | Invalid campaign |
| 500 | Server side error |
5.2 Repeat pattern¶
| Pattern key | Text | Description |
|---|---|---|
| week | Week | Every week |
| fortnight | Fortnight | Every two weeks |
| days-28 | 28 days | Every 28 days |
| month | Month - Specific date | Every month on the same date as the start date |
| month-2 | 2 months | Every 2 months on the same date as the start date |
| month-3 | 3 months | Every 3 months on the same date as the start date |
| month-4 | 4 months | Every 4 months on the same date as the start date |
| month-6 | 6 months | Every 6 months on the same date as the start date |
| months-first-specific-week-day | Month - First M, T, W, Th or F of the month | Every month on the first M, T, W, Th or F of the month determined by the start date |
| months-last-specific-week-day | Month - Last M, T, W, Th or F of the month | Every month on the last M, T, W, Th or F of the month determined by the start date |
| months-last-day | Month - Last day of the month | Every month on the last day of the month |
| months-last-working-day | Month - Last working day of the month | Every month on the last working day of the month (does not account for National Holidays) |
| year | Year | Every year on the same day and month as the start date |
| year-2 | 2 years | Every 2 years on the same day and month as the start date |
| manual | Manual dates | On the dates set manually by the parameter 'manualPayments' |
5.3 Payment schedule status¶
| Status | Description |
|---|---|
| 0 | Schedule not started yet, waiting for the first payment date |
| 1 | Schedule is active |
| 2 | Schedule is disabled |
| 3 | Schedule is completed |
| 5 | Schedule is waiting for a card key |
5.4 Schedule run status¶
| Status | Description |
|---|---|
| 1 | In arrears |
| 2 | Part settled |
| 3 | Settled |
| 4 | Overpaid |
| 5 | Written off |
5.5 Schedule transaction status¶
| Status | Description |
|---|---|
| 1 | Transaction approved |
| 2 | Transaction declined |
| 3 | Error in processing the transaction |