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.
- 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.
- 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.
- 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": "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
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 }