Reference
Need help?

Request layout

Requests to the Mobile API endpoint generate a link to the Hosted Payment Pages to securely capture the customer’s card details, rather than handling them directly within your App. This approach removes the need for PCI-DSS certification, as the App does not interact with or store any card data.

Transactions processed via this method can still serve as the basis for future continuous-authority transactions if needed. Additionally, the Hosted Payment Page will automatically manage any 3-D Secure authentication without requiring further action from the App.

Steps for Generating a Hosted Payment Page Request:

  1. Set the Transaction Type to 'PayPage': This specifies that the Hosted Payment Page will handle the card details.
  2. Exclude Card Details: You must not include any card information, such as card number, expiry date, or CVV, in the request.
  3. Provide Customer Information: Where possible, include as much customer information as possible (e.g., name, address) to simplify the payment process for the user.If these details are not provided, the Hosted Payment Page will prompt the customer to input them.
  4. Email Address is Mandatory: The customer’s email address must be included in the request, as it is required for the payment process.
<?xml version="1.0" encoding="UTF-8"?>
<mobile>
	<store>Store ID</store>
  <key>Authentication Key (Note 1)</key>
  <device>
    <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>
  </device>
  <app>
    <name>Application name</name>
    <version>Application version</version>
    <user>Application user ID (Note 5)</user>
    <id>Application installation ID</id>
  </app>
  <tran>
    <test>Test mode (Note 6)</test>
    <type>paypage</type>
    <class>ecom</class>
    <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>
  </tran>
  <billing>
    <name>
      <title>Title</title>
      <first>Forenames (Note 13)</first>
      <last>Surname (Note 13)</last>
    </name>
    <address>
      <line1>Street address – line 1 (Note 13)</line1>
      <line2>Street address – line 2</line2>
      <line3>Street address – line 3</line3>
      <city>City</city>
      <region>Region</region>
      <country>Country (Note 14)</country>
      <zip>Zip/Area/Postcode</zip>
    </address>
    <phone>Mobile number</phone>
    <email>Email address</email>
  </billing>
  <delivery>
    <name>
      <title>Title</title>
      <first>First Name</first>
      <last>Last Name</last>
    </name>
    <address>
      <line1>Street address – line 1</line1>
      <line2>Street address – line 2</line2>
      <line3>Street address – line 3</line3>
      <city>City</city>
      <region>Region</region>
      <country>Country</country>
      <zip>Zip/Area/Postcode</zip>
    </address>
    <phone>Mobile number</phone>
  </delivery>
  <custref>Customer Reference</custref>
  <paymethod>
    <type>Payment Method Type</type>
    <cardtoken>Card Token</cardtoken>
    <stcpayid>STC Pay ID</stcpayid>
  </paymethod>
  <repeat>
    <auto>true</auto>
    <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>
  </repeat>
  <filter>
    <bins>
      <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>
    </bins>
  </filter>
</mobile>

Notes:

  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 https://www.iban.com/country-codes.
  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: https://docs.telr.com/reference/repeat-billing

*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.