Remote API Integration Guide

Introduction

Merchants who collect and store their shoppers’ payment details on their own platform can use the remote system as an effective payment-processing gateway. With this system, the merchant collects both order and payment details and then communicates the relevant payment details on a per order basis with payment gateway for processing. All communications with payment gateway are handled using server-to-server methods.

The benefits of using the remote system for the merchant include being able to retain full control over the payment process and also the payment pages displayed to shoppers.

However, for this system to work successfully, it is important that the merchant ensures their own system operates within a secure environment so that payment details, which they collect and store, are protected. In view of the cost involved in establishing appropriate security measures, this model only applies to merchants with established high transaction volumes.

As part of the setup process you will be supplied with an authentication key, and you will need to provide the IP address details of the servers that will be making the remote requests.

As a minimum you will need to ensure that you have the following:

• A secure (HTTPS) server used for collecting the payment details.
• Full compliance with PCI-DSS which includes (but is not limited to) secure encrypted storage of all card details.
• Ability to implement 3-D Secure authentication for E-Commerce class transactions.

Security

A core issue associated with using the remote interface is security. The collection and storage of payment information, such as card numbers and cardholder names must take place in a secure environment. Even if you do not store the card details, handling the card details (such as allowing customers to enter them within your systems and then sending those to the gateway) will require PCI DSS certification.

Payment Card Industry Data Security Standard (PCI DSS)

PCI DSS is a global Card Scheme initiative that aims to ensure that every entity that handles, stores or processes cardholder data does so in a secure manner. MasterCard and Visa have combined their own security standards for cardholder data creating an aligned program, which is now endorsed by American Express, JCB and Diners. Much of PCI DSS relates to the technology involved in capturing and processing card data and this is particularly relevant to those merchants who process and capture cardholder data on their own systems rather than those who use the Hosted Payment Pages.

For more information, please refer to PCI DSS and to the PCI Security Standards Council at: www.pcisecuritystandards.org. If you want any help to gain compliance this site also lists PCI approved Quality Security Assessors (QSAʹs) who can provide technical advice.

Request methods

All payment requests must be sent using the HTTP POST method to one of three possible URL’s. The request data can either be in the form of standard HTTP URL encoded parameters, or it can be sent as an XML document.

The format of the response is dependent on which URL is used:

URL	Response format
https://secure.telr.com/gateway/remote.html	HTTP parameter format
https://secure.telr.com/gateway/remote.txt	Plain text
https://secure.telr.com/gateway/remote.xml	XML document

Example purchase request

using HTTP URL encoded parameters:

ivp_store=1&ivp_authkey=x47gy2avf9&ivp_trantype=sale&ivp_tranclass=moto& ivp_desc=Product%20details&ivp_currency=GBP&ivp_amount=24.95&ivp_test=0& ivp_cn=4000000000000002&ivp_exm=10&ivp_exy=2012&bill_fname=Card& bill_sname=Holder&bill_addr1=Address&bill_city=London&bill_country=GB& bill_email=test@test.com

 Example refund request

using HTTP URL encoded parameters:

ivp_store=1&ivp_authkey=x47gy2avf9&ivp_trantype=refund&ivp_tranclass=ecom& ivp_currency=USD&ivp_amount=34.70&tran_ref=010321000864&ivp_test=0

 The same refund request sent as an XML document would be as follows:

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

You can send either request format to any of the URL’s. For example, you can send the request in as HTTP URL parameters to remote.xml in order to get the response back as an XML document.

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:

Unicode set name	Characters allowed (hex code)
Basic Latin	0009, 000A, 000D, 0020-007E
Latin-1 Supplement	00A0-00FF
Latin Extended-A	0100-017F
Latin Extended-B	Latin Extended-B

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.

	Transaction Class
Transaction Type	E-Commerce	Mail/Telephone Order	Continuous Authority
Sale	Initial (Requires PCI DSS)	Initial (Requires PCI DSS)	Follow-up
Auth	Initial (Requires PCI DSS)	Initial (Requires PCI DSS)	Not Available
Verify	Initial (Requires PCI DSS)	Initial (Requires PCI DSS)	Not Available
Void	Follow-up	Follow-up	Follow-up
Capture	Follow-up	Follow-up	Not Available
Release	Follow-up	Follow-up	Not Available
Refund	Follow-up	Follow-up	Follow-up

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.

HTTP URL Parameters

Description	Parameter	Initial Trans	Follow-up
Core transaction data
Store ID	ivp_store	Required	Required
Authentication key (Note 1)	ivp_authkey	Required	Required
Transaction type	ivp_trantype	Required	Required
Transaction class	ivp_tranclass	Required	Required
Transaction description	ivp_desc	Required	Required
Transaction cart ID (Note 2)	ivp_cart	Required	Required
Transaction currency (Note 3)	ivp_currency	Required	Required
Transaction amount (Note 4)	ivp_amount	Required	Required
Previous transaction reference (Note 5)	tran_ref	Not used	Required
Test mode (Note 6)	tran_ref	Required	Required
Card details
Card number	ivp_cn	Required	Not used
Expiry date – month (Note 7)	ivp_exm	Required	Not used
Expiry date – year (Note 7)	ivp_exy	Required	Not used
CVV (Note 8)	ivp_cv	Conditional	Not used
Card holder details
Title (Mr, Mrs, etc)	bill_title	Optional	Not used
Forenames	bill_fname	Required	Not used
Surname	bill_sname	Required	Not used
Street address – line 1	bill_addr1	Required	Not used
Street address – line 2	bill_addr2	Optional	Not used
Street address – line 3	bill_addr3	Optional	Not used
City	bill_city	Required	Not used
Region/State (Note 9)	bill_region	Optional	Not used
Country (Note 10)	bill_country	Required	Not used
Zip/Area/Postcode (Note 9)	bill_zip	Optional	Not used
Email address	bill_email	Required	Not used
Phone number (Note 9)	bill_phone1	Optional	Not used
IP Address (Note 11)	bill_ip	Conditional	Not used
Delivery details (Note 12)			Not used
Title (Mr, Mrs, etc)	delv_title	Optional	Not used
Forenames	delv_fname	Conditional	Not used
Surname	delv_sname	Conditional	Not used
Street address – line 1	delv_addr1	Conditional	Not used
Street address – line 2	delv_addr2	Optional	Not used
Street address – line 3	delv_addr3	Optional	Not used
City	delv_city	Conditional	Not used
Region/State (Note 9)	delv_region	Optional	Not used
Country (Note 10)	delv_country	Conditional	Not used
Zip/Area/Postcode (Note 9)	delv_zip	Optional	Not used
Phone number (Note 9)	delv_phone1	Optional	Not used
Extra data fields (Note 13)			Not used
Extra data elements	xtra_*	Optional	Not used

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:
   Continuous Authority – Not Used
   Mo/To – Optional (* – see below)
   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
    Continuous Authority – Not Used
    Mo/To – Optional (* – see below)
    E-Commerce – 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.

Transaction Types

The ivp_trantype and ivp_tranclass parameters set the type of transaction that will be processed. These set both the processing action and the processing category. The options are:

ivp_trantype
auth	Seek authorisation from the card issuer for the amount specified. If authorised, the funds will be reserved but will not be debited until such time as a corresponding capture command is made. This is sometimes known as pre-authorisation.
capture	Debit the funds that have been reserved on a card using a previous auth transaction. The amount that to be captured can be any amount up to the full amount of the initial auth. It cannot exceed the initial amount. This is sometimes known as post- authorisation or as pre-authorisation completion.
release	Release funds that had previously been reserved using an auth transaction. It is possible for the amount that is captured to be lower than the initial auth amount. In this case the remaining balance should be released back to the card holder. A release transaction cannot be voided. The full amount of the auth can be released in order to cancel the transaction. A release cannot be done on any transaction type other than an auth.
sale	Immediate purchase request. This has the same effect as would be had by performing an auth transaction followed by a capture transaction for the full amount. No additional capture stage is required.
refund	Credit the amount specified back to the card holder. A refund can be processed against a sale or capture transaction.
void	Cancel either a sale, refund or capture transaction. This can only be done within a few hours of the transaction you are attempting to cancel.
verify	Confirm that the card details given are valid. No funds are reserved or taken from the card.
ivp_tranclass
moto	Process as Mail Order / Telephone Order.
ecom	Process as an Internet based E-Commerce transaction. The use of 3-D Secure is mandatory for this class of transaction.
cont	Process as a continuous authority transaction, for example a recurring subscription.

For E-Commerce transactions it is mandatory that you also implement 3-D Secure as part of the authorisation process. The payment gateway provides remote access to an MPI which will simplify this process for you. See the section on 3-D Secure later in this document.

For items or services that have an immediate delivery, the sale transaction method is often the simplest one to use. If there can be a delay between the transaction and eventual shipping of the goods, then separate auth and capture transactions should be used. You must ensure that you perform the capture stage of the transaction otherwise the funds will not be taken from the card and you will not receive payment. You should process the capture request before actually shipping the goods to ensure that the card used is still valid.

XML Request layout

<?xml version="1.0" encoding="UTF-8"?>
<remote>
  <store>Store ID</store>
  <key>Authentication Key</key>
  <tran>
    <type>Transaction type</type>
    <class>Transaction class</class>
    <cartid>Transaction cart ID</cartid>
    <description>Transaction description</description>
    <test>Test mode</test>
    <currency>Transaction currency</currency>
    <amount>Transaction amount</amount>
    <ref>Previous transaction reference</ref>
  </tran>
  <card>
    <number>Card number</number>
    <expiry>
    <month>Expiry date - month</month>
    <year>Expiry date - year</year>
    </expiry>
    <cvv>CVV</cvv>
  </card>
  <billing>
    <name>
      <title>Title</title>
      <first>Forenames</first>
      <last>Surname</last>
    </name>
    <address>
      <line1>Street address – line 1</line1>
      <line2>Street address – line 2</line2>
      <line3>Street address – line 3</line3>
      <city>City</city>
      <region>Region</region>
      <country>Country</country>
      <zip>Zip/Area/Postcode</zip>
    </address>
    <email>Email address</email>
    <ip>IP address</ip>
  </billing>
</remote>

To include the delivery details, add a <delivery> …. </delivery> section as follows

<?xml version="1.0" encoding="UTF-8"?>
<remote>
  <store>Store ID</store>
  <key>Authentication Key</key>
  <tran>
  ....
  </tran>
  <card>
  ....
  </card>
  <billing>
  ....
  </billing>
  <delivery>
    <name>
      <title>Title</title>
      <first>Forenames</first>
      <last>Surname</last>
    </name>
    <address>
      <line1>Street address – line 1</line1>
      <line2>Street address – line 2</line2>
      <line3>Street address – line 3</line3>
      <city>City</city>
      <region>Region</region>
      <country>Country</country>
      <zip>Zip/Area/Postcode</zip>
    </address>
  </delivery>
</remote>

To include the extra data fields, add a <extra> …. </extra> field as follows:

<?xml version="1.0" encoding="UTF-8"?>
<remote>
  <store>Store ID</store>
  <password>Store password</password>  
  <tran>
  ....
  </tran>
  <card>
  ....
  </card>
  <billing>
  ....
  </billing>
  <extra>
    <val1>data for xtra_val1</val1>
    <acnum>data for xtra_acnum</acnum>
    ....
  </extra>
</remote>

To convert the ‘xtra_name’ format to xml, simply remove the ‘xtra_’ part and include the remainder inside the <extra>…</extra> section.

You can include both delivery and extra data sections if required.

Authorisation response

The actual format of the response will depend on the URL used in the request. All formats contain the same details; you simply select whichever format is the easiest for you to process and integrate with your existing systems.

Field	Description
auth_status	Authorisation status. A indicates an authorised transaction. Any other value indicates that the request could not be processed.
auth_code	If the transaction was authorised, this contains the authorisation code from the card issuer. Otherwise it contains a code indicating why the transaction could not be processed.
auth_message	The authorisation or processing error message.
auth_tranref	The payment gateway transaction reference allocated to this request.
auth_cvv	Result of the CVV check: Y = CVV matched OK N = CVV not matched X = CVV not checked E = Error, unable to check CVV
auth_avs	Result of the AVS check: Y = AVS matched OK P = Partial match (for example, post-code only) N = AVS not matched X = AVS not checked E = Error, unable to check AVS

The AVS check is currently only available for cards issued in the United Kingdom, United States of America or Canada.

Response examples

Authorised – via remote.html

Response is on a single line:

auth_status=A&auth_code=tst123&auth_message=Authorised& auth_tranref=010321000871&auth_cvv=Y&auth_avs=X

Authorised – via remote.txt

Response is on multiple lines:

auth_status=A auth_code=tst123 auth_message=Authorised auth_tranref=010321000871 auth_cvv=Y auth_avs=X

 Authorised – via remote.xml

<?xml version="1.0" encoding="UTF-8"?>
<remote>
  <auth>
    <status>A</status>
    <code>tst123</code>
    <message>Authorised</message>
    <tranref>010321000871</tranref>
    <cvv>Y</cvv>
    <avs>X</avs>
  </auth>
</remote>

 Not authorised – via remote.html

auth_status=E&auth_code=02&auth_message=Invalid%20card%20number& auth_tranref=000321000874&auth_cvv=X&auth_avs=X

Tokenization

Tokenization is the process of replacing some piece of sensitive data with a value that is not considered sensitive in the context of the environment that consumes the token and the original sensitive data.

Transaction level

The payments gateway uses a transaction level tokenization by default. In this way, only the initial transaction requires the card details. In all other transactions (such as a Refund, Void, or further authorisations when using the Continuous Authority class) the card details do not form part of the transaction request. Instead, the request must include the payment gateway transaction reference for the initial transaction. All required details, such as card number and expiry date, will be retrieved from the transaction record held by gateway.

As the card details are not required for any follow-up transactions, merchants can simplify their PCI DSS compliance by not storing any of the card details. The transaction reference cannot be used to obtain a copy of the card details.

If additional sale transactions using the Mo/To or E-Commerce class transactions are required, then the full card details will need to be sent as part of the request.

Recurring transactions

Using the Continuous Authority transaction class, you can process additional authorisations against a card. This could be used, for example, in a subscription based system where the customer is required to pay a set amount every month.

The first transaction must be processed as either an E-Commerce transaction or as a MoTo (Mail Order / Telephone Order) transaction. If this transaction is authorised, then additional transactions can be processed as Continuous Authority.

These additional transactions requests are processed by setting a transaction type of ‘sale’, with a transaction class of ‘cont’. Although this is a sale request, it is treated as a follow-up transaction in the same way as would be done for a refund or void. Card and billing details must not be sent as part of the request, it must instead use the ‘tran_ref’ field to set the transaction ID of the initial authorisation. The card and billing details will be retrieved from that initial authorisation.  Other transaction details, such as cart ID and description, must be sent as per a normal Sale request.

The initial transaction must be an authorised sale, using either the E-Commerce or MoTo transaction class. If the transaction referenced is not a sale, was not authorised, or is not of the required class then the authorisation request will be rejected.

Should a customer require changing of their card details, maybe through needing to use a different card or simply down to the existing card expiring, then a new E-Commerce or MoTo transaction will be required to make an initial authorisation based on the new card details. All recurring transactions after that point should now refer to this new transaction and not the original transaction.

3-D Secure

The 3-D Secure protocol was developed by Visa to improve the security of Internet payments. It is designed to allow authentication of cardholders by their issuers at participating merchants. The objective is to benefit all participants by providing issuers the ability to fully authenticate cardholders during an online purchase, reducing the likelihood of fraudulent usage of Visa cards and improving overall transaction performance. It has since been licensed by other card schemes such as MasterCard, JCB and American Express. Each card scheme has its own brand name for 3-D Secure:

Scheme	3-D Secure brand name
Visa	Verified by Visa
MasterCard	SecureCode
JCB	J/Secure
American Express	SafeKey

The card holder verification takes place on a server called an Access Control Server (ACS) which is operated by the card issuer. The merchant or payment gateway is not involved in capturing or processing any of the authentication details.

The advantage for merchants is the reduction of “unauthorised transaction” chargebacks. The main advantage for cardholders is that there is a decreased risk of other people being able to use their payment cards fraudulently on the Internet.

In most current implementations of 3-D Secure, the issuing bank prompts the buyer for a password that is known only to the bank and the buyer. Since the merchant does not know this password and is not responsible for capturing it, it can be used by the issuing bank as evidence that the purchaser is indeed their cardholder. This decreases risk in two ways:

1. Copying card details, either by writing down the numbers on the card itself or by way of
   modified terminals or ATMs, does not result in the ability to purchase over the Internet
   because of the additional password, which is not stored on or written on the card.
2. Since the merchant does not capture the password, there is a reduced risk from security
   incidents at online merchants – there is no way for anyone to get the associated password.

Merchant integration with the 3-D Secure system is handled via a Merchant Plug-In (MPI). Normally this is an additional component that has to be installed within the merchants processing systems, and can be an expensive element to purchase and maintain.

Using 3-D Secure with the remote integration

To avoid the requirement for merchant systems to have their own MPI, The Remote Integration supports the option for merchants to use the gateway MPI without needing to install any additional components. This method also simplifies the work that would otherwise be needed to integrate your systems with an MPI.

Basic details of the transaction need to be sent to the remote MPI interface, this includes the card number, expiry date, transaction currency and amount. This information will be used to check if card holder verification is required. The response from the MPI interface will include a session ID, and may also include details of the ACS (Access Control Server) that needs to be used along with the data that needs to be sent to that ACS.

If there are no ACS details within the response, then you can immediately proceed with the transaction processing – however you must include the MPI session ID within the transaction request. Under the 3-D Secure system the transaction can be covered by the additional liability shift offered by 3-D Secure even if additional cardholder authentication is not required. If you do not include the MPI session ID within the transaction request, then your transaction cannot be covered by this possible liability shift.

If ACS details are returned, then you have to direct the consumer to the URL provided. This URL is operated by the card issuer, not by payment gateway. At this point the consumer is required to provide whatever additional identification the card issuer requires, and once that has been completed an authentication response will be returned to your system. Your system must include that authentication response, and the MPI Session ID, within the transaction processing request.

The two possible process flows are as shown on the following page.

MPI processing is only applicable to E-Commerce class transactions, and only for Sale transactions. It cannot be used for used for other transaction classes or methods.

Possible process flows

There are two possible process flows depending on if additional authentication is required or not.

Request methods

All payment requests must be sent using the HTTP POST method to one of three possible URL’s. The request data can either be in the form of standard HTTP URL encoded parameters, or it can be sent as an XML document.

The format of the response is dependent on which URL is used:

URL	Response format
https://secure.telr.com/gateway/remote_mpi.html	HTTP parameter format
https://secure.telr.com/gateway/remote_mpi.txt	Plain text
https://secure.telr.com/gateway/remote_mpi.xml	XML document

Example MPI request using HTTP URL encoded parameters:

ivp_store=1&ivp_authkey=x47gy2avf9&ivp_trantype=sale&ivp_tranclass=ecom& ivp_desc=Product%20details&ivp_currency=GBP&ivp_amount=24.95&ivp_test=0& ivp_cn=4000000000000002&ivp_exm=10&ivp_exy=2020

 The same request sent as an XML document would be as follows:

<?xml version="1.0" encoding="UTF-8"?>
  <remote>
  <store>1</store>
  <key>x47gy2avf9</key>
  <tran>
    <type>sale</type>
    <class>ecom</class>
    <description>Product details</description>
    <currency>GBP</currency>
    <amount>24.95</amount>
    <test>0</test>
  </tran>
  <card>
    <number>4000000000000002</number>
    <expiry>
    <month>10</month>
    <year>2020</year>
    </expiry>
  </card>
</remote>

You can send either request format to any of the URL’s. For example, you can send the request in as HTTP URL parameters to remote_mpi.xml in order to get the response back as an XML document.

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:

Unicode set name	Characters allowed (hex code)
Basic Latin	0009, 000A, 000D, 0020-007E
Latin-1 Supplement	00A0-00FF
Latin Extended-A	0100-017F
Latin Extended-B	Latin Extended-B

HTTP URL Parameters

Description	Parameter
Core transaction data
Store ID	ivp_store
Authentication key	ivp_authkey
Transaction type	ivp_trantype - Must be ‘sale’
Transaction class	ivp_tranclass - Must be ‘ecom’
Transaction cart ID	ivp_cart
Transaction description	ivp_desc
Transaction currency (Note 1)	ivp_currency
Transaction amount (Note 2)	ivp_amount
Test mode (Note 3)	ivp_test
Card details
Card number	ivp_cn
Expiry date – month (Note 4)	ivp_exm
Expiry date – year (Note 4)	ivp_exy
Browser details
Browser user agent (Note 5)	brsr_useragent
Browser accept header (Note 6)	brsr_accepthdr

Notes:

1. Currency must be sent as a 3 character ISO code. A list of currency codes can be found at the end of this document.
2. 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.
3. Test mode of zero indicates a live transaction. If this is set to any other value the transaction will be treated as a test.
4. Card dates must be sent as a numeric values with a two digit month (01-12) and a 4 digit year (e.g. 2016)
5. The browser user agent data is the content of the ‘User-Agent’ header provided to your server by the consumers browser.
6. The browser accept data is the content of the ‘Accept’ header provided to your server by the consumer’s browser.

XML Request layout

<?xml version="1.0" encoding="UTF-8"?>
<remote>
  <store>Store ID</store>
  <key>Authentication key</key>
  <tran>
    <type>Transaction type</type>
    <class>Transaction class</class>
    <cartid>Transaction cart ID</cartid>
    <description>Transaction description</description>
    <test>Test mode</test>
    <currency>Transaction currency</currency>
    <amount>Transaction amount</amount>
  </tran>
  <card>
    <number>Card number</number>
    <expiry>
    <month>Expiry date - month</month>
    <year>Expiry date - year</year>
    </expiry>
  </card>
  <browser>
    <agent>Browser User-Agent header</agent>
    <accept>Browser Accept header</accept>
  </browser>
</remote>

MPI response

The actual format of the response will depend on the URL used in the request. All formats contain the same details; you simply select whichever format is the easiest for you to process and integrate with your existing systems.

Field	Description
mpi_session	Session reference for this transaction. Must be included in the remote transaction processing request that is sent to authorise the transaction.
mpi_acsurl	The URL of the Access Control Server to be used for the additional authentication stage, if any
mpi_pareq	Data to be sent to the ACS

If the remote MPI request could not be processed, then no mpi_session will be supplied and instead there will be an error message. The response may also include other fields (such as mpi_xid, mpi_scheme and mpi_level) which are not used as part of this integration and can be ignored. Only the 3 fields shown in the table above are relevant to this integration method.

Response XML

<?xml version="1.0" encoding="UTF-8"?>
<remote>
  <mpi>
    <session>MPI Session ID</session>
    <acsurl>Access Control Server URL</acsurl>
    <pareq>Data to be sent to the ACS</pareq>
  </mpi>
</remote>

ACS Redirect

If the response indicates that additional authorisation is required, then your systems must direct the consumer to the required page. This must be done using the HTTP POST method to the URL given.
The data provided in the mpi_pareq field must be sent to the ACS as a field called ‘PaReq’ – the data must not be altered in any way otherwise the transaction will fail.

The mpi_pareq data can be large; your systems must be able to accept any size of data in this field. They must also be able to accept an ACS URL of up to 2048 bytes.

In addition to the PaReq field, you must also supply a field known as ‘TermUrl’. This contains the URL within your systems that you want the ACS to return the consumer to. The ACS will make a HTTP POST to this URL, which will contain the result of the authentication.

A further optional field, called ‘MD’, can also be supplied. The content of this field will be sent back as part of the data returned to your systems along with the authentication result. You can use this field as a method of tracking the payment session.

As HTTP POST must be used for ACS redirect, you will need to generate a page with a HTML form containing all of the required fields. This can be automatically submitted using JavaScript, but you must also provide an alternate submission method in case the consumers browser does not support JavaScript or does not have it enabled.

An example of this would be:

<form name="acsform" action="[acsurl obtained from the MPI request]" method="post">
<input type="hidden" name="PaReq" value="[The pareq data from the MPI request]">
<input type="hidden" name="MD" value="[Optional transaction reference]">
<input type="hidden" name="TermUrl" value="[return URL on your site]">
<noscript><input type="Submit"></noscript>
</form>
<script>
function autosub() {
document.forms['acsform'].submit();
}
document.onload=autosub;
</script>

After the authentication process has been completed, the ACS will make a HTTP POST back to the URL you gave as the ‘TermUrl’ field. This will contain two fields, the first is the ‘MD’ field which will
contain the same data as you provided in the request. The second is ‘PaRes’ which contains the result of the authentication.

The ACS page can be displayed as a full page by the browser, or it can be included as an inline frame within another page. The inline frame dimensions must be a minimum of 390 pixels wide by 400 pixels high. The page must not be displayed as a pop-up. See the section on ‘Merchant Requirments’  later in this document for more information.

Completing the transaction

Once the ACS has sent the authentication response back to your systems, you can then complete the transaction processing using the usual remote request. You must include the MPI session ID and the
authentication response that was received. This response must not be altered in any way otherwise the transaction will fail. The response data can be large; your systems must be able to accept any size of data in this field.

The additional HTTP URL parameters for the remote transaction processing are:

Description	Parameter
MPI Session ID	mpi_session
Authentication response	mpi_pares

If there was no additional authorisation stage required, you must still include the mpi_session value in the transaction processing request.

The details of the transaction (such as card number, amount, currency, cart ID and description) must be identical in the transaction processing request and the MPI request. If any details are changed, the transaction will not be able to be processed.

To include the fields within a XML request for transaction processing, they should be sent as follows:

<?xml version="1.0" encoding="UTF-8"?>
<remote>
  <store>Store ID</store>
  <key>Authentication key</key>
    <tran>
    ....
    </tran>
  <card>
  ....
  </card>
  <billing>
  ....
  </billing>
  <mpi>
    <session>MPI Session ID</session>
    <pares>Authentication response</pares>
  </mpi>
</remote>

Implementation best practices

3-D Secure has now been in use for several years, and valuable lessons can be learned from merchant and cardholder experiences during this time. The following points will assist you in implementing 3-D Secure in a way which is compliant with scheme requirements, and most importantly easy for the cardholder to use and therefore complete transactions.

Use of Inline Page instead of Pop-Up

Originally many merchants implemented a pop-up window for 3-D Secure, i.e. the authentication process appeared in a separate window to the payment system.

Pop-up suppression software has gained market adoption through stand-alone applications as well options built in to modern browsers. These will usually prevent the window from being displayed. Cardholders have also learned to disregard pop-up windows due to the high frequency of pop-up windows being used for unsolicited advertisements, and may just close them automatically without looking at them.

Pre-Authentication Message

You should include a brief message to cardholders on the checkout page informing them that they may be required to provide additional authentication details. The message must not say that this will
happen, as in some cases the process may continue without an authentication screen. This message should be placed on the page where it is likely the cardholder will notice and read it – for example next to the button that has to be clicked to make the payment.

A recommended pre-authentication message is as follows:

The next screen you see may be payment card verification through your card issuer.

3-D Secure logos

You should display the appropriate 3-D Secure logos (such as Verified by Visa or MasterCard SecureCode) on the payment page as an additional method of indicating to the cardholder that the
authentication steps may be required. If also serves to reassure cardholders if the authentication page is displayed as they have already seen the relevant logos within your payment page.

Inline options – Framed or Full page

With full page display, the entire browser display is replaced with the 3-D Secure authentication page, before returning to your systems where you can then display your own pages again. This has
the benefit of being a simpler implementation with fewer possibilities for mistakes, however it can disrupt the payment process as the browser navigation bar will show a different domain to the one the cardholder has been using so far, and the page layout will be different which can cause confusion.

With the framed approach you have more control over the page display, and the browser navigation bar continues to show the address of your site. This can be a more difficult method to implement.

Points to keep in mind when using the framed approach:

• Provide enough space so that the 3-D Secure frame can fit. The minimum size required is 390×400 pixels.
• Avoid having a ‘crowded’ screen which could cause confusion
• Ensure that the 3-D Secure frame is not pushed out of the viewable area on low resolution screens. The 3-D Secure frame must be viewable without having to scroll.
• There should not be other links or exit points that may distract the cardholder from completing the 3-D Secure process (such as search options, navigation menus etc)
• All page elements must be HTTPS. Never mix HTTP and HTTPS.

Within the framed approach you should also display a message that advises the cardholder not to click back or reload as that may cause problems with the authentication process.

Activity indicators

You should display something to the cardholder that lets them know authorisation is in progress. It may take several seconds for the initial cardholder enrollment checks to be undertaken, and you don’t want the cardholder to think that the process has stopped and abort the purchase.

The activity indicators should include some visual movement to reassure the cardholder that the process is continuing.

Activity indicators should be displayed during the initial MPI check to find out if additional authentication is required, and again during the actual authorisation process.

No promotional messages

Visa mandate that merchants must not display promotional messages to cardholders during the payment process, for example messages advertising special offers.

Example transaction request

The following shows an example of sending a continuous-authority sale transaction using PHP. This would be a follow-up transaction to an existing authorised e-commerce or moto class transaction.

$params = array(
  'ivp_store'      => 'Your Store ID',
  'ivp_authkey'	 => 'Your Authentication Key',
  'ivp_trantype'   => 'sale',
  'ivp_tranclass'  => 'cont',
  'ivp_desc'       => 'Product Description',
  'ivp_cart'       => 'Your Cart ID',
  'ivp_currency'   => 'AED',
  'ivp_amount'     => '100.00',
  'tran_ref'       => '12 digit reference of intial ecom/moto transaction',
  'ivp_test'       => '1'
);


$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://secure.telr.com/gateway/remote.html");
curl_setopt($ch, CURLOPT_POST, count($params));
curl_setopt($ch, CURLOPT_POSTFIELDS,$params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Expect:'));
$results = curl_exec($ch);
curl_close($ch);

Authorisation Response codes

Status	Code	Message
A	Set by issuer	Authorised
H	Set by issuer	Authorised, but placed on hold. Manual inspection required
E	01	Invalid request
E	02	Transaction cost or currency not supplied
E	03	Cart ID not set
E	04	Invalid store ID
E	05	Transaction cost or currency not valid
E	06	Invalid transaction mode
E	07	Card expiry not supplied
E	10	Card number not supplied
E	11	Invalid card number
E	12	Card expired
E	14	Card type mismatch
E	15	Invalid card security code (CVV)
E	16	Card security code (CVV) not supplied
E	17	Name not valid/not supplied
E	18	Address not valid/not supplied
E	19	Country not valid/not supplied
E	20	IP address not valid/not supplied
E	21	Card/Currency/Class combination not supported
E	22	Invalid transaction reference
E	23	Amount differs from original
E	24	Currency differs from original
E	25	Original transaction not authorised
E	26	Original transaction already voided
E	27	Original transaction mismatch
E	28	Invalid start date
E	29	Amount greater than available balance
E	30	Card details differ from original
D	31	Not authorised
D	32	Original transaction cannot be voided
C	33	Transaction cancelled
D	34	No response
E	35	Unable to refund
E	36	Previous transaction is on hold
D	37	Blocked by acquirer
E	38	Invalid expiry date
E	39	Invalid expiry date
E	40	Invalid transaction type
D	41	Insufficient funds
D	42	Card security code (CVV) mismatch
E	43	Email not valid/not supplied
E	44	Phone number not valid/not supplied
E	45	Transaction mode differs from original
D	46	3DSecure authentication not available for this card
D	47	3DSecure authentication rejected
E	48	Description not set
D	49	Sold out
E	50	Card is for ATM use only
D	51	Transaction part 1 not authorised
D	52	Transaction part 2 not authorised
X	53	Authorisation expired
E	54	Transaction part not specified
E	55	Unable to access transaction part
E	56	Duplicate transaction
D	57	Continuous authority not available on referenced transaction
E	58	Error connecting to service provider
E	59	Request aborted
E	60	Verification failed
D	61	Not authorised
D	62	Not authorised
D	63	Address verification (AVS) mismatch
D	64	Card security code (CVV) and address (AVS) mismatch
D	65	Card is not enabled for e-commerce
D	66	Card cancelled
D	67	Transaction not permitted by issuer
D	68	No suitable account
D	80	Not authorised Card Filter module. Message text can be changed
D	90	Not authorised
D	91	Not authorised
D	92	Not authorised
D	93	Card limits exceeded
D	94	Not authorised
D	95	Not authorised
D	96	Not authorised
E	98	Internal system error
E	99	Unknown error

Response code 01 (Invalid Request)

This indicates that at least one aspect of the request is not valid. It most cases a transaction exception will be generated and these can be viewed within the merchant admin system.

There are many possible causes of the ‘Invalid Request’ response. In order to help maintain system security the exact cause is not contained with the response. For example the reason could be that the request has been received from an un-authorised IP address, or that the password used is not correct. This information is not divulged as part of the response data, you will need to view the exception report to see the full details.

A common cause of this error is attempting to use the remote integration without first requesting that it is added to your account. You must first request that the remote integration is added to
your account before you start to use it – this is not enabled by default. As part of the activation process you will be supplied with the authentication key, and you will need to provide the IP address details of the servers which will be making the remote requests. Please ensure that you have read the Introduction, Security and PCI DSS sections at the start of this guide.

Please also keep in mind that the use of 3-D Secure is mandatory for E-Commerce class transactions.

Supported Currency Codes

AED	United Arab Emirates Dirham
BHD	Bahraini Dinar
CAD	Canadian Dollar
EGP	Egyptian Pound
EUR	Euro
IDR	Indonesian Rupiah
GBP	Pound Sterling
JOD	Jordanian Dinar
JPY	Japanese Yen
KHR	Cambodian Riel
KWD	Kuwaiti Dinar
MYR	Malaysian Ringgit
OMR	Omani Rial
PHP	Philippine Peso
QAR	Qatari Rial
SAR	Saudi Riyal
SGD	Singapore Dollar
THB	Thai Baht
USD	US Dollar
VND	Vietnamese Dong
INR	Indian Rupee

ISO Country Codes

ISO	Country
AF	Afghanistan
AL	Albania
DZ	Algeria
AS	American Samoa
AD	Andorra
AO	Angola
AI	Anguilla
AG	Antigua and Barbuda
AR	Argentina
AM	Armenia
AW	Aruba
AU	Australia
AT	Austria
AZ	Azerbaijan
BS	Bahamas
BH	Bahrain
BD	Bangladesh
BB	Barbados
BY	Belarus
BE	Belgium
BZ	Belize
BJ	Benin
BM	Bermuda
BT	Bhutan
BO	Bolivia
BA	Bosnia and Herzegovina
BW	Botswana
BR	Brazil
IO	British Indian Ocean Territory
VG	British Virgin Islands
BN	Brunei Darussalam
BG	Bulgaria
BF	Burkina Faso
BI	Burundi
KH	Cambodia
CM	Cameroon
CA	Canada
CV	Cape Verde
KY	Cayman Islands
CF	Central African Rep
TD	Chad
CL	Chile
CN	China
CX	Christmas Island
CC	Cocos (Keeling) Islands
CO	Colombia
KM	Comoros
CD	Congo, Democratic Rep of
CG	Congo, Republic of
CK	Cook Islands
CR	Costa Rica
CI	Cote d'Ivoire
HR	Croatia
CU	Cuba
CY	Cyprus
CZ	Czech Rep
DK	Denmark
DJ	Djibouti
DM	Dominica
DO	Dominican Rep
EC	Ecuador
EG	Egypt
SV	El Salvador
GQ	Equatorial Guinea
ER	Eritrea
EE	Estonia
ET	Ethiopia
FK	Falkland Islands
FO	Faroe Islands
FJ	Fiji
FI	Finland
FR	France
GF	French Guyana
PF	French Polynesia
GA	Gabon
GM	Gambia
GE	Georgia
DE	Germany
GH	Ghana
GI	Gibraltar
GR	Greece
GL	Greenland
GD	Grenada
GP	Guadeloupe
GU	Guam
GT	Guatemala
GN	Guinea
GW	Guinea-Bissau
GY	Guyana
HT	Haiti
HN	Honduras
HK	Hong Kong
HU	Hungary
IS	Iceland
IN	India
ID	Indonesia
IR	Iran
IQ	Iraq
IE	Ireland
IT	Italy
JM	Jamaica
JP	Japan
JO	Jordan
KZ	Kazakhstan
KE	Kenya
KI	Kiribati
KP	Korea, North
KR	Korea, South
KW	Kuwait
KG	Kyrgyzstan
LA	Laos
LV	Latvia
LB	Lebanon
LS	Lesotho
LR	Liberia
LY	Libya
LI	Liechtenstein
LT	Lithuania
LU	Luxembourg
MO	Macau
MK	Macedonia
MG	Madagascar
MW	Malawi
MY	Malaysia
MV	Maldives
ML	Mali
MT	Malta
MH	Marshall Islands
MQ	Martinique
MR	Mauritania
MU	Mauritius
YT	Mayotte
MX	Mexico
FM	Micronesia
MD	Moldova, Rep of
MC	Monaco
MN	Mongolia
ME	Montenegro
MS	Montserrat
MA	Morocco
MZ	Mozambique
MM	Myanmar
NA	Namibia
NR	Nauru
NP	Nepal
NL	Netherlands
AN	Netherlands Antilles
NC	New Caledonia
NZ	New Zealand
NI	Nicaragua
NE	Niger
NG	Nigeria
NU	Niue
NF	Norfolk Island
MP	Northern Mariana Islands
NO	Norway
OM	Oman
PK	Pakistan
PW	Palau
PS	Palestinian Territory, Occupied
PA	Panama
PG	Papua New Guinea
PY	Paraguay
PE	Peru
PH	Philippines
PN	Pitcairn Islands
PL	Poland
PT	Portugal
PR	Puerto Rico
QA	Qatar
RE	Reunion
RO	Romania
RU	Russian Federation
RW	Rwanda
WS	Samoa
SM	San Marino
ST	Sao Tome and Principe
SA	Saudi Arabia
SN	Senegal
RS	Serbia
SC	Seychelles
SL	Sierra Leone
SG	Singapore
SK	Slovakia
SI	Slovenia
SB	Solomon Islands
SO	Somalia
ZA	South Africa
ES	Spain
LK	Sri Lanka
SH	St Helena
KN	St Kitts and Nevis
LC	St Lucia
PM	St Pierre and Miquelon
VC	St Vincent and Grenadines
SD	Sudan
SR	Suriname
SZ	Swaziland
SE	Sweden
CH	Switzerland
SY	Syria
TJ	Tajikistan
TW	Taiwan, Rep of China
TZ	Tanzania
TH	Thailand
TL	Timor-Leste
TG	Togo
TK	Tokelau
TO	Tonga
TT	Trinidad and Tobago
TN	Tunisia
TR	Turkey
TM	Turkmenistan
TC	Turks and Caicos Islands
TV	Tuvalu
UG	Uganda
UA	Ukraine
AE	United Arab Emirates
GB	United Kingdom
VI	United States Virgin Islands
US	United States of America
UY	Uruguay
UZ	Uzbekistan
VU	Vanuatu
VA	Vatican City
VE	Venezuela
VN	Viet Nam
WF	Wallis and Futuna Islands
EH	Western Sahara
YE	Yemen
ZM	Zambia
ZW	Zimbabwe

Test Cards

These card numbers can be used when testing your integration to the payment gateway. These cards will not work for live transactions.

Card number	Type	CVV	MPI
4000 0000 0000 0002	Visa	123	No
4111 1111 1111 1111	Visa	123	Yes
4444 3333 2222 1111	Visa	123	Yes
4444 4244 4444 4440	Visa	123	Yes
4444 4444 4444 4448	Visa	123	Yes
4012 8888 8888 1881	Visa	123	Yes
5105 1051 0510 5100	Mastercard	123	No
5454 5454 5454 5454	Mastercard	123	Yes
5555 5555 5555 4444	Mastercard	123	Yes
5555 5555 5555 5557	Mastercard	123	Yes
5581 5822 2222 2229	Mastercard	123	Yes
5641 8209 0009 7002	Maestro UK	123	Yes
6767 0957 4000 0005	Solo	123	No
3434 343434 34343	American Express	1234	No
3566 0020 2014 0006	JCB	123	No
3111 1111 1111 1111	MADA	123	No

When these card numbers are used with a transaction class that requires the card security data (such as e-commerce transactions) then you should use the value 123 for all cards except for American Express which requires 1234.

For e-commerce transactions, cards which show ‘Yes’ in the MPI column will use a simulated 3D Secure authentication page, allowing you to test the transaction flow when Verified by Visa or MasterCard SecureCode is used.

Simulating decline/error responses

When it test mode, and when using the above test cards, you can simulate any of the transaction response codes by using specific values for the card security code (CVV). By taking the response code you want to simulate, pad that code with a leading ‘0’ in order to make it a 3 digit code and use that for the CVV.

For example, to simulate the Insufficient Funds response (status ‘D’, code ‘41’) use 041 as the CVV.

You can also simulate an on-hold transaction in the same way. On hold is where the transaction has been authorised, but the anti-fraud system has flagged the transaction for inspection. Whilst the transaction is on-hold, no funds will be debited from the customers’ card. You would need to use the Merchant Administration System to either accept or reject the transaction. To simulate the on-hold response within the test system, use a CVV value of ‘999’ with one of the above test cards.

Downloads

Card Change in Repeat Billing Agreement

New Feature in Repeat Billing Agreement

Save Card Option

Set Future Cancel Date – Repeat Billing

ApplePay Integration Guide