Payment Schedule API

Version: 3

[TOC]

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:

  1. Arrange all request parameters in alphabetical order by parameter name (not including the shaSignature parameter)
  2. Remove parameters with no value
  3. Concatenate the parameter name, an equals symbol, the parameter value and your shaKey
  4. Concatenate all resulting strings in order
  5. 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:500
In 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-15
In 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:500
In 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-15
In 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"
}

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