1. Home
  2. Developers
  3. Remote API Integration Guide

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.

You will need to request a remote integration for your account; this is not enabled by default.

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:

URLResponse format
https://secure.telr.com/gateway/remote.htmlHTTP parameter format
https://secure.telr.com/gateway/remote.txtPlain text
https://secure.telr.com/gateway/remote.xmlXML 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 nameCharacters allowed (hex code)
Basic Latin0009, 000A, 000D, 0020-007E
Latin-1 Supplement00A0-00FF
Latin Extended-A0100-017F
Latin Extended-BLatin 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 TypeE-CommerceMail/Telephone OrderContinuous Authority
SaleInitial (Requires PCI DSS)Initial (Requires PCI DSS)Follow-up
AuthInitial (Requires PCI DSS)Initial (Requires PCI DSS)Not Available
VerifyInitial (Requires PCI DSS)Initial (Requires PCI DSS)Not Available
VoidFollow-upFollow-upFollow-up
CaptureFollow-upFollow-upNot Available
ReleaseFollow-upFollow-upNot Available
RefundFollow-upFollow-upFollow-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

DescriptionParameterInitial TransFollow-up
Core transaction data
Store IDivp_storeRequiredRequired
Authentication key (Note 1)ivp_authkeyRequiredRequired
Transaction typeivp_trantypeRequiredRequired
Transaction classivp_tranclassRequiredRequired
Transaction descriptionivp_descRequiredRequired
Transaction cart ID (Note 2)ivp_cartRequiredRequired
Transaction currency (Note 3)ivp_currencyRequiredRequired
Transaction amount (Note 4)ivp_amountRequiredRequired
Previous transaction reference (Note 5)tran_refNot usedRequired
Test mode (Note 6)tran_refRequiredRequired
Card details
Card numberivp_cnRequiredNot used
Expiry date – month (Note 7)ivp_exmRequiredNot used
Expiry date – year (Note 7)ivp_exyRequiredNot used
CVV (Note 8)ivp_cvConditionalNot used
Card holder details
Title (Mr, Mrs, etc)bill_titleOptionalNot used
Forenamesbill_fnameRequiredNot used
Surnamebill_snameRequiredNot used
Street address – line 1bill_addr1RequiredNot used
Street address – line 2bill_addr2OptionalNot used
Street address – line 3bill_addr3OptionalNot used
Citybill_cityRequiredNot used
Region/State (Note 9)bill_regionOptionalNot used
Country (Note 10)bill_countryRequiredNot used
Zip/Area/Postcode (Note 9)bill_zipOptionalNot used
Email addressbill_emailRequiredNot used
Phone number (Note 9)bill_phone1OptionalNot used
IP Address (Note 11)bill_ipConditionalNot used
Delivery details (Note 12)
Not used
Title (Mr, Mrs, etc)delv_titleOptionalNot used
Forenamesdelv_fnameConditionalNot used
Surnamedelv_snameConditionalNot used
Street address – line 1delv_addr1ConditionalNot used
Street address – line 2delv_addr2OptionalNot used
Street address – line 3delv_addr3OptionalNot used
Citydelv_cityConditionalNot used
Region/State (Note 9)delv_regionOptionalNot used
Country (Note 10)delv_countryConditionalNot used
Zip/Area/Postcode (Note 9)delv_zipOptionalNot used
Phone number (Note 9)delv_phone1OptionalNot used
Extra data fields (Note 13)Not used
Extra data elementsxtra_*OptionalNot 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
authSeek 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.
captureDebit 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.
releaseRelease 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.
saleImmediate 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.
refundCredit the amount specified back to the card holder. A refund can be processed
against a sale or capture transaction.
voidCancel either a sale, refund or capture transaction. This can only be done within a few
hours of the transaction you are attempting to cancel.
verifyConfirm that the card details given are valid. No funds are reserved or taken from the
card.
ivp_tranclass
motoProcess as Mail Order / Telephone Order.
ecomProcess as an Internet based E-Commerce transaction. The use of 3-D Secure is
mandatory for this class of transaction.
contProcess 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.

FieldDescription
auth_statusAuthorisation status. A indicates an authorised transaction. Any other value
indicates that the request could not be processed.
auth_codeIf 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_messageThe authorisation or processing error message.
auth_tranrefThe payment gateway transaction reference allocated to this request.
auth_cvvResult of the CVV check:
Y = CVV matched OK
N = CVV not matched
X = CVV not checked
E = Error, unable to check CVV
auth_avsResult 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:

Scheme3-D Secure brand name
VisaVerified by Visa
MasterCardSecureCode
JCBJ/Secure
American ExpressSafeKey

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.

NOTE: 3-D Secure is mandatory for E-Commerce class transactions.

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.

NOTE: 3-D Secure is mandatory for E-Commerce class transactions.

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:

URLResponse format
https://secure.telr.com/gateway/remote_mpi.htmlHTTP parameter format
https://secure.telr.com/gateway/remote_mpi.txtPlain text
https://secure.telr.com/gateway/remote_mpi.xmlXML 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 nameCharacters allowed (hex code)
Basic Latin0009, 000A, 000D, 0020-007E
Latin-1 Supplement00A0-00FF
Latin Extended-A0100-017F
Latin Extended-BLatin Extended-B

HTTP URL Parameters

DescriptionParameter
Core transaction data
Store IDivp_store
Authentication keyivp_authkey
Transaction typeivp_trantype - Must be ‘sale’
Transaction classivp_tranclass - Must be ‘ecom’
Transaction cart IDivp_cart
Transaction descriptionivp_desc
Transaction currency (Note 1)ivp_currency
Transaction amount (Note 2)ivp_amount
Test mode (Note 3)ivp_test
Card details
Card numberivp_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.

FieldDescription
mpi_sessionSession reference for this transaction. Must be included in the remote
transaction processing request that is sent to authorise the transaction.
mpi_acsurlThe URL of the Access Control Server to be used for the additional
authentication stage, if any
mpi_pareqData 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:

DescriptionParameter
MPI Session IDmpi_session
Authentication responsempi_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.

It is also important to note that as of 2004, Visa and MasterCard have prohibited the use of pop-up pages for 3-D Secure

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.

You must replace the example values given below with actual valid details for your store, such as your actual store ID and authentication key, and the actual product/cost details.

$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);

To keep the sample code provide short and easy to read, no error detection or error handling is included. You must check that the curl request has worked as expected (status result of 200 OK), and that you have valid response data.

Authorisation Response codes

StatusCodeMessage
ASet by issuerAuthorised
HSet by issuerAuthorised, but placed on hold. Manual inspection required
E01Invalid request
E02Transaction cost or currency not supplied
E03Cart ID not set
E04Invalid store ID
E05Transaction cost or currency not valid
E06Invalid transaction mode
E07Card expiry not supplied
E10Card number not supplied
E11Invalid card number
E12Card expired
E14Card type mismatch
E15Invalid card security code (CVV)
E16Card security code (CVV) not supplied
E17Name not valid/not supplied
E18Address not valid/not supplied
E19Country not valid/not supplied
E20IP address not valid/not supplied
E21Card/Currency/Class combination not supported
E22Invalid transaction reference
E23Amount differs from original
E24Currency differs from original
E25Original transaction not authorised
E26Original transaction already voided
E27Original transaction mismatch
E28Invalid start date
E29Amount greater than available balance
E30Card details differ from original
D31Not authorised
D32Original transaction cannot be voided
C33Transaction cancelled
D34No response
E35Unable to refund
E36Previous transaction is on hold
D37Blocked by acquirer
E38Invalid expiry date
E39Invalid expiry date
E40Invalid transaction type
D41Insufficient funds
D42Card security code (CVV) mismatch
E43Email not valid/not supplied
E44Phone number not valid/not supplied
E45Transaction mode differs from original
D463DSecure authentication not available for this card
D473DSecure authentication rejected
E48Description not set
D49Sold out
E50Card is for ATM use only
D51Transaction part 1 not authorised
D52Transaction part 2 not authorised
X53Authorisation expired
E54Transaction part not specified
E55Unable to access transaction part
E56Duplicate transaction
D57Continuous authority not available on referenced transaction
E58Error connecting to service provider
E59Request aborted
E60Verification failed
D61Not authorised
D62Not authorised
D63Address verification (AVS) mismatch
D64Card security code (CVV) and address (AVS) mismatch
D65Card is not enabled for e-commerce
D66Card cancelled
D67Transaction not permitted by issuer
D68No suitable account
D80Not authorised
Card Filter module. Message text can be changed
D90Not authorised
D91Not authorised
D92Not authorised
D93Card limits exceeded
D94Not authorised
D95Not authorised
D96Not authorised
E98Internal system error
E99Unknown 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

AEDUnited Arab Emirates Dirham
BHDBahraini Dinar
CADCanadian Dollar
EGPEgyptian Pound
EUREuro
IDRIndonesian Rupiah
GBPPound Sterling
JODJordanian Dinar
JPYJapanese Yen
KHRCambodian Riel
KWDKuwaiti Dinar
MYRMalaysian Ringgit
OMROmani Rial
PHPPhilippine Peso
QARQatari Rial
SARSaudi Riyal
SGDSingapore Dollar
THBThai Baht
USDUS Dollar
VNDVietnamese Dong
INRIndian Rupee

ISO Country Codes

ISOCountry
AFAfghanistan
ALAlbania
DZAlgeria
ASAmerican Samoa
ADAndorra
AOAngola
AIAnguilla
AGAntigua and Barbuda
ARArgentina
AMArmenia
AWAruba
AUAustralia
ATAustria
AZAzerbaijan
BSBahamas
BHBahrain
BDBangladesh
BBBarbados
BYBelarus
BEBelgium
BZBelize
BJBenin
BMBermuda
BTBhutan
BOBolivia
BABosnia and Herzegovina
BWBotswana
BRBrazil
IOBritish Indian Ocean Territory
VGBritish Virgin Islands
BNBrunei Darussalam
BGBulgaria
BFBurkina Faso
BIBurundi
KHCambodia
CMCameroon
CACanada
CVCape Verde
KYCayman Islands
CFCentral African Rep
TDChad
CLChile
CNChina
CXChristmas Island
CCCocos (Keeling) Islands
COColombia
KMComoros
CDCongo, Democratic Rep of
CGCongo, Republic of
CKCook Islands
CRCosta Rica
CICote d'Ivoire
HRCroatia
CUCuba
CYCyprus
CZCzech Rep
DKDenmark
DJDjibouti
DMDominica
DODominican Rep
ECEcuador
EGEgypt
SVEl Salvador
GQEquatorial Guinea
EREritrea
EEEstonia
ETEthiopia
FKFalkland Islands
FOFaroe Islands
FJFiji
FIFinland
FRFrance
GFFrench Guyana
PFFrench Polynesia
GAGabon
GMGambia
GEGeorgia
DEGermany
GHGhana
GIGibraltar
GRGreece
GLGreenland
GDGrenada
GPGuadeloupe
GUGuam
GTGuatemala
GNGuinea
GWGuinea-Bissau
GYGuyana
HTHaiti
HNHonduras
HKHong Kong
HUHungary
ISIceland
INIndia
IDIndonesia
IRIran
IQIraq
IEIreland
ITItaly
JMJamaica
JPJapan
JOJordan
KZKazakhstan
KEKenya
KIKiribati
KPKorea, North
KRKorea, South
KWKuwait
KGKyrgyzstan
LALaos
LVLatvia
LBLebanon
LSLesotho
LRLiberia
LYLibya
LILiechtenstein
LTLithuania
LULuxembourg
MOMacau
MKMacedonia
MGMadagascar
MWMalawi
MYMalaysia
MVMaldives
MLMali
MTMalta
MHMarshall Islands
MQMartinique
MRMauritania
MUMauritius
YTMayotte
MXMexico
FMMicronesia
MDMoldova, Rep of
MCMonaco
MNMongolia
MEMontenegro
MSMontserrat
MAMorocco
MZMozambique
MMMyanmar
NANamibia
NRNauru
NPNepal
NLNetherlands
ANNetherlands Antilles
NCNew Caledonia
NZNew Zealand
NINicaragua
NENiger
NGNigeria
NUNiue
NFNorfolk Island
MPNorthern Mariana Islands
NONorway
OMOman
PKPakistan
PWPalau
PSPalestinian Territory, Occupied
PAPanama
PGPapua New Guinea
PYParaguay
PEPeru
PHPhilippines
PNPitcairn Islands
PLPoland
PTPortugal
PRPuerto Rico
QAQatar
REReunion
RORomania
RURussian Federation
RWRwanda
WSSamoa
SMSan Marino
STSao Tome and Principe
SASaudi Arabia
SNSenegal
RSSerbia
SCSeychelles
SLSierra Leone
SGSingapore
SKSlovakia
SISlovenia
SBSolomon Islands
SOSomalia
ZASouth Africa
ESSpain
LKSri Lanka
SHSt Helena
KNSt Kitts and Nevis
LCSt Lucia
PMSt Pierre and Miquelon
VCSt Vincent and Grenadines
SDSudan
SRSuriname
SZSwaziland
SESweden
CHSwitzerland
SYSyria
TJTajikistan
TWTaiwan, Rep of China
TZTanzania
THThailand
TLTimor-Leste
TGTogo
TKTokelau
TOTonga
TTTrinidad and Tobago
TNTunisia
TRTurkey
TMTurkmenistan
TCTurks and Caicos Islands
TVTuvalu
UGUganda
UAUkraine
AEUnited Arab Emirates
GBUnited Kingdom
VIUnited States Virgin Islands
USUnited States of America
UYUruguay
UZUzbekistan
VUVanuatu
VAVatican City
VEVenezuela
VNViet Nam
WFWallis and Futuna Islands
EHWestern Sahara
YEYemen
ZMZambia
ZWZimbabwe

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 numberTypeCVVMPI
4000 0000 0000 0002Visa123No
4111 1111 1111 1111Visa123Yes
4444 3333 2222 1111Visa123Yes
4444 4244 4444 4440Visa123Yes
4444 4444 4444 4448Visa123Yes
4012 8888 8888 1881Visa123Yes
5105 1051 0510 5100Mastercard123No
5454 5454 5454 5454Mastercard123Yes
5555 5555 5555 4444Mastercard123Yes
5555 5555 5555 5557Mastercard123Yes
5581 5822 2222 2229Mastercard123Yes
5641 8209 0009 7002Maestro UK123Yes
6767 0957 4000 0005Solo123No
3434 343434 34343American Express1234No
3566 0020 2014 0006JCB123No

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.

Updated on January 30, 2017

Related Articles