Hosted Payment Page integration guide

Introduction

This integration method allows for real-time processing of payments and ensures a maximum number of up-to-date payment methods. The Hosted Payment Page service is a secure PCI DSS compliant system, use of which does not require the merchant to have their own PCI compliance as card details are held only within the payment gateway. This is the fastest way to get up and running with on-line payments.

This integration method uses HTML messages to pass information between your site and the payment gateway. It is the simplest and easiest method of integration and will work on just about any platform.

There is nothing to install with the Hosted Payment Page method of integration. All you need is a working Internet connection and your store ID.

How the Hosted Payment Page works

The Hosted Payment Page service allows your website with its own shopping system to work in conjunction with our payment service. This integration method uses HTTP request from your systems to the gateway to send the transaction details and obtain the appropriate URL to direct the customer to in order to complete the purchase.

1. When a shopper is ready to pay for their goods, your server should generate a request to the gateway transmitting the details of the purchase. The response to this request contains an order reference and the URL for completing the transaction.
2. Your systems direct the shopper to the hosted payment pages using the transaction URL provided. Here they enter their payment details, such as credit/debit card details. Your website does not gather card details from the shopper – we do this in our payment pages.
3. We forward the shopper’s details to the bank, where the shopper’s credit worthiness is checked. The bank returns an authorised or declined response to us. The shopper is then returned to your site, and you can use the order reference obtained in step 1 to query the results of the transaction.

The pages displayed by the Hosted Payment Page service can be customised to suit your website style and presentation.

Request method and format

All transaction requests must be sent to the Hosted Payment Page gateway URL:

https://secure.telr.com/gateway/order.json

The minimum information that needs to be sent is the cost and currency for the purchase, a purchase description, your store ID and authentication key, and the return URL for your store (the URL the shopper will be sent to once the transaction process has been completed) The HTTP POST data fields that contain the basic purchase information are as follows:

Field	Description	Notes
ivp_method	The request method being used	Set to ‘create’ to generate a new transaction.
ivp_store	Your store ID	Numeric value only, no text. For example, 1234 not 1234 - Store name
ivp_authkey	Your authentication key
ivp_amount	Transaction amount	In major units, for example 9 dollars 50 cents must be sent as 9.50 not 950
ivp_currency	Currency the transaction is in	3 character ISO code.
ivp_test	Test mode indicator	0 = Live, 1 = Test
ivp_cart	Cart ID / Order ID	Your reference for the transaction. For example, this could be a cart ID or order ID generated by your shopping system. This must be unique for each request. Maximum length is 63 characters.
ivp_desc	Purchase description	Maximum length is 63 characters.
return_auth	URL for authorised transactions	These are URLs within your site, where the shopper will be directed to once the transaction process is complete.
return_decl	URL for declined transactions
return_can	URL for cancelled transactions

Request Response

The response from the transaction request will contain an order reference and a transaction URL if the request was accepted, otherwise it will contain an error block.

The response is formatted as JSON.

Order created

{
  "method":"create",
  "order":{
    "ref":"OrderRef",
    "url":"https://secure.telr.com/gateway/process.html?o=OrderRef"
  }
}

Error

{
  "method":"create",
  "error":{
    "message":"E56:Duplicate transaction",
    "note":"Cart ID must be unique"
  }
}

If the request has been accepted, then your systems should store the order reference provided (as this will be needed to query the order status later) and then direct the customer to the given URL. This can be done using a Location: redirect, as a link or as a form. It can use either the GET or POST method.
The created order reference is only valid for a short time, you should direct the customer to the given URL as soon as possible after creating the reference.

Optional additional request fields

In addition to the basic transaction request fields (such as the amount and description fields, shown in the Request Method section above) there are other fields that can be included within the request that can alter the way the request is processed.

Supplying customer details

If your systems have the customer details available (such as through a customer registering with your site) then you should include the customer’s name, address and email information as part of the request.

This improves the payment experience for the customer, as it removes the need for them to re-enter details that they have already supplied.

You can send these details by including the following fields with the transaction request:

Field	Description	Notes
bill_title	The customer’s title.	Optional. If used, this should be a value such as ‘Mr’, ‘Mrs’ etc. It does not refer to details such as job title.
bill_fname	Forenames	The customer’s forename, plus any other middle names or initials they may have.
bill_sname	Surname	Customer surname (also known as family name)
bill_addr1	Address line 1
bill_addr2	Address line 2	Optional
bill_addr3	Address line 3	Optional
bill_phone	Customer Mobile number
bill_city	City
bill_region	Region/State	Optional
bill_country	Country	Must be supplied as a 2 character ISO 3166 country code.
bill_zip	Post/Area/Zip code	Optional
bill_email	Email address
ivp_lang	Payment Page interface language	Optional. If used, this should be a value of "en" or "ar" which are the currently supported languages
ivp_trantype	Transaction Type	Optional. configured default in merchant admin is used if not set>
ivp_update_url	Transaction advice service type URL	Optional. Set a transaction advice service type URL on a per transaction basis

If any part of the customer details are not supplied, or if they are not valid, then the payment pages will prompt for the correct details. For example, if you have supplied name and email but not their address, then the payment pages will only ask for the address.

For the name to be accepted, both the bill_fname and bill_sname values must be set and valid.

For the address to be accepted, bill_addr1, bill_city and bill_country must be set and valid.

It is always best to send this information with the request whenever possible, as that improves the customer experience of completing the transaction and reduces cart abandonment. However, it is important that only valid information collected from the customer is used – pre-set values to try and avoid collecting the data will cause transaction processing problems, and is against card processing
rules.

Stored Cards (Returning Customers)

The Hosted Payment Pages can provide customers with the option to store their card details for future use, making it simpler for a customer to complete the checkout process the next time they purchase from your store.

• There are some key requirements in order to enable stored cards:
• The acquiring bank that your merchant account is with must support continuous authority transactions.
• Your store must be operating from a HTTPS server.
• You must have a method of identifying each individual customer, with a unique ID for each.
• Customers must be required to provide some form of authentication (such as username and password) within your store. This must be done using a HTTPS server.
• Customer authentication details (such as their password) must be securely managed within your system, and must only be stored using strong hashing algorithms with a random salt for each hash.

To enable the stored card system, you first need to select the ‘Stored cards’ option within the payment page configuration in the Merchant Admin System (the page that shows your authentication key). You then need to modify your integration to include your unique customer ID in the transaction request.

Field	Description	Notes
bill_custref	Unique customer ID	Optional. If set, the customer may be given the option to store their card for future use if the transaction is authorised, and will be presented with a list of stored cards (if any) at the start of a transaction.

Repeat Billing

The Repeat Billing system gives merchants who use the Hosted Payment Pages the ability to setup and manage automatic recurring payments, such as those used in a subscription service. The ability to directly debit a card for each payment depends upon your acquiring bank allowing ‘Continuous Authority’ transactions for your merchant account.

Payment Agreements

The Repeat Billing System allows you to create and manage what are termed Payment Agreements. These Payment Agreements specify the value and frequency of the payments to be made. Payment Agreements can be for a fixed term, or for an unlimited term.

There elements that form a Payment Agreement are as follows:

• Initial payment amount
• Payment period (Monthly or Weekly)
• Payment interval (Interval between payment periods, e.g. every 2 weeks)
• Regular payment amount
• Start date (when to start the regular payments)
• Term (how many payments to take)
• Final payment amount (Any additional final payment to take after the last regular payment)

With these elements it is possible to create Payment Agreements that suit most subscription requirements or other regular payment requirements.

Sending the payment agreement details

The details are sent as part of the transaction request using the following fields:

Field	Description	Notes
repeat_amount	Regular payment amount	The amount to be taken at each payment interval.
repeat_period	Agreement billing period	This can be set to either ‘M’ (Months) or ‘W’ (Weeks)
repeat_interval	Number of Weeks/Months between each payment	Set to 1 to bill every month/week (as per billing period).
repeat_start	Agreement start date	Formatted as DDMMYYYY. The start date cannot be the same date that the agreement is made on, and cannot be a date that has already past.
repeat_term	Agreement term	Indicates the number of regular payments to take. Set this to zero to indicate an unlimited term.
repeat_final	Final payment amount	0 if there is no final payment amount. Final payment can only be set if there is a fixed term to the agreement.

All payment amounts are taken in the same currency as used for the main transaction request (as sent in the field). The amounts must be sent in major units (for example, 9 dollars 50 cents must be sent as 9.50 not 950).

Immediate Payment Amount

This specifies an amount to be taken at the same time that the agreement is setup. The immediate payment amount is sent as the ivp_amount field in the main transaction request.

Regular Payment Amount

This is the amount that will be taken from the card holder for each payment.

Agreement period and interval

The period must be set to either ‘M’ or ’W’, which relates to Months or Weeks. The interval must be an integer value between 1 and 12.

Examples
repeat_period=M repeat_interval=1	Payment taken every month
repeat_period=W repeat_interval=3	Payment taken every three weeks.

Agreement term

This is a number indicating how many regular payments are to be taken. Set this to zero to indicate an agreement that does not have a fixed term.

Examples
repeat_period=M repeat_interval=1 repeat_term=12	12 payments taken one month apart – agreement duration is 1 year.
repeat_period=M repeat_interval=3 repeat_term=0	Payments taken every quarter, no fixed term. Payments will continue until such time as the agreement is cancelled.

Start date

This indicates when the first regular payment should be taken. It is an 8 digit value, formatted as DDMMYYYY where DD = 2 digit day, MM = 2 digit month and YYYY = 4 digit year.

This date cannot be in the past, and cannot be the same date as the date the agreement is being made on (i.e. it cannot be today)

When the payment interval is specified in weeks, it will be taken on the same day of the week as the day that this date represents. For example, as the 1 st of May 2011 (01052011) is a Sunday, every payment would be taken on a Sunday.

When the payment interval is specified in months, it will be taken of the same day of the month as the day given here. In the event that this is scheduled for a day that not all months have, then the payment will be taken on the last day of the month instead. For example, a payment scheduled for the 30 th of each month would be taken on the 28 th (or 29 th ) of February, and on the 30 th for all other months.

The start date value can be supplied as the word ‘next’ in which case the first regular payment will be scheduled for one payment period on from today.

Examples
repeat_period=M repeat_interval=1 repeat_start=10082015	First payment to be taken on the 10 th of August 2015. Subsequent payments will be taken on the 10 th of each month.
repeat_period=W repeat_interval=2 repeat_start=13062015	First payment will be taken on the 13 th of June 2015. As that is a Saturday, subsequent payments will be taken every two weeks on a Saturday.
repeat_period=M repeat_interval=1 repeat_start=next	First payment will be taken 1 month from today. Subsequent payments will be taken on the same day of each month.

Final payment amount

This specifies an amount to be taken at the end of the agreement. This is only applicable for fixed term agreements (where repeat_term is non-zero). This final amount is in addition to any amount that would be taken as part of the regular payment processing. It will be taken at one payment interval following the last regular payment.

The total amount the customer will pay is as follows

For fixed term payments:

• Initial payment amount (ivp_amount)
• repeat_term * repeat_amount
• repeat_final

For unlimited term payments:

• Initial payment amount (ivp_amount)
• Continual payments of repeat_amount until the agreement is cancelled.

Google Analytics

The hosted payment pages can use the Google Analytics Measurement Protocol to send information on customer progress through the payment pages. You will need to provide your tracker ID, the customers Client ID, and details of the domain you want to record the events under.

Field	Description	Notes
ga_tid	Tracker ID	Your Google Analytics tracker ID
ga_cid	Client ID	The customers client ID
ga_dh	Your hostname	No protocol (such as http: etc), just the domain (e.g. www.site.com)
ga_dp	Document path	This will be used as a prefix to the path sent at each stage. It must start with ‘/’
ga_ds	Data source	Optional. If not set, then ‘web’ will be used.
ga_cn	Campaign name	Optional fields to allow you to specify any required campaign tracking values.
ga_cs	Campaign source
ga_cm	Campaign medium
ga_ck	Campaign keyword
ga_cc	Campaign content
ga_ci	Campaign ID
ga_gclid	AdWords ID
ga_dclid	Display Ads ID

The URL sent for each payment stage is constructed by adding the following to the value in ’ga_dp’

/telr/data_entry.html	Initial Data Entry
/telr/service_out.html	Redirect to service provider
/telr/service_back.html	Return from service provider
/telr/mpi_check.html	3D-Secure Enrolment Check
/telr/acs_out.html	Redirect to card issuer (3D Secure)
/telr/acs_back.html	Return from card issuer (3D Secure)
/telr/card_auth.html	Card authorisation request
/telr/authorised.html	Transaction authorised
/telr/declined.html	Transaction declined
/telr/cancelled.html	Transaction cancelled

If you have set ‘ga_dp’ to a value such as ‘/payments’ then the URLs sent to the analytics system would be ‘/payments/telr/data_entry.html’, ‘/payments/telr/mpi_check.html’ and so on.

Obtaining the client ID

You will need to get the client ID from the Google Analytics code you are operating on your site prior to sending the transaction request. If you are using the analytics.js method, then you can use the following code on your page to retrieve the client ID:

ga(function(tracker) {
    var clientId = tracker.get('clientId');
});

See https://developers.google.com/analytics/devguides/collection/analyticsjs/domains#getClientId for more details.

Transaction results

Once the shopper has been returned to your store (using one of the return URLs defined in the request, which can all be the same value if required) you can the query the order system to obtain the transaction status and other payment details.

This is done by sending a second server-to-server request from your systems to the gateway. This request must include the order reference obtained from the initial create order request.

The required fields for this request are as follows:

Field	Description	Description
ivp_method	The request method being used	Set to ‘check’ to get the status of an order.
ivp_store	Your store ID	Numeric value only, no text. For example, 1234 not 1234 - Store name
ivp_authkey	Your authentication key
order_ref	Order reference	Obtained from the create order request.

The request must be sent using HTTP POST to

https://secure.telr.com/gateway/order.json

The response is formatted as JSON. For completed transactions, the response will include the transaction details and the customer details. Empty fields will be omitted.

The results will show the order status, and if applicable the transaction status. Order status codes are as follows:

Order Status	Description
1	Pending
2	Authorised (Transaction not captured, such as an AUTH transaction or a SALE transaction which has been placed on hold)
3	Paid (Transaction captured, SALE transaction, not placed on hold)
-1	Expired
-2	Cancelled
-3	Declined

The transaction status codes are detailed at the end of this guide.

Order processed

{
  "method":"check",
  "order":{
    "ref":"OrderRef",
    "cartid":"Your Cart ID",
    "test":Test mode indicator,
    "amount":Transaction amount,
    "currency":"Transaction currency",
    "description":"Order description",
    "status":{
      "code":Order status code,
      "text":"Order status description"
    },
  "transaction":{
    "ref":"Transaction reference",
    "type":"Transaction type",
    "status":"Transaction status",
    "code":"Authorisation/Error code",
    "message":"Authorisation/Error message"
  },
  "customer":{
    "email":"Customer email address",
    "name":{
      "title":"Customer title",
      "forenames":"Customer forename",
      "surname":"Customer surname"
    },
  "address":{
    "line1":"Address line 1",
    "line2":"Address line 2",
    "line3":"Address line 3",
    "city":"City",
    "state":"Region","country":"ISO Country code",
    "areacode":"Post/Area/Zip code"
      }
    }
  }
}

Error

{
  "method":"check",
  "error":{
    "message":"E01:Invalid request",
    "note":"Invalid order reference"
  }
}

Payment page customisation

The payment page can be customised through the use of a CSS file. The core page display is based on the BootStrap 3 responsive layout. You should ensure that you are familiar with the underlying styles used within BootStrap before making any CSS changes. For more details on the BootStrap layout, please refer to: http://getbootstrap.com/css/

The page itself is constructed in sections. The top part of the page is where core branding information such as logos should be placed. This is also where the details of the transaction amount are shown.

Below this are the panels for the different payment methods available. If there are multiple payment methods, then the panels are presented as an accordion style display, where only one panel can be visible at any one time.

The main elements that can be styled are as follows:

div	.container	Wrapper around the content sections, sets the BootStrap grid system.
div	.content_header	Wrapper around the page header (jumbotron)
div	.content_body	Wrapper around the main page content (the panels)
div	.content_footer	Wrapper around the footer part of the page.
div	.jumbotron	Header section containing store name and payment details.
div	.panel-heading	Heading displayed when multiple panels are in use.
div	.panel-subheader	Individual panel heading
h4	.panel-title	The text element within a panel heading or sub header.
div	.panel-body	The main panel content, such as input fields.
button	.btn	Core button style used by all buttons.
button	.btn-success	Primary action button, default style is green.
button	.btn-danger	Cancel button, default style is red.
button	.btn-warning	Intermediate action button, default style is orange.
div	#collapse_card	Panel for card payments.
div	#collapse_qpay	Panel for payment using stored card details.
div	#collapse_sadad	Panel for the SADAD payment method.
div	#collapse_paypal	Panel for PayPal payments.
div	#collapse_mpass	Panel for MasterPass payments.

You should ensure you do not make any changes to the core Bootstrap classes, as doing so could adversely affect the payment page display. You should not change any of the following elements:

div	.col-*	These are the main elements that control the BootStrap responsive layout (e.g. .col-md-8, .col-xs-12, .visible-sm, .hidden-lg etc) and should not be altered. This is the BootStrap grid system.
div	.visible-*
div	.hidden-*
div	.row
div	.form-group	Bootstrap form handling
input	.form-control
div	.panel-collapse	Panel display controls, when used as part of an accordion they allow individual panels to be opened and closed.
div	.collapse
div	.in

Page element layout

<div class= " container " >
   <div class= " content_header " >
      <div class= " jumbotron " ></div>
   </div>
   <div class= " content_body " >
      <div class= " panel-group " id= " single_method " >
         <div class= " panel panel-default " >
            <div class= " panel-subheader " >
               <h4 class= " panel-title " ></h4>
            </div>
            <div id= " collapse_card " class= " panel-collapse collapse " >
               <div class= " panel-body " >
                  <button class= " btn btn-success " ></button>
                  <button class= " btn btn-warning " ></button>
               </div>
            </div>
         </div>
      </div>
   </div>
   <div class= " content_footer " ></div>
</div>

The following is for a page with multiple panels.

<div class=”container”>
   <div class= " content_header " >
      <div class= " jumbotron " ></div>
   </div>
   <div class= " content_body " >
      <div class= " panel-group” id=”accordion " >
         <div class= " panel panel-default " >
            <div class= " panel-heading " >
               <h4 class= " panel-title " ></h4>
            </div>
            <-- panel-heading only displayed when multiple panels are in use -->
            <div class= " panel-subheader " >
               <h4 class= " panel-title " ></h4>
            </div>
            <div id= " collapse_card " class= " panel-collapse collapse " >
               <div class= " panel-body " >
                  <button class= " btn btn-success " ></button>
                  <button class= " btn btn-warning " ></button>
               </div>
            </div>
            <div class= " panel-subheader " >
               <h4 class= " panel-title " ></h4>
            </div>
            <div id= " collapse_sadad " class= " panel-collapse collapse " >
               <div class= " panel-body " >
                  <button class= " btn btn-success " ></button>
                  <button class= " btn btn-warning " ></button>
               </div>
            </div>
            <-- panel-subheader & panel-collapse sections repeated as needed -->
         </div>
      </div>
   </div>
   <div class= " content_footer " ></div>
</div>

Uploading customisation files

Files can be uploaded using the Additional Files section within the payment page menu in the Merchant Administration System. You can upload the custom CSS file and any required images.

CSS

You can upload your custom style sheet by uploading a file titled ‘custom_pp2.css’

This file must be un-compressed CSS file, must not include any JavaScript, nor any references to other external css files. If it references images then those must be sourced from a secure (https) server. The best option is to upload those images to the payment gateway. To reference an image uploaded to the gateway use the sequence {{FileBase}} to have the correct URL inserted at that point – the URL will change depending on if the page is viewed in test or live mode.

For example, to reference an image uploaded as logo.png you should use the following:   url( ” {{FileBase}}logo.png ” )

Images

You can upload image files in gif, jpg or png format for use within the payment page customisation. These can be then be referenced from within your custom CSS. The maximum size of an image file is 256K.

iFrame Display

The payment pages can be displayed within an iFrame, giving the appearance of the payment page being contained entirely within your website.

To enable the framed display, you need to include an additional parameter within the ‘create order’ request. The parameter is ivp_framed and the values for this are as follows:

Value	Description
0 or not set	Standard full screen payment page
1	Framed payment page, with only payment methods that can operate directly from within a frame. Payment methods that require a full page display cannot be used. The customer will be returned to your site still within the frame.
2	Framed payment page as the initial display, but the process can break out of the frame to a full page display if required by any payment method. The customer will be returned to your site outside of the frame.

To avoid any issue in redirection due to blockers on customer’s browser, we recommend you to implement the below code for loading iFrame on our website.

*sandbox=’allow-forms allow-modals allow-popups-to-escape-sandbox allow-popups allow-scripts allow-top-navigation allow-same-origin’*

The frame that is displayed must be a minimum of 600 pixels wide and 550 pixels high.

After obtaining the URL from the create order request, this can then be used as the src value for the iframe. For example:

<style>
  #telr {
    width: 100%;
    min-width: 600px;
    height: 600px;
    frameborder: 0;
  }
</style>

<iframe id= " telr " src= " [url obtained from create order] " ></iframe>

When displayed within a frame, the payment page does not display the content-header section of the page (see payment page customization)

Verified by Visa and MasterCard SecureCode

After the consumer enters their card details, the payment gateway will check to see if that card is enrolled as part of the Verified by Visa or MasterCard SecureCode authentication systems (known as 3D-Secure).

If the card is part of one of these authentication systems, then an additional page is displayed which requires the relevant authentication details to be entered. This is usually in the form of a password that has been assigned by the consumer or via a one-time code sent to the customers mobile.

The actual data entry section is presented directly by the card issuer and cannot be customised. It is generally displayed on a white background.

Where possible the 3D-Secure authentication form is displayed over the payment page, allowing the customer to see that it is clearly part of the payment process.

JSON field map

The following shows the JSON transaction request and transaction check objects, along with the corresponding http form post field. Mandatory fields are shown in red.

JSON Field	Type	Form field
"method": "xxx"	String	ivp_method
"store": xxx	Integer	ivp_store
"authkey": "xxx"	String	ivp_cart
"framed": xxx	String	ivp_currency
"cartid": "xxx"	String
"test": xxx	Integer	ivp_test
"amount": xxx.xx	Number	ivp_amount
"currency": "xxx"	String	ivp_currency
"description": "xxx"	String	ivp_desc
"authorised": "xxx"	String	return_auth
"declined": "xxx"	String	return_decl
"cancelled": "xxx"	String	return_can
"email": "xxx"	String	bill_email
"title": "xxx"	String	bill_title
"forenames": "xxx"	String	bill_fname
"surname": "xxx"	String	bill_sname
"line1": "xxx"	String	bill_addr1
"line2": "xxx"	String	bill_addr2
"line3": "xxx"	String	bill_addr3
city": "xxx"	String	bill_city
"state": "xxx"	String	bill_region
"country": "xxx"	String	bill_country
"areacode": "xxx"	String	bill_zip
"ref": "xxx"	String	bill_custref
"amount": xxx.xx	Number	repeat_amount
"interval": xxx	Integer	repeat_interval
"period": "xxx"	String	repeat_period
"term": xxx	Integer	repeat_term
"final": xxx.xx	Number	repeat_final
"start": "xxx"	String	repeat_start
"tid": "xxx"	String	ga_tid
"cid": "xxx"	String	ga_cid
"dh": "xxx"	String	ga_dh
"dp": "xxx"	String	ga_dp
"ds": "xxx"	String	ga_ds
"cn": "xxx"	String	ga_cn
"cs": "xxx"	String	ga_cs
"cm": "xxx"	String	ga_cm
"ck": "xxx"	String	ga_ck
"cc": "xxx"	String	ga_cc
"ci": "xxx"	String	ga_ci
"gclid": "xxx"	String	ga_gclid
"dclid": "xxx"	String	ga_dclid

Transaction Check	Type	Form field
"method": "xxx"	String	ivp_method
"store": xxx	Integer	ivp_store
"authkey": "xxx"	String	ivp_authkey
"ref": "xxx"	String	order_ref

When creating the JSON object, you must only include the elements for which you have an appropriate value and which relate to options that you are actually using. For example, if you are not using the Google Analytics options, then do not include the ga {} object. If you are not sending customer details, do not include the customer{} object. If you are sending customer details such as name and address, but not a customer reference, then do not include the “ref” element within the customer {} object.

Example JSON Request 

{
  "method": "create",
  "store": <store_id>,
  "authkey": "<store authkey>",
  "order": {
    "cartid": "0123456789",
    "test": "1",
    "amount": "100",
    "currency": "AED",
    "description": "Test Transaction"
  },
  "customer": {
    "ref": "2020",
    "email": "[email protected]",
    "name": {
      "forenames": "John",
      "surname": "Smith"
    },
    "address": {
      "line1": "5 th street",
      "city": "Dubai",
      "country": "AE"
    },
    "phone": "0123456789"
  },
  "return": {
    "authorised": "http://www.example.com/",
    "declined": "http://www.example.com/",
    "cancelled": "http://www.example.com/"
  }
}

Transaction Status 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

You should not limit status codes to only those listed above as transaction status codes are subject to change/addition.

You should only accept codes ‘A’ or ‘H’ as authorised, any other status indicates that the transaction has not been authorised.

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

The available currency codes on your account are determined by the merchant accounts you have with your acquiring bank. You can only process transactions in those currencies. Submitting a transaction request in a currency that is not available on your account will result in the request being rejected.

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

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

The card security code (CVV) to use with the test cards is 123 (except for American Express, which should be 1234) for an authorised response, other codes will be declined.

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.

Example order creation

The following shows an example of creating an order using PHP.

$params = array(
        'ivp_method'  => 'create',
        'ivp_store'   => 'Your Store ID',
        'ivp_authkey' => 'Your Authentication Key',
        'ivp_cart'    => 'UniqueCartID',  
        'ivp_test'    => '1',
        'ivp_amount'  => '100.00',
        'ivp_currency'=> 'AED',
        'ivp_desc'    => 'Product Description',
        'return_auth' => 'https://domain.com/return.html',
        'return_can'  => 'https://domain.com/return.html',
        'return_decl' => 'https://domain.com/return.html'
    );


$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://secure.telr.com/gateway/order.json");
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);
$results = json_decode($results,true);
$ref= trim($results['order']['ref']);
$url= trim($results['order']['url']);
if (empty($ref) || empty($url)) {
# Failed to create order
}