Request methods

All payment requests must be sent as an XML request using the HTTP POST method to the following URL:

https://secure.telr.com/gateway/remote.xml

All data must be sent in UTF-8 encoding. In order to allow processing via the global card network, only certain characters can be used. These are:

Example refund request

<?xml version="1.0" encoding="UTF-8"?>
<remote>
  <store>1</store>
  <key>mykey1234</key>
  <tran>
    <type>refund</type>
    <class>ecom</class>
    <currency>USD</currency>
    <amount>34.70</amount>
    <ref>010321000864</ref>
    <test>0</test>
  </tran>
</remote>

Transaction Categories

There are two categories of transactions, an initial transaction (a new sale for a new customer) and a follow-up transaction (such as a refund, or a continuous-authority sale such as could be used for returning customers or subscription payments)

Initial transactions require the full card details. Your systems must be PCI DSS certified in order to be able to use these.

Follow-up transactions do not have any card information, instead a reference is provided to the initial transaction and the gateway will retrieve the required card information from that initial transaction. PCI DSS certification is not required to use the follow-up transactions.

Any integration method can be used to obtain the transaction reference required in a follow-up transaction. For instance you can use the Hosted Payment Pages to process the initial transaction and then use remote for the follow-up. This combination would avoid any PCI DSS certification requirements for your systems as the card data would only be entered on and handled by the gateway.

The different parameters required for either initial or follow-up transactions are listed below.

Notes

1. The Authentication Key will be provided to you as part of the Remote Integration setup process after you request that this integration type is enabled for your account.
2. An example use of the cart ID field would be your own transaction or order reference.
3. Currency must be sent as a 3 character ISO code. A list of currency codes can be found at the end of this document. For voids or refunds this must match the original transaction currency.
4. The transaction amount must be sent in major units, for example 9 dollars 50 cents must be sent as 9.50 not 950. There must be no currency symbol, and no thousands separators. The decimal part must be separated using a dot.
   For voids, the amount must exactly match the amount of the original transaction.
   For refunds, captures and releases the amount must not exceed the amount of the original transaction.
5. The previous transaction reference is required for any void, refund, capture or release transaction. It must contain the reference that was supplied in the response for the original transaction.
6. Test mode of zero indicates a live transaction. If this is set to any other value the transaction will be treated as a test.
7. Card dates must be sent as a numeric values with a two digit month (01-12) and a 4 digit year (e.g. 2010)
8. The requirement for the CVV (card security code) depends on the transaction class:
   1. Continuous Authority - Not Used
   2. Mo/To - Optional
   3. E-Commerce - Required
9. Some fields (such as region, zip code and phone number) are optional within the gateway itself, but may be mandated by the acquirer you are using. If your acquirer mandates these details, then they must be supplied as part of the request.
10. Country must be sent as a 2 character ISO code. A list of country codes can be found at the end of this document.
11. The requirement for the IP address depends on the transaction class. Where it is sent, it must be sent in the dotted-decimal format, for example 1.2.3.4
    1. Continuous Authority Mo/To
       E-Commerce
    2. Not Used
    3. Optional (* - see below) - Required
12. Delivery details are optional, but if used then as a minimum the forename, surname, address line 1, city and country must be sent. Acquirer specific requirements for details such as region and zip code also apply here.
13. The optional extra data fields can be used to hold additional data that relates to this transaction. The parameter name must be a between 6 and 20 characters, consist only of lower case a-z, digits 0-9 and the underscore. The name must start ‘xtra_’. For example, a customer account number could be sent as ‘xtra_acnum’.
    There are two reserved fields that cannot be used – ‘xtra_fields’ and ‘xtra_signature’

* Although these values (CVV and IP Address) are optional within the gateway for Mo/To class transactions, some acquiring banks may mandate one or both of these. Please check with support to confirm if these are required for your account.