Need help?

Request layout

Requests to Mobile API endpoint will generate a link to Hosted Payment Pages to capture the customer’s card details, rather than having them entered directly into your App.

This removes PCI-DSS certification requirements for your application, as it is no longer handling any card data. Transactions processed in this way can still be used as the base for any future continuous-authority transactions if required. The Hosted Payment Page method will automatically handle any 3-D Secure pages without any further action required from the App.

To generate a Hosted Payment Page request, set the transaction type field to ‘PayPage’. You must not include any card details (card number, expiry or cvv). Where possible, you should provide as much information about the customer as you can (name and address) as this will simplify the payment process for the customer. If these details are not supplied, then the Hosted Payment Page will prompt for them. The customers email address must be supplied.

<?xml version="1.0" encoding="UTF-8"?>
	<store>Store ID</store>
  <key>Authentication Key (Note 1)</key>
    <type>Mobile device type (Note 2)</type>
    <id>Mobile device ID (Note 3)</id>
    <agent>WebView user agent header (Note 4)</agent>
    <accept>WebView accept header (Note 4)</accept>
    <name>Application name</name>
    <version>Application version</version>
    <user>Application user ID (Note 5)</user>
    <id>Application installation ID</id>
    <test>Test mode (Note 6)</test>
    <cartid>Transaction cart ID (Note 7)</cartid>
    <description>Transaction description</description>
    <currency>Transaction currency (Note 8)</currency>
    <amount>Transaction amount (Note 9)</amount>
    <ref>Previous transaction reference (Note 10)</ref>
      <first>Forenames (Note 13)</first>
      <last>Surname (Note 13)</last>
      <line1>Street address – line 1 (Note 13)</line1>
      <line2>Street address – line 2</line2>
      <line3>Street address – line 3</line3>
      <country>Country (Note 14)</country>
    <phone>Mobile number</phone>
    <email>Email address</email>
      <first>First Name</first>
      <last>Last Name</last>
      <line1>Street address – line 1</line1>
      <line2>Street address – line 2</line2>
      <line3>Street address – line 3</line3>
    <phone>Mobile number</phone>
  <custref>Customer Reference</custref>
    <type>Payment Method Type</type>
    <cardtoken>Card Token</cardtoken>
    <stcpayid>STC Pay ID</stcpayid>
    <amount>Regular payment amount</amount>
    <interval>Payment interval (numeric)</interval>
    <period>Payment period (Monthly = M or Weekly = W)</period>
    <term>Number of payments to take</term>
    <final>Final amount after last regular payment</final>
    <start>Start date</start>
      <list1>Card range 1</list1>
      <list2>Card range 2</list2>
      <list3>Card range 3</list3>
      <list4>Card range 4</list4>
      <list5>Card range 5</list5>
      <list6>Card range 6</list6>
      <list7>Card range 7</list7>
      <list8>Card range 8</list8>


  1. The Authentication Key will be supplied by Telr as part of the Mobile API setup process after you request that this integration type is enabled for your account. This should not be stored permanently within the App.
  2. Description of the device the App is running on.
  3. Unique ID for the mobile device (such as identifierForVendor in iOS)
  4. The User-Agent and Accept headers that will be used in any webview based requests. These are required as part of E-Commerce class transactions. If no value is sent for these fields, then the gateway will use the headers that are sent as part of the mobile API request. See the section on 3-D Secure for more details.
  5. Your reference for the customer/user that is running the App. This should relate to their account within your systems.
  6. Test mode of zero indicates a live transaction. If this is set to any other value the transaction will be treated as a test.
  7. An example use of the cart ID field would be your own transaction or order reference.
  8. Currency must be sent as a 3 character ISO code. A list of currency codes can be found at the end of this document. For voids or refunds, this must match the currency of the original transaction.
  9. The transaction amount must be sent in major units, for example 9 dollars 50 cents must be sent as 9.50 not 950. There must be no currency symbol, and no thousands separators. The
    decimal part must be separated using a dot.
  10. The previous transaction reference is required for any continuous authority transaction. It must contain the reference that was supplied in the response for the original transaction.
  11. Card dates must be sent as a numeric values with a two digit month (01-12) and a 4 digit year (e.g. 2010)
  12. The requirement for the CVV (card security code) depends on the transaction class:
    Continuous Authority – Not Used
    Mo/To – Optional (* – see below)
    E-Commerce – Required
  13. Customer Email Address is the minimum required customer information for a transaction to be processed.
  14. Country must be sent as a 2 character ISO code. A list of 2 letter country codes can be found at
  15. Repeat section is utilized for passing subsequent (recurring) payment details. For more information on the repeat parameter details, please refer to the following link:

*Although the CVV is optional within the Telr Payments gateway for Mo/To class transactions, some acquiring banks may mandate this. Please check with Telr Payments support to confirm if this is required for your account.