ecommpay web application for the Xero platform

General information

The ecommpay platform supports integration with the Xero cloud-based accounting platform. It is carried out using a separate web application from ecommpay, which allows information to be transferred between the two platforms. With this integration, you can do the following on the Xero platform:

The ecommpay platform supports integration with the Xero cloud-based accounting platform, which allows payment information to be transferred between the two platforms. With this integration, you can do the following on the Xero platform:

  • Perform financial reconciliation—with the help of customisable rules and automatic comparison of operation information stored on the ecommpay platform against that stored on the Xero platform.
  • Automatically generate credit notes—with all settlements being linked to the corresponding payments.
  • Accept payments via invoices—by means of generating links for making payments via Payment Page and forwarding them to customers, as well as tracking the status of such payments and recording the income generated by them.
Warning: Note that the ecommpay web application is considered to be a third-party application by the Xero platform, and connecting it may require you to disconnect one of your other connected applications in order to adhere to these limits.
Warning: Note that the ecommpay web application is considered to be a third-party application by the Xero platform (since it is not hosted on the Xero app store). Since at most two third-party applications are allowed to be used simultaneously on the Xero platform, connecting the ecommpay solution may require you to disconnect one of your other connected third-party applications. Prior to disconnecting any other application, check that doing so will not result in the loss of any critical information.

Setup

To ensure that information about payments processed via the ecommpay payment platform is sent to the Xero cloud platform automatically (for relevant projects) and that other capabilities are ready to be used, you should set up the ecommpay web application. To do so, proceed as follows:

To set up the ecommpay web application for the Xero platform, proceed as follows:

  1. Ensure that you have a Xero account for the Xero Developer portal and a Dashboard user account.

  2. Make sure that connecting a new application will not exceed Xero's limit on the number of concurrently connected third-party web applications, and disconnect one of them if required.

    Make sure that connecting the ecommpay solution will not exceed Xero's limit on the number of concurrently connected third-party web applications. If connecting the application will indeed exceed the limit, disconnect at least one other third-party application.

  3. Set up the web application.

    1. Use your Xero account to set up a connection with the web application by following the link https://xero-app.ecommpay.com.

      1. Use your Xero Developer portal account to open the Xero user interface.
      2. Open the following link: https://xero-app.ecommpay.com (in a separate tab).
      3. Click Login with Xero on the page that opens.
      4. Allow ecommpay access to the information about your Xero account and the organisations that require the ecommpay and Xero platforms to be connected.

        To do so, select the organisation you need from the drop-down list, click Allow access, and save changes by clicking Continue with organisations.

    2. Set up how the information is exchanged between the two platforms. To do so, specify the following required parameters on the connection parameter page: Environment, Secret, and Token.

      To do so, specify the required parameters on the connection parameter page:

      • Environment—the web application environment type (live refers to the live environment and sandbox refers to the test environment). Note that using the test environment requires you to set up a separate test project in the ecommpay platform.
      • Secret—a secret key associated with a specific Dashboard account. The token for that account is specified in the Token field located in the account profile in the Dashboard interface of the ecommpay platform (for more information, see this article).
      • Token—the token of the Dashboard account in the ecommpay platform. This token is used to interact with the Data API.
  4. Establish a connection by clicking Continue.

  5. Make sure that the connection has been established.

    If a connection has been established, a page containing the ecommpay web application properties opens in the Xero interface. By default, the Settings tab is displayed. If a connection has not been established, an error message is displayed in the Xero interface (for a list of error codes, see this page).

    If a connection has not been established, an error message is displayed in the Xero interface (for a list of error codes, see this page). For example, the 401 Authorization Required error means that access was denied. This can be caused by specifying either an incorrect token or secret key. If this is the case, rectify the incorrect parameters and try to establish a connection again.

Configuration

To begin using the web application, you need to link the ecommpay platform and the Xero platform as follows:

  1. Select a synchronisation type by turning on the I want to synchronize settlements with XERO toggle and selecting the appropriate synchronisation type.

    This is done by turning on the I want to synchronize settlements with XERO toggle and selecting the appropriate synchronisation type from the Synchronization interval drop-down list:

    • Live sync—information about each operation is sent upon completion thereof (note that for this synchronisation type, the information may take up to ten minutes to be displayed in the Xero interface).
    • Daily, Weekly, Monthly—information about all relevant operations is sent at the end of the specified time period according to the following timeframes:
      • Daily—starting at 01:00 AM UTC every day, containing information from the previous day;
      • Weekly—starting at 02:00 AM UTC every Monday, containing information from the previous week;
      • Monthly—starting at 03:00 AM UTC on the 1st of every month, containing information from the previous month.
      When synchronisation occurs according to the timeframes above, the first batch of operations will contain only those operations that have been assigned the Success final status from the moment the configuration changes are implemented (and recorded in the ecommpay platform) until the end of the specified time period. All subsequent batches that are sent will contain all relevant operations that fit the entirety of the specified time period. The first batch of operations is sent once the first time period has ended (even if the full length of this time period has not passed).

  2. Set up both bank and clearing accounts in each currency used for payment processing via the ecommpay platform and set up a fallback clearing account (details).

    To set up bank and clearing accounts in a specific currency, select the relevant values from the corresponding drop-down lists Currency, Settle to Bank Account, and XERO Clearing Account. as follows:

    • Currency—the currency code (note that each currency can only be used once; a list of currency codes can be found here).
    • Settle to Bank Account—the name of the merchant's Xero account associated with the merchant's bank account in the selected currency.

    • XERO Clearing Account—the name of the merchant's Xero clearing account for operations processed via the ecommpay platform in the selected currency.

    To set up a suspense account, select the account you need in the Fallback clearing account drop-down list.

  3. If required, you can filter operations by projects in the Enter the project_id, press Enter, and save the changes below field.

    To set up a filter for a specific project, fill in its identifier in the Enter the project_id, press Enter, and save the changes below field and press the Enter key. If you need to specify several identifiers, repeat this step for each one. Identifiers that have been specified correctly will appear as separate filtering values above this field.

  4. If required, set up the option to perform payments via links generated by Xero Invoices (details).

  5. Save the changes by clicking Save changes.

  6. Make sure that your changes have been applied. To do so, go to the Monitoring tab in the ecommpay web application for the Xero platform and check that records have appeared.

    To do so, go to the Monitoring tab in the ecommpay web application for the Xero platform and check that records have appeared. This will mean that the synchronisation has been completed. Each such record includes information about the date and time of the synchronisation, its status (Success or Failed), and the number of operations that were synchronised. If the synchronisation fails, you can find the cause of the failure in the relevant report. If no operations were synchronised, no data is displayed in the report.

To illustrate, these are the steps of this procedure in the ecommpay web application.

Figure 1. Selecting the synchronisation type
Figure 2. Setting up Xero accounts
Figure 3. Monitoring changes

Setting up and using Xero accounts

Overview

To use the integration between the ecommpay and Xero platforms to its full advantage, including the Xero Invoice service for processing payments, set up the following internal accounts in Xero to ensure correct synchronisation of operation data and efficient utilisation of financial reconciliation capabilities.

  • Clearing account is a temporary holding account in Xero used for recording and processing operations received from the payment providers you work with.

    When configuring the application from ecommpay, you are recommended to set up a separate clearing account in each currency of operations processed via ecommpay. Note that only clearing accounts with the Enable payments to this account option enabled can be used for this purpose.

  • Fallback clearing account is a suspense account in Xero used for recording and processing operations processed via ecommpay in currencies that do not yet have configured clearing accounts.

    When configuring the application from ecommpay, you are recommended to set up a suspense account right away to prevent the loss of information about these operations in the process of operation data synchronisation between ecommpay and Xero.

  • Bank account is an account in Xero associated with a merchant's actual bank account and used for reconciling operation data received from bank statements and from ecommpay.

To make sure the application from ecommpay works properly, in the Xero interface configure as many accounts of each type as necessary to categorise your operation data correctly. Keep in mind that the appearance of the Xero interface may differ from the illustrations provided in this article.

When synchronising and reconciling data, the application first sends operation data from ecommpay to Xero, allocating each operation to the appropriate Xero clearing account in the relevant currency, or to the suspense account if no suitable clearing account is found. Then, the application automatically creates records of these operations in the bank accounts in Xero (also in relevant currencies) for subsequent financial reconciliation.

In the application from ecommpay for Xero, the accounts described above are set up in the Settings tab.

Working with clearing accounts

Adding an account

To add a clearing account:

  1. Open the Chart of accounts section that lists all accounts of the organisation you have selected out of your Xero organisations.

    To do so, click the Accounting item in the upper menu, then select Chart of accounts in the menu that opens, or open the https://go.xero.com/GeneralLedger/ChartOfAccounts.aspx link.

  2. Open the window for adding a new account by clicking Add account.
  3. Specify the appropriate parameters and enable the Enable payments to this account switch to use the account for clearing.

    As a rule, the following fields are required:

    • Account Type—the type of the account (depending on the purpose of the payments; for example, you can choose the Current Asset account type for synchronising payment data between ecommpay and Xero).
    • Code—the identifier of the account unique within the selected organisation (up to 10 characters long; assigned by the merchant).
    • Name—the name of the account (up to 150 characters long; assigned by the merchant).
  4. Save changes by clicking Save at the bottom of the window for adding a new account.
  5. Make sure that the clearing account has been added.

    A confirmation notification should appear above the organisation's list of accounts in the All accounts tab, and the new account should be shown in the list.

Looking up which account an operation is posted to

To review which Xero clearing account an invoice generated in Xero (paid with the use of ecommpay as a payment service) is posted to:

  1. Navigate to the invoice management page in Xero by selecting Business > Invoices in the top menu.

    To do so, in the Business drop-down menu on the Xero toolbar, select Invoices.

  2. Open the card of the specific invoice.

    To do so, click the row of the invoice you need in the list of invoices.

  3. Open the invoice details.

    To do so, click the link that contains the date when the payment was completed, for example, Payment (17 May 2025) in the bottom right corner of the panel.

  4. Review the accuracy of the posting.

    To do so, in the opened browser tab, locate the name of the clearing account in the breadcrumb trail. It should be one of the accounts specified at the step of configuration of the application from ecommpay, and the currency of the operation should be the same as the currency of the clearing account.

In the Xero interface, this procedure may look as follows.

Figure 4. Opening the Invoices page
Figure 5. Opening the invoice card
Figure 6. Reviewing information about the account

Working with bank accounts

Adding an account

To add information about the bank account to the Xero platform:

  1. Open the Bank accounts section that lists bank accounts of the organisation you have selected out of your Xero organisations.

    To do so, click the Accounting item in the upper menu, then select the Bank accounts in the menu that opens, or open the https://go.xero.com/Bank/BankAccounts.aspx link.

  2. Open the window for adding a new bank account by clicking Add Bank Account.
  3. Specify the appropriate parameters according to the instructions in the Xero interface and save changes.
  4. Make sure that the bank account has been added.

    The card of the new bank account should be shown in the Bank accounts section.

Using bank accounts in reconciliation

To view operation data from ecommpay in Xero and reconcile it with operation data received from banks:

  1. Open the Bank accounts section that lists bank accounts of your Xero organisation.

    To do so, click the Accounting item in the upper menu, then select Bank accounts in the menu that opens or open the https://go.xero.com/Bank/BankAccounts.aspx link.

  2. Open the card of the specific bank account that is associated with payments performed via the ecommpay platform.

    To do so, click the row with the name of the bank account in the list of accounts.

  3. If needed, check the list of operations that are posted to this bank account.

    To do so, in the opened card, navigate to the Account Transactions tab.

  4. If needed, reconcile operations in the Xero interface by comparing the information received from banks and from ecommpay.

    To do so, follow the steps below:

    1. In the opened card of the bank account, navigate to the Reconcile tab.
    2. If needed, import bank statements via a CSV report.
    3. Check data of each operation according to recommendations on the Xero's website and confirm correct operations by clicking OK.

      The information received from the bank is displayed on the left side of the tab, and the information received from ecommpay is displayed on the right.

  5. Make sure that information about operations is correct.

Working with invoices

Setting up Xero Invoices

To set up the option of performing payments via links generated by Xero Invoices (with the use of Payment Page from ecommpay to complete payments), follow the steps below:

  1. Generate the link for adding ecommpay as a payment service in the ecommpay web application.

    To do so,

    1. Navigate to the Settings tab of the web application.
    2. Enable the I want to offer ecommpay as a payment service on XERO invoices toggle.
    3. Fill in the project identifier and its secret key in the Project ID and Project Secret fields.
    4. Save by clicking Save changes.
    5. Copy the link provided in the ecommpay payment service URL field by clicking Copy to the right of the field.
  2. Add ecommpay as a new payment service to Xero.

    To do so,

    1. Open the Xero interface using your Xero Developer account.
    2. Navigate to the section with the organisation settings by clicking its name in the top left corner of the interface and selecting Settings in the menu that opens.
    3. Navigate to the subsection with settings to manage payment options by clicking Payment services in the Features column.
    4. Navigate to the Add new payment service tab and click the link under the tiles with available payment services (If you're wanting a payment service that isn't listed, add another payment option).
    5. In the window that opens, enable the Custom Payment URL switch and click Continue to open the window for specifying the new payment service.
    6. In the window that opens, specify the information about the service in the following fields: Account name, Your custom URL, and Pay now button text the name of the service (ecommpay) in the Account name field, the link copied from the ecommpay payment service URL field of the web application—in the Your custom URL field, and the text for the pay button (if needed)—in the Pay now button text field, following which, click Save to apply changes.

      Once the service is added, there will be a notification in the bottom left corner of the interface and the service will appear in the table on the Manage connected services tab.

    7. If necessary, customise the theme of the email with the invoice for the ecommpay payment service on the Manage connected services tab.

      To do so, navigate to the Manage connected services tab, click Manage themes, find in the table that opens the row with the theme you need, select ecommpay in the Credit card column, and click Save to apply changes.

      There will be a notification that the selected theme has been applied in the bottom left corner of the interface.

  3. Make sure that the ecommpay payment service is ready to process purchases using invoices generated in Xero. To do so, go to the Manage payment methods tab and check that it is listed in the group of connected payment services.

    To do so, go to the Manage payment methods tab and check that ecommpay is listed among the Connected payment apps and enabled (it should be assigned the On status, shown to the right of the name of the service).

To illustrate, these are the steps of this procedure in the ecommpay web application and the Xero interface.

Figure 7. Generating the URL
Figure 8. Adding the payment service
Figure 9. Ensuring the service is connected

Generating payment links

Once the Xero Invoices service is set up (details), the Xero platform allows you to generate invoices that can be sent to customers via email and then settled via the included links that invoke Payment Page from ecommpay. Keep in mind that these links are not identical to payment links generated in the ecommpay platform and correspond to ecommpay's regular one-time payments via Payment Page instead (for more information about this payment type, see this article).

To process a one-time purchase using a Xero invoice, follow the steps below:

  1. Navigate to the invoice management page in Xero by selecting Business > Invoices in the top menu.

    To do so, in the Business drop-down menu on the Xero toolbar, select Invoices.

  2. Navigate to the page where invoices can be generated by clicking New Invoice on the Invoices toolbar.

  3. Specify the appropriate parameters and generate the invoice.Specify the appropriate parameters, generate the invoice, and click Approve & email in order to navigate to the page where you can review and send the invoice to the customer.

    To do so, fill in the necessary fields and click Approve & email in order to navigate to the page where you can review and send the invoice to the customer. You can also save your changes without sending the invoice (for instance, if more details are needed) by clicking Save & close.

    The following fields are required: To, Issue date, Due date, Invoice number, Online payments, Currency, Item, Qty., and Price.

    1. To—the name of the customer to whom the invoice will be sent for payment.
    2. Issue date and Due date—the issue date for the invoice and the date on which the invoice payment link stops being valid, respectively. The due date cannot be later than 30 days from the issue date.
    3. Invoice number—the payment identifier which should correspond one-to-one to the appropriate payment identifier unique within the project in the ecommpay platform. This identifier is prefilled, but it can be corrected manually.
    4. Online payments—the payment service (or provider) for processing the payment (should be set to ecommpay).
    5. Currency—the name of the currency of the payment. All amounts on the invoice will be specified in this currency.
    6. Item—the name of the goods or services provided.
    7. Qty.—the quantity of the goods or services provided.
    8. Price—the price of a single unit.

  4. Send the invoice to the customer by clicking Send email.

    You can also modify the contents of the email before sending the invoice to the customer. Proofread the email, revise if necessary, and click Send email.

  5. Make sure that the one-time payment has been completed.

    The status of a one-time payment can be viewed in Xero on the Invoices page (here completed payments will be assigned the paid status) and in the Payments section of Dashboard (here completed payments will be assigned the success status). A full list of all possible statuses for one-time purchases processed in the ecommpay platform can be viewed in this article.

To illustrate, these are the steps of this procedure in the Xero interface.

Figure 10. Opening the Invoices page
Figure 11. Navigating to generate a new invoice
Figure 12. Specifying the invoice parameters
Figure 13. Sending the link to the customer