The following pages detail each of the services available. For each service, the required URL will be shown, and an example of the data provided by that service. Unless specified otherwise, the request method for each service must be GET
Where the response data includes any of the common data elements, refer to the relevant section above for the details of that element. These will be marked in the response examples by the prefix CDE followed by the element title.
Recent transaction list
https://secure.telr.com/tools/api/xml/transaction
This will provide a list of the most recent transactions processed within the last 48 hours. A maximum of 30 transactions will be included.
Data provided:
<?xml version="1.0" encoding="UTF-8"?>
<transactions>
<trancount>Count of transactions in the results</trancount>
<transaction>CDE: Transaction information</transaction>
</transactions>
The … section will be repeated for each transaction in the list.
Transaction details
https://secure.telr.com/tools/api/xml/transaction/{tranref}
This will provide the details for a given transaction reference. The transaction reference must be included within the URL, where it shows {tranref} above.
For example, the details for transaction reference 011287290362 would be obtained from : https://secure.telr.com/tools/api/xml/transaction/011287290362
Data provided:
<?xml version="1.0" encoding="UTF-8"?>
<transaction>CDE: Transaction information</transaction>
Linked transactions
https://secure.telr.com/tools/api/xml/transaction/{tranref}/linked
This will provide the details for all transaction linked to the given reference. The transaction reference must be included within the URL, where it shows {tranref} above.
For example, the details for transactions linked to reference 011287290362 would be obtained from : https://secure.telr.com/tools/api/xml/transaction/011287290362/linked
This allows you to find the complete list of events for any given transaction including the initial auth or sale, and any subsequent capture, refund or void transactions. The initial transaction reference for the specified transaction is obtained, and then all transactions which have the same initial transaction reference are returned. A maximum of 30 transactions will be included.
Data provided:
<?xml version="1.0" encoding="UTF-8"?>
<transactions>
<trancount>Count of transactions in the results</trancount>
<transaction>CDE: Transaction information</transaction>
</transactions>
Transactions search – Cart ID
https://secure.telr.com/tools/api/xml/transaction/{ref}/cart
This will provide the details for all transaction that have the given reference as their cart ID. The reference must be included within the URL, where it shows {ref} above.
For example, the details for transactions with cart ID ABC123 would be obtained from : https://secure.telr.com/tools/api/xml/transaction/ABC123/cart
This will return all matching transactions, including the initial auth or sale, and any subsequent capture, refund or void transactions. This is most effective if the cart ID used in the initial transaction request is a unique ID for the transaction. A maximum of 30 transactions will be included.
Data provided:
<?xml version="1.0" encoding="UTF-8"?>
<transactions>
<trancount>Count of transactions in the results</trancount>
<transaction>CDE: Transaction information</transaction>
</transactions>
Transactions search – Cart ID (Allowing special characters)
https://secure.telr.com/tools/api/xml/transaction?cart_id=
This will provide the details for all transaction that have the given reference as their cart ID. The reference must be included within the URL after the query parameter, where it shows cart_id= above.
For example, the details for transactions with cart ID ABC123 would be obtained from : https://secure.telr.com/tools/api/xml/transaction?cart_id=ABC123
This will return all matching transactions, including the initial auth or sale, and any subsequent capture, refund or void transactions. This is most effective if the cart ID used in the initial transaction request is a unique ID for the transaction. A maximum of 30 transactions will be included.
Data provided:
<?xml version="1.0" encoding="UTF-8"?>
<transactions>
<trancount>Count of transactions in the results</trancount>
<transaction>CDE: Transaction information</transaction>
</transactions>
Transactions search – Email
https://secure.telr.com/tools/api/xml/transaction/{addr}/email
This will provide the details for all transaction that have the given address as their billing email address. The address must be included within the URL, where it shows {addr} above.
For example, the details for transactions with email [email protected] would be obtained from : https://secure.telr.com/tools/api/xml/transaction/[email protected]/email
This will return all matching transactions, including the initial auth or sale, and any subsequent capture, refund or void transactions. A maximum of 30 transactions will be included.
Data provided:
<?xml version="1.0" encoding="UTF-8"?>
<transactions>
<trancount>Count of transactions in the results</trancount>
<transaction>CDE: Transaction information</transaction>
</transactions>
The … section will be repeated for each transaction in the list.
Transactions search – Card number
https://secure.telr.com/tools/api/xml/transaction/{num}/card
This will provide the details for all transaction that where made with the given card number. The number must be included within the URL, where it shows {num} above.
The card number can be provided in two ways, as either an 8 digit value (containing the first 4 and last 4 digits of the card number) or as a 12 digit transaction reference.
Examples:
Details for transactions with card starting 4000 and ending 0002:
https://secure.telr.com/tools/api/xml/transaction/40000002/card
Details for transactions made use the same card as transaction 011287290362:
https://secure.telr.com/tools/api/xml/transaction/011287290362/card
This will return all matching transactions, including the initial auth or sale, and any subsequent capture, refund or void transactions. A maximum of 30 transactions will be included.
Data provided:
<?xml version="1.0" encoding="UTF-8"?>
<transactions>
<trancount>Count of transactions in the results</trancount>
<transaction>CDE: Transaction information</transaction>
</transactions>
The … section will be repeated for each transaction in the list.
Report list
https://secure.telr.com/tools/api/xml/report
This will provide a list of the most recent reports that have been generated, such as the Daily and Monthly transaction reports. A maximum of 50 reports will be included.
Data provided:
<?xml version="1.0" encoding="UTF-8"?>
<reports>
<repcount>Count of reports in the results</repcount>
<report>
<id>Report ID</id>
<store>Store ID</store>
<date>Time and date report was generated, GMT</date>
<file1>Filename of the first report file</file1>
<file2>Filename of the second report file, if any</file2>
<description>Description of the report</description>
<comments>Additional information about the report</comments>
</report>
</reports>
The ... section will be repeated for each report in the list.
Report download
https://secure.telr.com/tools/api/xml/report/{report_id}
https://secure.telr.com/tools/api/xml/report/{report_id}/file1
https://secure.telr.com/tools/api/xml/report/{report_id}/file2
This will start the download of a report file from a given report ID. The report ID must be included within the URL, where it shows {report_id} above. You also need to select if you will be downloading report file1 or file2 (if the file selection is omitted from the URL, then file1 will be assumed).
For example, file 1 of report 80000 would be downloaded from https://secure.telr.com/tools/api/xml/report/80000/file1
If the request reported is not found (such as invalid ID, or requesting file2 for a report that only has one file) then an XML response will be generated indicating this error.
If the report file is available, then the response from the system will not be an XML response, it will be the actual report file as a binary download. In this instance, the response will include content- type and content-disposition headers containing details of the file type and file name, for example:
Content-Disposition: attachment; filename=DailySummary_20170118.zip
Content-Type: application/zip
Recent repeat billing agreements list
https://secure.telr.com/tools/api/xml/agreement
This will provide a list of the most recent repeat billing agreements. A maximum of 30 agreements will be included
Data provided:
<?xml version="1.0" encoding="UTF-8"?>
<agreements>
<agrcount>Count of agreements in the results</agrcount>
<agreement>CDE: Repeat billing agreement</agreement> (No billing details)
</agreements>
Repeat billing agreement details
https://secure.telr.com/tools/api/xml/agreement/{agreement_id}
This will provide the details for a given agreement ID. The agreement ID must be included within the URL, where it shows {agreement_id} above.
For example, the details for agreement 60100 would be obtained from : https://secure.telr.com/tools/api/xml/agreement/60100
Data provided:
<?xml version="1.0" encoding="UTF-8"?>
<agreement>CDE: Repeat billing agreement</agreement> (Includes billing details)
Repeat billing agreement history
https://secure.telr.com/tools/api/xml/agreement/{agreement_id}/history
This will provide the event history for a given agreement ID. The agreement ID must be included within the URL, where it shows {agreement_id} above.
For example, the history for agreement 60100 would be obtained from : https://secure.telr.com/tools/api/xml/agreement/60100/history
Data provided:
<?xml version="1.0" encoding="UTF-8"?>
<agreement>
<eventcount>Count of events in the results</eventcount>
<event>
<type>Event type</type>
<typetxt>Event type, text description</typetxt>
<date>Time and date of event, GMT</date>
<note>Event note text</note> (*)
<paytype>Payment type</paytype> (*)
<paytypetxt>Payment type, text description</paytypetxt> (*)
<paycount>Payment number for regular payments</paycount> (*)
<amount>Transaction amount</amount> (*)
<tranref>Transaction reference</tranref> (*)
<invoice>Invoice reference</invoice> (*)
</event>
</agreement>
The … section will be repeated for each event in the list.
Fields marked with (*) are optional, and will only be present if relevant to that event.
Event type | Event type description |
---|---|
1 | Agreement created |
2 | Agreement completed |
3 | Agreement failed (to many declined transactions) |
4 | Invoice late for payment |
5 | Agreement cancelled |
6 | Invoice sent |
7 | Payment authorised |
8 | Payment declined |
9 | Card verified |
10 | Credit authorised |
11 | Credit declined |
12 | Text note added |
Payment type | Description |
---|---|
1 | Initial payment |
2 | Regular payment |
3 | Final payment |
4 | Manual adjustment (e.g. additional payment or a refund) |
Cancel repeat billing agreement
https://<<base_url>/tools/api/xml/agreement/{agreement_id}
A request sent using the DELETE method will cancel the agreement. The agreement ID must be included within the URL, where it shows {agreement_id} above.
For example, the to cancel agreement 60100 send a DELETE method request to https://secure.telr.com/tools/api/xml/agreement/60100
This option will provide the same format response as for the agreement details request, showing the updated agreement status.
<?xml version="1.0" encoding="UTF-8"?>
<agreement>CDE: Repeat billing agreement</agreement> (Includes billing details)