Most Common Support Issues

Payment Gateways

Payment Gateways are the heart of uCollect. You can have more than one gateway, but each contact may only be assigned to a single gateway. If you have a contact where some invoices are collected by Credit Card and others by Direct Debit/eCheck then you will need to split them into two contacts in Xero or uCollect will attempt to collect from only one of these methods.

There are two types of gateways:

Direct: Direct gateways are where we send the transaction direct to the gateway through the internet (using a secure transaction method known as an API). Once you have properly configured your gateway and contact we do not need to remind you or ask for any additional verification. We will simply initiate the collection for the due date as instructed. Once the gateway has confirmed that the request has been received we will record the payment in Xero in anticipation of the receipt of the funds.

Upload: Upload gateways do not allow API transactions (so last century) so we need you to intervene in the process. We wish it wasn’t like this, but we have to work within the limitations of each gateway. Rather than sending the transaction direct to the gateway, we alert you when a transaction needs to be generated and then you have to upload the file to the gateway (detailed instructions are below, in Step 3).

There are three steps to working with a gateway that you need to understand.

1. Setting up the Payment Gateway

You set up gateways when you first create the organisation. You can add, delete or modify a gateway at any stage from the Edit Organisation page. The Payment Gateway screen contains three possible sections:

Gateway Data

Please select the country that your bank account is based in – this will generate a list of eligible gateways for you to select from.  If you country is not listed then we do not currently have any gateways that will work in your country (to the best of our knowlegde).  Feel free to contact us and tell us what gateway(s) you are using and we can see if we can integrate with them.


Payment Gateway: This drop-down list allows you to select the gateway. Once you have created the gateway this field can not be changed (you will need to delete and start again).

Xero Bank Account: This field lists all Bank Accounts and all Payment-Enabled ledger accounts in Xero. The account you select here is the account that the payment will be recorded in. You can choose any bank or payment-enabled account you like. For some pointers on using a clearing account instead of your main bank account please read our “Special Cases” page.

Description: You can change the description to anything you like. You can add the same gateway type twice using two different descriptions. This would be used when, for example, one gateway processes both direct debits and credit cards or where you need to use a different bank account for some settlements. This field is what you will see in the rest of the system.

Instructions: If there are any special instructions they will be displayed here. You should always read these thoroughly as they may provide special instructions or information necessary to get the system to work correctly.

Gateway Authentication: If your gateway needs a key to authenticate you then we will ask for it here. The name varies by gateway. We will validate this key with the gateway before allowing you to complete the gateway definition.

Commission/Fees on Settlement

If your gateway settles it’s transactions by deducting the commission/fees it charges you from the deposit you receive then you can use uCollect to calculate and post these fees.  You can combine a flat rate per transaction and a percentage of the charge in the calculation.  Please note that your percentage or transaction charge must be the same for all transactions for uCollect to calculate it.  If you charges are likely to vary by transaction or settlement then you should NOT use this feature.

Also, please note that this is calculated for each batch processed by uCollect and may not exactly match the settlement cycle processed by your gateway.  We will create a new fee entry every time uCollect generates payments through (1) the scheduled daily batch, (2) the Process Now/Generate Now feature, and (3) when a customer uses the Pay Now feature.

If your settlement account (“Xero Bank Account”) is a Bank account type then uCollect will create a Spend Money transaction.  If it is not a bank account (i.e., another account type with payments enabled”) then uCollect will create a Bill and mark it as paid against the settlement account.

Calculate Commission/Fees on Settllement

Calculate Commission/Fees on Settlement: Check this box to activate the feature.  If you un-check this box your commission data will be removed from the system.

Per Transaction $ Amount: This is the amount that will be calculated for each transaction in the settlement batch.  uCollect adds up the number of settlement transactions (which may be less than the number of invoices if some invoices are for the same contact) and multiplies this by the amount given (rounded to 2 decimal points).  Your bank account (or base currency for non-bank accounts) is always used.  If there is no per transaction fee then please enter zero.

Per Transaction Commission %: This is the percentage that will be multiplied against the transaction amount.  Do not include the percent sign (e.g., for 2.9% enter “2.9”).  Please see “Calculate batch total per line” below for more details on the calculation method.

Xero Account to code Fee to: This is a list of all expense accounts from your ledger.  Please choose one to charge the settlement fee against.

Tax Rate to apply to fee: This is a list of all the tax rates from your ledger.  Please choose one to be used when creating the settlement fee.

Supplier Name for Fees: This is a list of all supplier contacts from your ledger.  Please choose one use as the contact for the settlement fee.  If the desired contact is not listed you may need to create them in Xero and add a bill against them to trigger them as a supplier (rather than a customer).

Calculate batch total per line: If this option is checked then uCollect will round the % commission to 2 decimal places on each line before adding them up.  If this option is unchecked then uCollect will only round the total to d decimal points.  If you find that your settlement fee is often out by a few cents then change this setting.

Make available as a Pay Now option

This option allows your customer to click on a link in the invoice email or PDF sent from Xero and then pay the invoice, multiple and even sign up for automatic charging using your uCollect payment gateways.

Make available as a Pay Now option: check this box to enable the Pay Now feature.  This check box is only available if the Pay Now feature is available for this gateway type (so you won’t see it on all gateways).

Description for Pay Now service: Enter a description for the pay now service – this is what will be displayed to the user if you have multiple options under the heading “pay using”.  We suggest that you say “Credit Card” rather than “Stripe” (as your customer will be thinking “I want to pay with my Credit Card” not “Oh – I really want to use Stripe”).

Send Admin an email when a customer activates a recurring option:  If you want to receive an email every time a customer selects the ongoing authority (so that you can send them flowers, of change their branding theme in Xero to notify them that their account will be charged automatically).

For full details please refer to the Pay Now/Payment Services page.

Additional Data


The content of this section will vary by gateway – and some gateways have no additional data required. The data requested here will relate to your organisation, and never to your contacts/customers. In many cases it is data that will help us process the payment or data that may appear on the bank statement of your customers. You should pay particular attention to the examples and ensure that you format your data EXACTLY as shown. We can not validate anything in these fields so they are passed to your gateway exactly as you enter them. If you do not know what you should enter here please read the instructions and then call the gateway’s help desk if you still do not know what to enter. In most cases you should not leave an entry blank.

Customer Data


The content of this section will vary by gateway – and some gateways have no customer data required. This section will contain any questions that we need to ask about your contact in the Edit Contact screen. In this screen all you need to enter is the DEFAULT value that will be displayed back to you when you assign a contact to this gateway. A blank entry here is fine. You can enter “[Invoice]” (without the quotation marks) and uCollect will automatically replace it with the invoice number(s) of the invoices that are being collected, or “[Contact]” to insert the contact name.
When you are done press the “Update” button. If applicable we will validate the authentication data. If the gateway rejects it we will alert you.

2. Connecting the Contact to the Payment Gateway

Please see the Edit Contact page.

3. Initiating the Collection Request

Every day uCollect will log into your Xero ledger to see if there are any payments to collect for your connected contacts. We do this at the time specified in your Organisation Settings (“uCollect Processing Time”). We look for payments that are overdue or due within the number of days you have specified in your Organisation Settings (“Number of days in advance to initiate”).

For example, Heavenly Pizza is set to initiate at 2pm UTC, and select invoices 2 days in advance. The contact “Hungry Office” is connected to the gateway in uCollect and has the following approved invoices in Xero:

• INV-0010 for $100.00 due on 15/3/15
• INV-0011 for $565.00 due on 16/3/15
• INV-0016 for $51.65 due on 17/3/15
• INV-0017 for $199.00 due on 20/3/15

At 2pm on March 16 2015 uCollect logs into Xero and check’s Heavenly Pizza’s invoices for Hungry Office. It will select all invoices that are due on or before March 18 2015 (being March 16 plus two days). A collection request for $716.65 will be initiated for March 18 for Invoices INV-0010, INV-0011 and INV-0016. Invoice INV-0017 will not be initiated until March 18.

For Direct gateways there is nothing that you need to do – we will send the request directly to the gateway. If the gateway accepts the request we will mark it as paid in Xero in anticipation of receiving the payment. If the gateway returns an error as we request the transaction then we will not mark the invoice as paid and will send you an email. We will automatically re-try the collection tomorrow.

For Upload gateways we can’t send the request directly. Here’s what will happen when we detect that a payment is required for an Upload-type gateway:

  1. We will send you an email alerting you. We will email you every day until you have completed the suggested action. If you do not respond the payment will not be initiated. For this reason we strongly suggest that you set the number of days in advance that we should initiate to 2 or 3. This allows plenty of margin for delay over weekends etc.
  2. You will log into uCollect. On the Search Contacts and the Collection History screens you will see the following message reminding you that there are transactions that need your intervention.
  3. When you click “Generate Now” you will be shown a list of the various gateways that have pending transactions. If you do not want to generate one gateway right away you can de-select it.
  4. Click “Process all Selected Batches Now”.
  5. uCollect will generate the transaction files and process the impending payments against the invoices in Xero.
  6. uCollect will send the text files to upload to your browser (as a downloaded file). If you can’t see them then you can download them from the “Collection Result” screen (which will display automatically) or from the Collection History screen any time in the next day.

It is important that you upload these files to your financial institution right away as uCollect has now told Xero to expect the payment and will not remind you again if you forget to upload the file to your bank.

If your gateway notifies you that a payment has failed then you will need to reverse the payment in Xero. More information on this is in our “Special Cases” page.