Remote creation of invoices

If you have an existing invoicing system and want to link it to the Telr Payment invoice system, you can use the remote interface to generate new invoices. This interface is a XML based system that allows you to send the complete details of the invoice into the Telr Payment server, which will in turn generate the invoice email and add the invoice details into the list of invoices available on the system.

To enable the remote interface for the e-invoicing system, you must first create a password within the Remote section of the invoice configuration page. This password is mandatory for all remote requests; any request without the password will be rejected.

Remote requests must be sent using the HTTP POST method to the following URL:

https://secure.telr.com/gateway/invoice_create.xml

All data must be transmitted in UTF-8 encoding. To ensure compatibility with global card networks, only specific characters can be used in the request data. These characters include:

XML Request layout

<invoice>
   <store>Store ID</store>
   <password>Remote access password</password>
   <title>Invoice title</title>
   <testmode>Test mode (0=Live, 1=Test)</testmode>
   <currency>Invoice currency – 3 character ISO code</currency>
   <amount>Invoice amount – this is what is used on the payment page</amount>
	 <repeat>
     		<type>unscheduled</type>
	 </repeat>
   <layout>Layout ID (1-3)</layout>
   <early>
        <day>Early payment day (1-31)</day>
        <month>Early payment month (1-12)</month>	NOTE: Early payment
        <year>Early payment year – 4 digits</year>	details are optional
        <amount>Early payment amount</amount>
   </early>
   <late>
        <day>Late payment day (1-31)</day>
        <month>Late payment month (1-12)</month>	NOTE: Late payment
        <year>Late payment year – 4 digits</year>	details are optional
        <amount>Late payment amount</amount>
   </late>
   <recipient>
        <name>
              <title>Title</title>
              <first>Forenames</first>
              <last>Surname</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 – 2 character ISO code</country>
              <zip>Zip/Area/Postcode</zip>
        </address>
        <email>Email address</email>
    </recipient>
    <details>
          [ Invoice details section. See below. ]
    </details>
</invoice>

When sending amounts in the e-invoicing system, it's important to follow the correct format for processing:

• Amounts must be sent in major units, such as dollars or euros, without any currency symbols.
• Commas must not be used between digit groups.
• The minor amount (such as cents or pence) should follow a decimal point.

Example of Valid Amounts:

• 12.95
• 1234.56

Example of Invalid Amounts:

• 12.95
• 1,234.56

The early and late payment sections are optional, but if included, they must contain valid dates and amounts. Otherwise, the request will be rejected. If the late payment section is used, invoices displayed after the specified date will be marked as overdue.

📘

The "repeat" object uses the type parameter to indicate whether the transaction will be used for subsequent authorization. Currently, the supported value is "unscheduled". Any other values will be ignored.

Details section

The details section contains the actual content of the invoice, such as item descriptions, totals, and notes. It's important to note that no content validation is performed on this data, so it is the merchant's responsibility to ensure that the amounts within the invoice details match the total invoice amount specified.

The details section consists of three elements, the first being the invoice items. The format for specifying these items depends on the layout selected.

Layout 1: Basic invoice with a simple item and cost entry for each line.

  <item>  
       <text>Product description</text>  
       <cost>Product cost</cost>  
   </item>

Layout 2: Unit cost and quantity can be specified for each item.

 <item>  
      <text>Product description</text>  
      <cost>Product unit cost</cost>  
      <quantity>Product quantity</quantity>  
      <amount>Amount due</amount>  
 </item>

Layout 3: Unit cost, quantity and a discount can be specified for each item.

  <item>  
        <text>Product description</text>  
        <cost>Product unit cost</cost>  
        <quantity>Product quantity</quantity>  
        <discount>Any discount given</discount>  
        <amount>Amount due</amount>  
   </item>

There can be multiple item entries per invoice, but there must be at least one item present. The second section is the totals section. This is the same for each layout.

   <total>  
         <text>Total description</text>  
        <amount>Total amount</amount>  
   </total>

There can be multiple total entries per invoice, but there should be at least one total entry present. You should ensure that the amount shown in the last total entry matches the amount that will be charged for the invoice. If no total entries are sent, then a single line will be used with the text description set to ‘Total’ and with the amount set to the value given in .

The third section is the notes section. This is the same for each layout.

  <note>  
        <text>Note details</text>  
  </note>

There can be multiple note entries per invoice. This is an optional section; there is no requirement for any notes to be present.

Sample details section

<details>
  <item>
     <text>Item 1</text>
     <cost>100.00</cost>
  </item>  
  <item>  
     <text>Item 2</text>  
     <cost>25.00</cost>  
   </item>  
   <total>  
      <text>Sub Total</text>  
      <amount>125.00</amount>  
   </total>  
   <total>  
      <text>Postage</text>  
      <amount>9.95</amount>  
   </total>  
   <total>  
      <text>Total</text>  
      <amount>134.95</amount>  
    </total>
</details>

Response details

If the invoice has been generated, the response will contain the reference that has been allocated to that invoice, and the URL that will be used for payment.

   <invoice>
       <status>OK</status>
       <reference>Invoice Reference</reference>
       <url>Payment URL</url>
</invoice>

If the invoice could not be created, for example due to a problem within the invoice details, the response will contain a message describing the error that has occurred.

   <invoice>  
       <status>Error</status>  
       <message>Error details</message>  
   </invoice>

Linking to existing email invoices

If you already have an invoicing system that can send invoice emails, you can integrate it with the Telr Payment Gateway to handle payment collection. This allows you to leverage your existing system while using Telr to process payments.

Usage Overview:
The process for using the payment gateway is identical to the remote creation of invoices, as described earlier. The only difference is that the details section of the request should not be included.

Key Points:

• Omitting the Details Section: If the details section is omitted, the system will still generate an invoice reference and a payment URL. However, no email will be sent from the Telr system.
• Including the Payment URL: You can embed the payment URL, which is provided in the response from the Telr Payments system, directly within your existing invoice. This URL will serve as a link to the payment process.

Additional Options:

• You can still specify early or late payment amounts.
• Recipient details must still be provided in the request for proper invoice processing.