1. Home
  2. Developers
  3. Hosted Payment Page integration guide

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:

FieldDescriptionNotes
ivp_methodThe request method being usedSet to ‘create’ to generate a new transaction.
ivp_storeYour store IDNumeric value only, no text. For example, 1234 not 1234 - Store name
ivp_authkeyYour authentication key
ivp_amountTransaction amountIn major units, for example 9 dollars 50
cents must be sent as 9.50 not 950
ivp_currencyCurrency the transaction is in3 character ISO code.
ivp_testTest mode indicator0 = Live, 1 = Test
ivp_cartCart ID / Order IDYour 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_descPurchase descriptionMaximum length is 63 characters.
return_authURL for authorised transactionsThese are URLs within your site, where
the shopper will be directed to once the
transaction process is complete.
return_declURL for declined transactions
return_canURL for cancelled transactions

The create order request must be sent using a server-to-server method (such as using curl from within php) – it must not be sent via the customer’s browser.

Test mode requests can be sent from any IP address, but live mode requests will only be accepted from a pre-approved list of IPs (the IP address details for your production systems will be required prior to any live processing)

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:

FieldDescriptionNotes
bill_titleThe 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_fnameForenamesThe customer’s forename, plus any other
middle names or initials they may have.
bill_snameSurnameCustomer surname (also known as family name)
bill_addr1Address line 1
bill_addr2Address line 2Optional
bill_addr3Address line 3Optional
bill_cityCity
bill_regionRegion/StateOptional
bill_countryCountryMust be supplied as a 2 character ISO
3166 country code.
bill_zipPost/Area/Zip codeOptional
bill_emailEmail address
ivp_langPayment Page interface languageOptional. If used, this should be a value of "en" or "ar" which are the currently supported languages
ivp_trantypeTransaction TypeOptional. configured default in merchant admin is used if not set>
ivp_update_urlTransaction
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.

FieldDescriptionNotes
bill_custrefUnique customer IDOptional. 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.

The bill_custref field must not be set if the checkout is not for a registered customer – such as if the customer is using a guest checkout option, or if they have not yet registered within your store.

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:

FieldDescriptionNotes
repeat_amountRegular payment amountThe amount to be taken at each payment
interval.
repeat_periodAgreement billing periodThis can be set to either ‘M’ (Months) or ‘W’ (Weeks)
repeat_intervalNumber of Weeks/Months
between each payment
Set to 1 to bill every month/week (as per billing period).
repeat_startAgreement start dateFormatted 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_termAgreement termIndicates the number of regular payments to take. Set this to zero to indicate an unlimited term.
repeat_finalFinal payment amount0 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.

FieldDescriptionNotes
ga_tidTracker IDYour Google Analytics tracker ID
ga_cidClient IDThe customers client ID
ga_dhYour hostnameNo protocol (such as http: etc), just the
domain (e.g. www.site.com)
ga_dpDocument pathThis will be used as a prefix to the path sent
at each stage. It must start with ‘/’
ga_dsData sourceOptional. If not set, then ‘web’ will be used.
ga_cnCampaign nameOptional fields to allow you to specify any
required campaign tracking values.
ga_csCampaign source
ga_cmCampaign medium
ga_ckCampaign keyword
ga_ccCampaign content
ga_ciCampaign ID
ga_gclidAdWords ID
ga_dclidDisplay Ads ID

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

/telr/data_entry.htmlInitial Data Entry
/telr/service_out.htmlRedirect to service provider
/telr/service_back.htmlReturn from service provider
/telr/mpi_check.html3D-Secure Enrolment Check
/telr/acs_out.htmlRedirect to card issuer (3D Secure)
/telr/acs_back.htmlReturn from card issuer (3D Secure)
/telr/card_auth.htmlCard authorisation request
/telr/authorised.htmlTransaction authorised
/telr/declined.htmlTransaction declined
/telr/cancelled.htmlTransaction 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:

FieldDescriptionDescription
ivp_methodThe request method being usedSet to ‘check’ to get the status of an
order.
ivp_storeYour store IDNumeric value only, no text. For
example, 1234 not 1234 - Store name
ivp_authkeyYour authentication key
order_refOrder referenceObtained 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 check order request must be sent using a server-to-server method (such as using curl from within php) – it must not be sent via the customer’s browser.

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

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

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.containerWrapper around the content sections, sets the BootStrap grid
system.
div.content_headerWrapper around the page header (jumbotron)
div.content_bodyWrapper around the main page content (the panels)
div.content_footerWrapper around the footer part of the page.
div.jumbotronHeader section containing store name and payment details.
div.panel-headingHeading displayed when multiple panels are in use.
div.panel-subheaderIndividual panel heading
h4.panel-titleThe text element within a panel heading or sub header.
div.panel-bodyThe main panel content, such as input fields.
button.btnCore button style used by all buttons.
button.btn-successPrimary action button, default style is green.
button.btn-dangerCancel button, default style is red.
button.btn-warningIntermediate action button, default style is orange.
div#collapse_cardPanel for card payments.
div#collapse_qpayPanel for payment using stored card details.
div#collapse_sadadPanel for the SADAD payment method.
div#collapse_paypalPanel for PayPal payments.
div#collapse_mpassPanel 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-groupBootstrap form handling
input.form-control
div.panel-collapsePanel 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:

ValueDescription
0 or not setStandard full screen payment page
1Framed 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.
2Framed 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 use framed mode your store must be operating under https, not http.

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 customisation)

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 FieldTypeForm field
"method": "xxx"
Stringivp_method
"store": xxxIntegerivp_store
"authkey": "xxx"Stringivp_cart
"framed": xxxString
ivp_currency
"cartid": "xxx"String
"test": xxxIntegerivp_test
"amount": xxx.xxNumberivp_amount
"currency": "xxx"Stringivp_currency
"description": "xxx"Stringivp_desc
"authorised": "xxx"Stringreturn_auth
"declined": "xxx"Stringreturn_decl
"cancelled": "xxx"Stringreturn_can
"email": "xxx"Stringbill_email
"title": "xxx"Stringbill_title
"forenames": "xxx" Stringbill_fname
"surname": "xxx"Stringbill_sname
"line1": "xxx"Stringbill_addr1
"line2": "xxx"Stringbill_addr2
"line3": "xxx"Stringbill_addr3
city": "xxx"Stringbill_city
"state": "xxx"Stringbill_region
"country": "xxx"Stringbill_country
"areacode": "xxx"Stringbill_zip
"ref": "xxx"Stringbill_custref
"amount": xxx.xxNumberrepeat_amount
"interval": xxxIntegerrepeat_interval
"period": "xxx"Stringrepeat_period
"term": xxxIntegerrepeat_term
"final": xxx.xxNumberrepeat_final
"start": "xxx"Stringrepeat_start
"tid": "xxx"Stringga_tid
"cid": "xxx"Stringga_cid
"dh": "xxx"Stringga_dh
"dp": "xxx"Stringga_dp
"ds": "xxx"Stringga_ds
"cn": "xxx"Stringga_cn
"cs": "xxx"Stringga_cs
"cm": "xxx"Stringga_cm
"ck": "xxx"Stringga_ck
"cc": "xxx"Stringga_cc
"ci": "xxx"Stringga_ci
"gclid": "xxx"Stringga_gclid
"dclid": "xxx"Stringga_dclid
Transaction Check TypeForm field
"method": "xxx"Stringivp_method
"store": xxxIntegerivp_store
"authkey": "xxx"Stringivp_authkey
"ref": "xxx"Stringorder_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": "test@test.com",
    "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

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

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

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

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

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

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

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.

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

$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
}

 

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), that you have a valid json object as the response, and that you have correctly decoded the json object.

Updated on September 6, 2017

Related Articles