Remote creation of invoices

If you have an existing invoicing system and want to link it to the Innovate Payments 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 Innovate Payments servers, 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, you must create a password in the remote section of the invoice configuration page. All remote requests must include this password in order to be accepted.

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 sent in UTF-8 encoding. In order to allow processing via the global card network, only certain characters can be used. These are:

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>

Amounts must be sent in major units, without any currency symbols. Commas must not be used between digit groups, and the minor amount (e.g. pence or cents) must be sent after a decimal point.

Valid amounts:
12.95
1234.56

Invalid amounts:
$12.95 1,234.56

The early and late payment sections are optional, but if used they must contain a valid date and amount or the request will be rejected. If a late payment section is used, then invoices that are displayed after the date set will be shown as overdue.

Note: Repeat object "type" is used to indicate if the transaction will be used for subsequent authorization. Currently supported value is "unscheduled", other values will be ignored.

Details section

This is where the actual invoice content (such as the item descriptions, totals and any notes) is supplied. No content validation is performed on this data, so you should ensure that the amounts shown within the invoice content match the total amount that is specified as the invoice amount.

There are three elements to the details section, the first of which is the actual invoice items. The fields used to specify the items depend on which layout has been 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 have an existing invoicing system that can send invoice emails, you can still use the Innovate Payments gateway to collect the payment.

The method of use is exactly the same as for the remote creation of invoices described earlier in this document, with the exception that the //details// part of the request must not be supplied.

If that section is omitted, then an invoice reference and payment URL will still be generated, but no email will be sent. The payment URL that is provided in the response from the Innovate Payments system should be included within your invoice to act as a link to the payment process.

Options such as early/late payment amounts can still be specified. The recipient details must still be provided.