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 user@domain.com would be obtained from : https://secure.telr.com/tools/api/xml/transaction/user@domain.com/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://secure.telr.com/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)