Remote creation of invoices

If you have an existing invoicing system and want to link it to the USER.COMPANY_NAME 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 USER.COMPANY_NAME 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>

   <!-- ── Core fields ─────────────────────────────────────────────────── -->
   <store>Store ID</store>
   <password>Remote access password</password>
   <title>Invoice title</title>
   <testmode>0=Live, 1=Test</testmode>
   <currency>Invoice currency – 3 character ISO code</currency>
   <amount>Invoice amount – major units (e.g. 12.95). Used on the payment page.</amount>
   <layout>Layout ID (1–3)</layout>

   <!-- ── Optional: repeat billing agreement ────────────────────────── -->
   <repeat>
      <amount>Recurring charge amount – major units (e.g. 12.95)</amount>
      <period>Billing cycle: W=weekly, M=monthly</period>
      <interval>Periods between charges (1–12)</interval>
      <start>First billing date – DDMMYYYY or: next / first / last / mid</start>
      <term>Total number of charges – 0=unlimited, 1–48=fixed term (optional)</term>
      <final>Amount for last charge, fixed term only – major units (optional)</final>
      <auto>1=card-based auto-charge, 0/absent=invoice-based (optional)</auto>
      <type>Agreement type – only "unscheduled" supported currently (optional)</type>
   </repeat>

   <!-- ── Optional: early payment offer ─────────────────────────────── -->
   <!-- If included, all four fields are required.                       -->
   <early>
      <day>Early payment day (1–31)</day>
      <month>Early payment month (1–12)</month>
      <year>Early payment year – 4 digits</year>
      <amount>Early payment amount</amount>
   </early>

   <!-- ── Optional: late payment penalty ────────────────────────────── -->
   <!-- If included, all four fields are required.                       -->
   <!-- Invoices displayed after this date will be marked as overdue.   -->
   <late>
      <day>Late payment day (1–31)</day>
      <month>Late payment month (1–12)</month>
      <year>Late payment year – 4 digits</year>
      <amount>Late payment amount</amount>
   </late>

   <!-- ── Recipient details ──────────────────────────────────────────── -->
   <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>

   <!-- ── Invoice details (items, totals, notes) – see below ────────── -->
   <details>
      [ Invoice details section. See below. ]
   </details>

</invoice>

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

Repeat billing

The <repeat> block is optional. If omitted, the endpoint behaves exactly as before.

When a repeat billing agreement is created, <invoice><amount> is used as the immediate charge at the time of invoice payment. The <repeat><amount> applies to all subsequent recurring charges.

Two different amounts, two different roles:

<invoice><amount> — charged immediately when the customer pays the invoice. Sent in major units.
<repeat><amount> — charged on each subsequent recurring cycle. Sent in integer minor units.

If you want the first and recurring charges to be the same value, both fields must still be supplied — they are not linked automatically.

Amount format

When sending amounts, follow the correct format for processing:

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

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 <invoice><amount>.

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 USER.COMPANY_NAME Payment Gateway to handle payment collection. This allows you to leverage your existing system while using USER.COMPANY_NAME 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 USER.COMPANY_NAME system.
• Including the Payment URL: You can embed the payment URL, which is provided in the response from the USER.COMPANY_NAME 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.