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.

Setup

To ensure that information about payments processed via the ecommpay payment platform is sent to the Xero cloud platform automatically (for relevant projects), 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. Contact the ecommpay technical support specialists and work out a timeframe for implementing this feature. Additionally, ensure that you have a Xero account for the Xero Developer portal.
2. Wait for confirmation from the ecommpay specialists that the web application is ready to be installed.

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

4. 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.
      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.
   
5. Establish a connection by clicking Continue.

6. 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. If required, you can filter operations by currency and projects.

   To set up a currency filter, select the relevant criteria from the corresponding drop-down lists Currency, Settle to Bank Account, and XERO Clearing Account. as follows:

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

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

   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.

   

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

4. Save the changes by clicking Save changes.

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

Setting up Xero Invoices

To set up the option of performing payments via links generated by Xero Invoices, 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.

Generating payment links

The Xero platform allows you to generate invoices that can be sent to customers via email and then be settled via the included links. 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).

Processing purchases using invoices generated in Xero requires both the ecommpay and Xero platforms to be configured accordingly (details) with the invoices capability properly set up (details).

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 with the appropriate payment 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 each single item.
   

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.