- 03 Jun 2024
- 24 Minutes to read
- Print
Xero Payments Integration
- Updated on 03 Jun 2024
- 24 Minutes to read
- Print
Existing Helcim Merchants
The Xero integration is only intended for merchants using Helcim to receive payments on Xero invoices. If you use other Helcim payment tools, this integration will not function as intended and your clearing account in Xero will not balance to $0.00.
Connecting your Helcim and Xero Accounts
The first step to accepting payments for Xero invoices using Helcim is to sign in to your Helcim account. If you do not have a Helcim account, you can create an account for free, with no set up or monthly fees. Check out our website and select "Get Started".
Once you have signed into your Helcim account, you can activate the Xero Payments integration by following these six steps:
1. Use the “All Tools” menu and navigate to “Accounting Center”
2. Select “Xero Integration” from the menu
3. Select “Connect” on the integration interface
4. Complete the set up wizard
5. Start accepting payments for Xero invoices using Helcim! Simply navigate to Xero and send invoices using your selected branding theme.
During the set up Wizard, if eligible, you will see an option to select ACH as a payment method for your Xero invoices. To learn more about ACH payments with Xero, click here .
Important note about the Xero Connection:
The connection with Xero and Helcim is 1:1, meaning one Xero organization to one Helcim account.
If Xero organization A is connected to Helcim account A, the contacts and invoices will be imported and any due invoices will be collected for enabled contacts.
If Xero organization A is then disconnected from Helcim account A and connected to Helcim account B, the contacts and invoices from that account will sync to Helcim account B.
The Xero integration only supports one connection at a time, so any invoices from the original connection, Helcim account A, will not be collected automatically and new contacts and invoices will not be synced to the account.
Only invoicers on the active connection, Helcim account B, will be collected and new contacts and invoices synced to the account.
Limitations of the Integration
The integration with Xero is designed for Xero invoices to be paid easily using Helcim. The correct functioning of the integration is dependent on only payments from Xero invoices being processed in your Helcim account.
At this time, only the transaction data from your Xero invoices will appear in your Helcim clearing account in Xero. Other payments made using other Helcim tools will not appear in the clearing account, unless those invoices originated in Xero and were synced to Helcim. Do note, if you use other Helcim tools, your payout amount will be the total amount for all payments made through Helcim, meaning the payout will not reconcile with your Xero account balance.
For example, you process two transactions for Xero invoices for a total of $500 and you process several more transactions using the Virtual Terminal for a total of $2500. Your total payout will be $3000 minus fees. Your clearing account will not balance because the money received is $500 and the money spent is $3000. In order for your account to balance, you need to create the $2500 of virtual terminal transactions into Xero.
Setting up the Integration
When setting up the integration, you will be prompted to complete four tasks:
1. Select the Xero organization that you want to connect to your Helcim account.
Connections between Xero and Helcim are 1:1, meaning that you can connect one Helcim account to a single Xero organization. If you have multiple Helcim accounts, you can connect each one to the appropriate Xero organization. Your Helcim and Xero accounts must remain connected for the integration to work and for customers to pay invoices using Helcim. If the integration is disconnected, customers will receive an error message saying "Payment service is expired". You will also not receive fee and Bank Transfer data pushed in your Helcim clearing account in Xero.
2. Helcim clearing account is automatically created in the selected Xero organization.
The Helcim clearing account is where you can see your payments, fees and bank transfers from the invoices paid using Helcim. You can find the account named "Helcim" under your bank accounts section. The transactions are all auto-reconciled when added to your account and require no other actions. The Batch ID is used as the Payment Reference so you can easily see which payments, fees and transfers belong to which batch.
3. Select the bank account where payouts from Helcim are deposited.
This account is referred to as a payment account or deposit account. The account you select here should be the same account that you linked to your Helcim account for payouts. When a batch closes and your fees and deposit are calculated, both will be pushed to your Helcim Clearing account. The bank transfer will show as a "Spent" in the clearing account and the other side of that transaction will appear as a "Received" in your mapped bank account.
4. Select the expense account for Helcim's processing fees.
This step allows you to map which account from your Chart of Accounts (CoA) in Xero will be used for handling processing fees. The drop down list populates from all the available expense accounts in Xero. Helcim fees will be visible as a "Spent" transaction in your Helcim clearing account and as a "Debit" in the mapped expense account.
5. Select the invoices that you want Helcim to be available as a payment service.
In Xero, payment services are available for each invoice branding theme. When setting up the integration, all the branding themes from your Xero account will be available in a checklist and you can select which ones will use Helcim as a Payment Service. You must select at least one branding theme for the integration to work.
If you want to edit which payment services are available for each invoice branding theme you can do so by going to Xero and navigating to Settings -> Payment Services -> Manage Themes.
Multi-Currency with Xero
Multi-Currency Note
Please note that Multi-Currency is only available for Canadian Merchants who are set up to accept credit card payments in USD. If you want to accept payments in USD but have not yet set this up on your Helcim account, please contact our support team here . Multi-Currency is not available for ACH payments.
If you are able to accept payments in USD through your account, you will see an option to add an additional bank account when setting up your Xero integration. This will allow you to deposit USD credit card payments into a USD bank account.
Select the bank account you wish to use for your core currency first, then select 'Add a USD bank account'. Select the bank account from the drop down and hit 'Next'.
In order to select a second currency for Xero, you must have this currency added in your Helcim account. Instructions on how to add a second currency can be found here .
Continue mapping out your accounts from step 4 below.
Mapping Your Accounts
When setting up the setup wizard, you will be prompted to complete four steps:
1. Select the Xero organization that you want to connect to your Helcim account.
Connections between Xero and Helcim are 1:1, meaning that you can connect one Helcim account to one Xero organization. If you have multiple Helcim accounts, you can connect each one to the appropriate Xero organization. Your Helcim and Xero accounts must remain connected for the integration to work and for customers to pay invoices using Helcim. If the integration is disconnected, customers will receive an error message saying "Payment service is expired". You will also not receive fee and bank transfer data pushed in your Helcim clearing account in Xero.
2. Helcim Clearing Account is automatically created in the selected Xero organization.
The Helcim clearing account is where you can see your payments, fees, and bank transfers from the invoices paid using Helcim. You can find the account named "Helcim" under your bank accounts section on your Xero dashboard. The transactions are all auto-reconciled when added to your account and require no further actions. The Batch ID is used as the payment reference so you can easily see which payments, fees, and transfers belong to which batch.
3. Select the bank account where payouts from Helcim are deposited.
This account is referred to as a payment account or deposit account. The account you select here should be the same account that you linked to your Helcim account for payouts. When a batch closes and your fees and deposit are calculated, both will be pushed to your Helcim Clearing Account. The bank transfer will show as a "spent" in the clearing account and the other side of that transaction will appear as a "received" in your mapped bank account.
4. Select the expense account for Helcim's processing fees.
This step allows you to map which account from your Chart of Accounts (CoA) in Xero will be used for handling processing fees. The drop down list populates from all the available expense accounts in Xero. Helcim fees will be visible as a "spent" transaction in your Helcim Clearing Account and as a "debit" in the mapped expense account.
5. Select the invoices that you want Helcim to be available as a payment service.
In Xero, payment services are available for each invoice branding theme. When setting up the integration, all the branding themes from your Xero account will be available in a checklist and you can select which ones will use Helcim as a payment service. You must select at least one branding theme for the integration to work.
If you want to edit which payment services are available for each invoice branding theme you can do so by going to Xero and navigating to Settings → Payment Services → Manage Themes.
Using the Integration
Once the integration is set up, you can navigate back to your Xero account. There you can simply send invoices from the selected branding theme to customers and have them paid as normal.
Your customers will see a "Pay with Credit Card" button on these Xero invoices. To make a payment, they can click this button, enter their payment information, and select "Process Payment". When the invoice is paid, your Xero contact is saved as a customer in Helcim, including their tokenized payment information. For repeat customers, their name and payment information will be populated for them on future transactions so they can conveniently pay in just one-click.
Reconciling Payouts
When you receive payouts from Helcim, they will appear as a bank transfer in the “account transactions” tab of your Helcim Clearing Account. They appear here as "reconciled".
The other side of that transaction will require you to reconcile the bank transfer with the deposit in the mapped bank account or bank feed. To reconcile the payout:
Open the "reconcile" tab in your bank account
2. Find the Helcim deposit from your bank statement matched to the bank transfer created from the clearing account.
3. Select "OK"
4. The transaction is now reconciled!
Processing a Refund
There may be cases where you need to refund or reversed a payment received for a Xero invoice. In Helcim, you have the option to reverse a payment if the batch is still open. After a batch has closed, you have the option to refund the payment. Processing a refund will require actions in both your Helcim and Xero accounts.
STEP 1: Process the reverse or refund in Helcim
1. Go to the Payments section of your Helcim account
2. Select the transaction you want to reverse/refund
3. Select the "actions" menu and select the desired action
STEP 2: Record the Refund in Xero
1. In Xero, search the customer’s name you are refunding by selecting the magnifying glass in the top right hand corner and select their contact.
2. Under their contact, in the top left corner click on the "New" the drop-down and select the “sales credit note.”
STEP 3: Complete the credit note
Including the date you processed the refund, original invoice details, original invoice number for reference, and a description of why the payment is being refunded.
STEP 4: Issue a “Cash Refund”
Mark the Date it was refunded and what account it was paid from. For refunds, select the Helcim clearing account.
Note: For reversed transactions, you may also avoid credit notes by deleting the payment from the invoice.
STEP 5:
The paid credit note will appear in the account transactions tab of the selected bank account and can be reconciled. The refund will appear in your clearing account as a "Spent" transaction. The payout you receive for the batch including the refund will be less the refund and the associated fees. The bank transfer can then be reconciled to the payout that included the refund.
Refund Limitations
Refunds should be processed on a day where the payments you received are greater than the refund amount. If the refund is more than the total payments for the batch, the result is a negative deposit amount and a pull from your bank account. The integration cannot account for negative deposit amounts in your clearing account and will not import them.
Processing ACH payments with Xero
When first setting up your Xero integration through your Helcim account you will be asked which payment methods you want to accept. If you want to accept both credit card and ACH payments, select both boxes. If you are business that is not eligible for ACH payments you will only see the option for credit card.
If ACH is selected, when customers pay for invoices they will see the option for ACH on the payment Modal.
PAD Agreements Customers who have not processed payments before will be required to agree to either the terms of the Pre-authorized Debit Agreement (PAD-Canada) or ACH Mandate (US). PAD agreements will be accessible from the customer profile in your Helcim account.
ACH payments will appear in your Helcim clearing account in Xero as soon as your customer pays the invoice. The invoice will be marked as paid but the payment itself and the associated fees will not be visible for up to five business days.
ACH payments will be visible in the ACH transaction list in your Helcim account.
Some ACH payments may be returned or result in chargebacks. For more information on ACH returns, click here .
For a guide on how to manage returned ACH payments in your Xero account, please refer to Xero's support article - here .
Please note: Helcim Fee Saver is not currently compatible with Helcim's Xero integration.
Updating Payment Modal when Incorporating ACH
If you have ACH payments turned on for your Xero integration, by default, the payment modal customers see will still display, 'Pay by Credit Card'. To change this:
Navigate to your Xero account 'Settings'
Select 'Payment Services'
Select 'Edit' next to Helcim (This will only appear if you are connected to Helcim)
Select 'Service Details
In the Pay Now button test section, Change 'Pay with Credit Card' to your preferred payment option, e.g. 'Pay Now'.
Using other Helcim Payment Tools
Helcim's integration with Xero is designed to work for merchants that are using Helcim to have customers pay for Xero invoices. For merchants using other Helcim payment tools, the payout and fees posted to the Helcim clearing account will include all Helcim transactions, not just those from Xero. This means that gross total of payments in the clearing account will not equal the sum of payouts and fees, and the account balance will never be at $0.00.
Bank transfers from the clearing account are based on the payout from Helcim, so the bank transfer can be reconciled with the payout. Fees in the clearing account will also be accurate.
If you process any transactions outside of Xero, you will need to create those payments in Xero and also create the invoice if you want to reconcile those payments.
Create an invoice
There are two options for creating invoices in Xero for transactions in Helcim:
1. Create an invoice for each individual transaction by selecting "New Invoice" and inputting the same details as the invoice in Helcim, including applicable taxes.
2. Create in invoice for the gross transaction amount for the batch (excluding transaction in using the Xero integration), including the applicable taxes.
The decision about whether to put in the invoices individually or the entire batch as one depends on your accounting process. It may be helpful to consult with an accountant to determine the best option for your business.
Import invoices
It is possible to import your Helcim invoices into Xero:
STEP 1: Export invoices from Helcim
1. Go to the Invoicing section of your helcim account
2. Select the Import/Export tab
3. Select Export as a CSV file
STEP 2: Import into Xero
1. Download the Xero invoice template CSV file
2. Export your invoices from Helcim as a comma separated list. Using Excel, google sheets or another spreadsheet editor, copy and paste your invoices from the exported file into the Xero template. Make sure the invoice data you copy matches the column headings provided in the Xero template.
3. Import the update CSV file into Xero.
Create Payments
Now that the invoices have been created in Xero, you can created the required payments.
The important thing to remember is that these payments should be visible in your Helcim clearing account so that your account balances with the bank transfers and fees that are created in that account.
Create payments using the following steps:
1. View the newly created invoice, whether for individual transaction or a batch
2. Find the "receive a payment" section at the bottom
3. Input the payment amount, date paid, and select your Helcim clearing account from the "Paid to" drop down
4. Select "add Payment"
5. View your Helcim Clearing account in Bank Account section
6. Confirm the payment was created in the "Account Transactions" tab
7. Reconcile the new payment (if you choose)
Now that you have created the payments for the transactions processed outside the Xero integration, your clearing account can balance and will reflect that payouts and fees in your Helcim account.
Using Xero Auto-Collect
NOTE
Contacts in Xero are only synced to Helcim if they are a customer. A newly created contact without a previous invoice is not identified as a customer. To have a Xero contact imported to Helcim without a due invoice, we recommend creating a draft invoice for them so that the system recognizes them as a customer.
What is Auto-Collect?
With Auto-Collect, you can now set up customers to have payments processed automatically when a Xero invoice is due. This means you don’t have to manually send the invoice, your customer doesn't have to click into an invoice and enter their payment information—it’ll all be done automatically. Set it up once and Helcim will use the stored payment information for the customer for any invoices you create in Xero going forward.
Customizing your Auto-Collect workflow
Auto-Collect offers a few options that all work together to allow invoices in Xero to be automatically paid on the invoice due date. You can select how much manual control or automation you would like from the feature.
You have the option to have Helcim send payment information request emails automatically to ensure you have payment information on hand before an invoice is due. Alternatively, you also have the ability to manually control when and how you’d like to obtain this information.
You also have the option to have Auto-Collect enabled for all contacts or to manual select who to turn it on for at a per contact level.
You can alter the settings once the setup is completed from the Xero Integrations settings page.
Choosing Invoices
To enable Xero Auto-Collect, as part of the integration set up, you will see the option to set Helcim as the default provider for types of Xero invoices:
This allows all due invoices wherein Helcim has been added as a Payment Service to the invoice branding theme, to be imported from Xero to Helcim.
Only Xero invoices that have been approved and are awaiting payment will be imported for Auto-Collect.
These invoices are kept up to date so any changes made within Xero are reflected on the matching Helcim invoice.
Payment will automatically be collected on the due date assigned on your Xero invoice.
Invoices voided in Xero will be marked as Canceled in Helcim and no payment will be collected.
Enabling Auto-Collect
NOTE
If you exit the wizard without hitting next, nothing will be auto-collected as the integration has not been completed at this stage!
Selecting Which Contacts to Include with Auto-Collect
Next you can choose how you want your contacts to have payment collected. Either automatically (through Auto-Collect) or manually by sending an email invoice with a Pay Now button.
To enroll customer in auto-collect:
Xero contacts must be enabled, either automatically during set up or manually from Helcim’s Customers section, for Auto-Collect to have their invoices collected on the due date.
‘Enable automatically for existing contacts’ means that all contacts imported to Helcim when connecting Helcim to your Xero account will have the Auto-Collect feature enabled. When this setting is used, all contacts with payment information stored in Helcim, will have their invoices collected on the due date
‘Enable automatically for future contacts’ means that when this setting is enabled, no existing contacts will have Auto-Collect enabled, but any new contacts added to Xero in the future will be immediately imported to Helcim and have the feature enabled
‘Enable manually’ means that when selected for existing or future contacts, no customers in Helcim will have Auto-Collect enabled and the merchant must enable the feature for each customer individually from Helcim’s customers section.
Syncing Xero contacts from Xero to Helcim
This means that Xero contacts will be imported to Helcim the moment the Auto-Collect feature is toggled on.
These contacts are then kept up to date via webhook.
Whenever a change is made to contact in Xero, it will be reflected in your Helcim account.
The Xero contact must have an email address stored so that Helcim can use this email to send requests for payment information.This will notify the contact via email.
Imported contacts: Anyone that you already have connected as a contact in Xero that also has due invoices will be included with Auto-Collect. If this is selected as Automatic, Xero will toggle ON Auto-Collect for all contacts in Xero.
Future contacts: Contacts going forwards who are not in your list currently can be set to automatically have Auto-Collect enabled, or manual. This will leave existing contacts as OFF for Auto-Collect.
Auto-Collect Settings
Invite link
Merchants can copy an invite link from the customer section. It’s important to remember that invite links are unique for each customer!
Each customer must be sent the link for their specific customer profile. If the link is shared with the wrong or with multiple customers, then the payment information provided will be added to the linked customer's profile.
These links can be added to a contract, email, invoice, etc. so you can craft the messaging you would like to accompany the payment information request.
We recommend using the link and embedding it into a crafted template. Automated emails cannot be customized.
Manual email
The ability to trigger an email from the customers section is available through selecting the email icon next to that customer.
These emails have a set template that can be viewed during the integration setup wizard.
Merchant Notification
Regardless of how you request payment information, whenever customers enter and save their information, you will receive email confirmation.
This allows you to manage which customers have provided their payment information as any auto-collect payments will fail if no payment info is available for the customer.
Auto-invite
This will send a payment information request to any contact that has the auto-collect feature enabled. If all your existing customers are automatically enabled, then all imported contacts will be emailed a link to provide their payment info.
To avoid sending a payment information request to all your existing contacts, leave auto-invite disabled and send the requests manually.
Choosing Automatic or Manual Payment Information Requests
Next, choose how you want to request payment information from your customers.
If you enable the Auto-Invite feature, then emails requesting payment information will be sent to the customer whenever that customer has Auto-Collect enabled.
If you leave Auto-Invite turned off, Helcim will not send payment information request emails, and you have the option to collect the payment information using two other methods
Copy a link (a payment request link)
Send an email from the customer list for each contact individually.
NOTE
If you select all imported contacts to have Auto-Collect enabled automatically and Auto-Invite is turned on, all your contacts will receive emails requesting their payment information. If this is not something you want, we recommend setting Auto-Collect to be enabled manually for all existing contacts for your first time setup.
Automatic - the system will automatically send emails to customers requesting their payment information. These emails are only sent to customers who do not already have payment information stored in Helcim.
Manual - You have the ability to go through the customer list and individually toggle on contacts for Auto-Collect.
** Recommended first time setup: We recommend following the manual method so that the payment information emails are not automatically sent to all of your customers for the first time. After completing the wizard, you can switch the settings to Auto going forwards for any new contacts.**
Completing the Wizard
The wizard to set up your integration (and start receiving auto collection amounts) will not be completed until you select Finish on the following screen:
Congratulations, you have completed the Xero integration wizard for setup! These checkmarks will update depending on your settings in the previous steps. Please make sure to hit ‘Finish’ to complete and return to your regular screen.
Important note:
If you have selected yes to include imported/existing contacts on the earlier screen, this will be when the payment information request emails are sent out to your contacts!
Summary
Afterwards, you will be taken to the Summary screen.
The settings viewed at this point will change depending on your choices made through the wizard.
You can select the invoice branding theme from here, and set the syncing for Auto-Collect as on or off. Turning this off will stop the payment request emails.
Errors and Troubleshooting
Integration errors
Errors may include issues with the connection between Helcim and Xero or the mapping of accounts between Helcim and Xero.
In all cases, an error message will be displayed on the integration interface in Helcim. If you are not seeing the required data in Xero, please login to Helcim, go to the Xero Integration, and check if any errors are displayed. Follow the direction provided by the error to resolve the issue.
Connection errors
There may be cases which require you to disconnect and reconnect the integration to resolve the issue.
For cases where you cannot resolve the issue or your integration is showing "No data" please select disconnect from your Helcim's account's Xero integration settings and then reconnect the integration. Your data in Xero will not be impacted.
If you are unable to disconnect the integration from your Helcim account, please do so from Xero by selecting the menu icon in the top right corner of your Xero account. Then select "Manage Connections" and disconnect Helcim.
Once disconnected, go back to your Helcim account to reconnect the integration.
Xero invoice not marked as Paid
When your customers pay a Xero invoice using Helcim, the invoice will be immediately updated as "paid" in your Xero account. You will also see the corresponding payment "reconciled" in your Helcim clearing account.
In rare instances, a communication error between Helcim and Xero may stop the payment in Helcim from being reflected in Xero. If this happens, your customer will see a message "payment could not be updated in Xero, please contact the merchant". The result of this error is a payment that was received by your Helcim account but not reflected in your Xero account. The Xero integration will reduce the likelihood of you experiencing a missing payment by automatically checking your Helcim account everyday at 8pm MST and importing any missing payments to your Xero account.
If you are confident that a customer paid an invoice but it is not visible in your Xero account, follow these steps:
Log in to your Helcim account and verify that there is an approved transaction for the associated invoice by looking at your transactions list in the Payment section.
Wait until 8pm MST and the payment will be automatically imported to Xero
If waiting for the automatic import is not an option, manually create a payment in your Helcim clearing account in Xero for the amount received and reconcile with the associated invoice.
Customer Facing Errors
When you customer is paying an invoice there are a few issues that they may run into:
Payment service is expired- Customer may encounter this error when a payment service is no longer connected. If a customer contacts you with this error, it means that the integration has been disconnected since the invoice was shared. Please reconnect and request that the customer attempt payment again on the original invoice.
Currency does not match with invoice currency - This error may appear if the currency of the invoice the customer is trying to pay, does not match the currency of your Helcim account. Your Helcim account can only process in the currency you have selected for your account.
The invoice is not due - This error will occur if the invoice has already been marked paid in Helcim.
Logs
In your Helcim account, you will find a log of all the actions taken between Helcim and Xero, including connections and payments. To view the report, follow the steps below:
1. "All Tools" menu and select Reporting
2. Xero API Logs
3. View logs