Integration

Setting up the application

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 and granting ecommpay access to the information about your Xero account and the organisations that require the ecommpay and Xero platforms to be connected.

      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 the exchange of information between the two platforms. To do so, specify the following required parameters: Environment, Secret, and Token.

      To do so, specify the following required information on the page with connection settings:

      • 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.

Configuring the connection

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

  1. Open the application from ecommpay and go to the Settings tab.

  2. Select a synchronisation type by turning on the I want to synchronize settlements with XERO toggle and selecting the appropriate synchronisation type—event-based (Live sync) or interval-based (Daily, Weekly, Monthly).

    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).

  3. Set up bank and clearing accounts in each currency used for payment processing via the ecommpay platform and a suspense account (details).

    To set up an account 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.

  4. 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.

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

  6. Save the changes by clicking Save changes.

  7. 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:

    1. You can look up (for example, via the Dashboard interface of the ecommpay payment platform) if there was at least one completed financial operation between the moment the configuration changes were implemented and the end of the specified time period (or by the current moment if the real-time synchronisation had been set up).
    2. You can check that the records about performed synchronisation have appeared in the ecommpay web application for the Xero platform on the Monitoring tab. Each 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 a synchronisation attempt fails, you can find the cause of the failure in the relevant report. If no operations were synchronised, there will be no records about performed synchronisation shown.

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 synchronisation attempts

Invoice setup

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 in order to add and configure relevant payment services for sending payment requests between the Xero and ecommpay platforms. Note that to process a one-time invoice payment, you only need to add the ecommpay payment service, while for processing recurring invoice payments with the use of Direct Debit BACS and Direct Debit SEPA, you need to add payment services for these methods (in addition to the ecommpay payment service) as well.

  1. Generate links for adding relevant payment services in the ecommpay web application (for each relevant project in the ecommpay platform.

    To do so,

    1. Navigate to the Settings tab of the web application.
    2. Enable either or both toggles:
      • I want to offer ecommpay as a payment service on XERO invoices
      • I want to offer ecommpay Direct Debit (SEPA and BACS) as payment services provider on Xero invoices
    3. Fill in the project identifier and its secret key in the Project ID and Project Secret fields.
    4. Save by clicking Save changes.
  2. Navigate to the page with payment services settings in Xero.

    To do so (you have to repeat these steps for each service) :

    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.
  3. Add and configure each payment service that you need in Xero.

    To do so,

    1. Copy the link provided in the ecommpay payment service URL field by clicking Copy to the right of the field.
    2. 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).
    3. In the window that opens, enable the Custom Payment URL switch and click Continue to open the window for specifying the new payment service.
    4. 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.
      1. Account name—the name of the service (for example, ecommpay or ecommpay BACS).
      2. Your custom URL—the link copied from the ecommpay payment service URL field of the web application.
      3. Pay now button text— the text for the pay button in the Xero interface that will allow confirming the payment and checking its status.
        Notice: For repeating invoices, the Pay now button can be used both for confirming initial payments to register recurring payments and for checking statuses of recurring payments (more information on these scenarios can be found in the article about working with invoices ). Therefore, it is recommended that for Direct Debit payment methods you use the text that clearly identifies the payment method involved and prevents cases of misunderstanding, for example, Processing with ….
    5. Confirm adding a payment service by clicking Save to apply changes.
    6. Make sure that the service has been added (to the Xero platform).

      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.

  4. Make sure that the added payment services are ready to process purchases using invoices generated in Xero. To do so, go to the Manage payment methods tab and check that they are listed in the group of connected payment services.

    To do so, go to the Manage payment methods tab and check that these payment services are listed among the Connected payment apps and enabled (i.e. assigned the On status).

In addition, for the Direct Debit methods you can create a test invoice and follow the generated link. If the payment services have been added and configured properly, then once you click the link, the ecommpay payment form will open to complete the payment. If not, the page of the ecommpay web application will open with the Payment method not enabled notification.

Figure 4. Payment methods set up correctly
Figure 5. Payment method unavailable notification

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

Figure 6. Generating the URL
Figure 7. Adding the payment service
Figure 8. Checking if the service is connected