Веб-приложение от ecommpay для интеграции с платформой Xero

Общая информация

При работе с платформой ecommpay поддерживается возможность интеграции с облачной платформой бухгалтерского и финансового учёта Xero. Для этого предусмотрено отдельное веб-приложение от ecommpay, обеспечивающее автоматический обмен информацией между платформами. В результате интеграции с платформой Xero в её интерфейсе становятся доступными следующие возможности:

При работе с платформой ecommpay поддерживается возможность настроить автоматический обмен информации о платежах с платформой бухгалтерского учёта Xero. В результате в интерфейсе Xero становятся доступными следующие возможности:

  • Финансовые сверки — с возможностями настраивать правила сверок и автоматически сопоставлять информацию об операциях из платформы ecommpay с информацией в платформе Xero.
  • Автоматическое формирование возвратных чеков (credit notes) — с автоматическим сопоставлением выполняемых возвратов с оплатами, к которым эти возвраты относятся.
  • Проведение оплат по платёжным ссылкам — с формированием и отправкой пользователям ссылок на оплаты через платёжную форму Payment Page и с отображением статусов и финансовых результатов этих оплат.
Внимание: Стоит учитывать, что веб-приложение от ecommpay является сторонним для платформы Xero и для его подключения может потребоваться отключить одно из других сторонних приложений — в соответствии с ограничениями Xero.
Внимание: Стоит учитывать, что веб-приложение от ecommpay является сторонним для платформы Xero (так как оно не размещено в официальном магазине веб-приложений Xero). Поскольку в этой платформе допускается работать не более чем с двумя сторонними веб-приложениями одновременно, для подключения решения от ecommpay может потребоваться отключить одно из других сторонних приложений. Перед отключением любого из приложений желательно убедиться, что это не приведёт к потере критически значимой информации.

Подключение

Чтобы обеспечить автоматическую передачу в облачную платформу Xero информации о платежах, проводимых через платформу ecommpay (по актуальным проектам), и доступность других поддерживаемых возможностей, необходимо обеспечить взаимодействие с веб-приложением от ecommpay. Для этого следует:

Чтобы обеспечить работу с веб-приложением от ecommpay для платформы Xero, следует:

  1. Обеспечить наличие учётной записи портала Xero Developer и учётной записи интерфейса Dashboard для мерчантов ecommpay.

  2. Убедиться, что при подключении не будет превышено ограничение Xero на количество одновременно используемых сторонних веб-приложений, и при необходимости отключить одно из других приложений.

    Убедиться, что при подключении приложения от ecommpay не будет превышено ограничение платформы Xero на количество одновременно используемых сторонних веб-приложений. Если это ограничение может быть превышено, отключить, как минимум, одно из других сторонних приложений.

  3. Подключить веб-приложение.
    1. Инициировать подключение веб-приложения под учётной записью Xero, перейдя по ссылке https://xero-app.ecommpay.com.
      1. Открыть интерфейс Xero с использованием учётной записи портала Xero Developer.
      2. Открыть страницу https://xero-app.ecommpay.com (в отдельной вкладке браузера).
      3. Щёлкнуть кнопку Login with Xero на открывшейся странице.
      4. Предоставить ecommpay доступ к информации об учётной записи Xero и целевых организациях, для которых требуется обмен информацией между платформами ecommpay и Xero.

        Для этого необходимо выбрать в выпадающем списке выбрать целевую организацию, предоставить доступ к информации о ней, щёлкнув Allow access, и сохранить изменения, щёлкнув Continue with organisations.

    2. Настроить обмен данными между платформами ecommpay и Xero, указав параметры соединения: Environment, Secret и Token.

      Для этого следует указать на странице с параметрами соединения необходимые сведения:

      • Environment — режим работы веб-приложения: рабочий (live) или тестовый (sandbox). Стоит учитывать, что для работы в тестовом режиме должен быть настроен отдельный тестовый проект в платформе ecommpay.
      • Secret — секретный ключ, полученный от ecommpay и ассоциированный с учётной записью Dashboard, токен которой указывается в поле Token в профиле учётной записи интерфейса Dashboard платёжной платформы ecommpay (подробнее).

      • Token — токен учётной записи Dashboard в платформе ecommpay, используемый для работы с Data API.

  4. Установить соединение, щёлкнув кнопку Continue.

  5. Убедиться, что подключение установлено.

    Если подключение выполнено, в интерфейсе Xero открывается страница со свойствами веб-приложения от ecommpay (с активной вкладкой Settings). Если подключение не выполнено, в интерфейсе Xero отображается сообщение об ошибке (список возможных ошибок представлен на отдельной странице).

    Если подключение не выполнено, в интерфейсе Xero отображается сообщение об ошибке (список возможных ошибок представлен на отдельной странице). Например, ошибка 401 Authorization Required свидетельствует об отказе в доступе, связанном с указанием некорректного токена или секретного ключа. В таком случае необходимо указать корректные данные и попробовать установить подключение повторно.

Общий порядок настройки

Чтобы начать работу с веб-приложением, необходимо настроить взаимодействие между платформами ecommpay и Xero. Для этого следует:

  1. Выбрать способ синхронизации, включив переключатель I want to synchronize settlements with XERO и выбрав целевой способ синхронизации.

    Для этого необходимо включить переключатель I want to synchronize settlements with XERO и выбрать в выпадающем списке Synchronization interval целевой способ синхронизации:

    • По событиям (Live sync) — с передачей сведений о каждой операции непосредственно после её выполнения (при этом в интерфейсе Xero такие сведения могут отображаться с задержкой до 10 минут).
    • По периодам (Daily, Weekly, Monthly) — с передачей сведений о всех релевантных операциях по итогам заданного календарного периода с использованием следующего базового расписания:
      • Daily — начиная с 01:00 UTC каждый день по итогам предыдущего дня,
      • Weekly — начиная с 02:00 UTC каждый понедельник по итогам предыдущей недели,
      • Monthly — начиная с 03:00 UTC каждое 1-е число календарного месяца по итогам предыдущего месяца.

      При синхронизации таким способом в первую группу релевантных операций попадают только те, которым в платформе присваивается итоговый статус Success с момента сохранения вносимых изменений (и регистрации этих сведений в платформе ecommpay) и до конца заданного календарного периода, в то время как последующие группы охватывают полные периоды. Информация о первой группе таких операций отправляется по завершении первого периода (даже если он неполный).

  2. Настроить банковские и расчётные счета (для каждой из используемых валют, в которых выполняются операции через платформу ecommpay) и резервный расчётный счёт (подробнее).

    Для задания счетов в конкретной валюте необходимо выбрать соответствующие значения в выпадающих списках Currency, Settle to Bank Account и XERO Clearing Account.:

    • Currency — код валюты (при этом одна валюта может использоваться только один раз; справочник валют представлен в отдельной статье).
    • Settle to Bank Account — название внутреннего счёта в Xero с реквизитами банковского счёта мерчанта (для расчётов в выбранной валюте).

    • XERO Clearing Account — название внутреннего промежуточного счёта мерчанта в платформе Xero, используемого для клиринга операций, которые были выполнены через платформу ecommpay (в выбранной валюте).

    Для задания резервного расчётного счёта необходимо выбрать в выпадающем списке Fallback clearing account один из промежуточных счетов в качестве резервного.

  3. При необходимости, задать условия фильтрации операций по проектам в поле Enter the project_id, press Enter, and save the changes below.

    Для задания отдельного условия фильтрации по конкретному проекту необходимо указать его идентификатор в поле Enter the project_id, press Enter, and save the changes below и нажать клавишу Enter. При необходимости указать более одного идентификатора, такую процедуру следует повторить для каждого из них — корректно переданные значения должны отображаться отдельными условиями над этим полем.

  4. При необходимости, настроить возможность проведения оплат по ссылкам из интерфейса Xero (подробнее).
  5. Сохранить изменения, щёлкнув кнопку Save changes.

  6. Убедиться, что изменения применены, перейдя на вкладку Monitoring в веб-приложении от ecommpay для платформы Xero и дождавшись появления записей о выполненной синхронизации.

    Для этого следует перейти на вкладку Monitoring в веб-приложении от ecommpay для платформы Xero и дождаться появления записей о выполненной синхронизации. Каждая такая запись включает в себя информацию о дате и времени синхронизации, её статусе (Success или Failed) и количестве операций, по которым были переданы сведения в платформу Xero. В случаях с ошибками синхронизации в отчётах могут указываться причины таких ошибок. В случаях, когда количество операций равно нулю, записи о синхронизации не отображаются.

В интерфейсе приложения ecommpay эта процедура может выглядеть следующим образом.

Рис. 1. Выбор способа синхронизации
Рис. 2. Настройка счетов
Рис. 3. Контроль изменений

Настройка и использование счетов Xero

Общая информация

Для использования интеграции между платформами ecommpay и Xero, включая сценарии проведения оплат по ссылкам через приложение ecommpay для Xero, необходимо настроить работу с внутренними счетами в Xero — таким образом, чтобы обеспечивать корректную синхронизацию данных об операциях и улучшать возможности финансовых сверок.

  • Промежуточный счёт (clearing account) — внутренний расчётный счёт мерчанта в платформе Xero. Такой счёт используется для учёта (клиринга) операций, данные о которых передаются из платформы ecommpay, в одной валюте.

    При настройке приложения рекомендуется настроить отдельный промежуточный счёт для каждой из используемых валют, в которых выполняются операции через платформу ecommpay. Стоит учитывать, что для этого доступны только те промежуточные счета, в свойствах которых активирована возможность выполнять расчёты (Enable payments to this account).

  • Резервный промежуточный счёт (fallback clearing account) — внутренний расчётный счёт мерчанта в платформе Xero. Этот счёт используется в случаях, когда при синхронизации данных между платформами ecommpay и Xero выявляются операции в валютах, для которых ещё не настроены промежуточные счета. Чтобы информация о таких операциях не утратилась, они соотносятся с резервным счётом. Рекомендуется указывать этот счёт при начальной настройке приложения от ecommpay.
  • Банковский счёт (bank account) — внутренний счёт в Xero с реквизитами банковского счёта мерчанта. Этот счёт используется для финансовых сверок информации по операциям, полученной из платформы ecommpay, с информацией из банковских выписок.

Для обеспечения корректной работы приложения от ecommpay необходимо настроить актуальное количество счетов каждого из этих типов в интерфейсе Xero. При этом стоит учитывать, что реализация интерфейса для работы со счетами обеспечивается на стороне платформы Xero и может отличаться от описанной в рамках этой статьи.

В процессе синхронизации и сверки финансовой информации сначала с помощью приложения выполняется синхронизация между платформами ecommpay и Xero, с передачей сведений о выполненных операциях и с соотнесением этих операций с промежуточными счетами Xero в соответствующих валютах. Затем на внутренних банковских счетах Xero (также в валютах операций) автоматически создаются записи, соответствующие переданным операциям, — для последующей финансовой сверки.

В приложении от ecommpay для Xero перечисленные счета задаются на вкладке Settings.

Работа с промежуточными счетами

Добавление счёта

Чтобы добавить промежуточный счёт, необходимо:

  1. Открыть в интерфейсе Xero раздел Chart of accounts со счетами организации.

    Для этого необходимо щёлкнуть пункт Accounting в верхнем меню и выбрать в открывшемся контекстном меню раздел Chart of accounts либо перейти по адресу https://go.xero.com/GeneralLedger/ChartOfAccounts.aspx.

  2. Открыть окно добавления счёта, щёлкнув кнопку Add account.
  3. Задать параметры счёта и активировать возможность выполнять расчёты через этот счёт, установив флажок Enable payments to this account.

    Как правило, к числу обязательных параметров для заполнения относятся следующие:

    • Account Type — тип счёта (в соответствии с назначением платежей; например, Current Asset для обмена данными между платформами ecommpay и Xero).
    • Code — идентификатор счёта, уникальный в рамках целевой организации мерчанта в платформе Xero (длиной до 10 символов; присваивается на стороне мерчанта).
    • Name — название счёта (длиной до 150 символов; присваивается на стороне мерчанта).
  4. Сохранить изменения, щёлкнув кнопку Save, расположенную в нижней части окна добавления счёта.
  5. Убедиться, что счёт добавлен.

    О добавлении счёта свидетельствуют соответствующее уведомление над реестром счетов организации на вкладке All accounts и отображение добавленного счёта в этом реестре.

Сопоставление операции со счётом

Чтобы узнать, с каким промежуточным расчётным счётом Xero соотнесён платёж по выставленному в интерфейсе Xero счёту на оплату (с использованием ecommpay в качестве платёжного сервиса), необходимо:

  1. Открыть страницу для работы с платёжными ссылками в интерфейсе Xero, выбрав в верхнем меню пункт Business > Invoices.

    Для этого необходимо перейти в интерфейс Xero, раскрыть в верхнем меню пункт Business и выбрать в нём пункт Invoices.

  2. Открыть карточку целевого счёта на оплату.

    Для этого следует щёлкнуть соответствующую строку в реестре выставленных счетов.

  3. Открыть детальную информацию о проведённом платеже в рамках целевого счёта на оплату.

    Для этого следует щёлкнуть на панели с итоговыми суммами ссылку с датой проведения платежа (например, Payment (17 May 2025)).

  4. Проверить искомую информацию.

    Для этого в открывшейся вкладке браузера необходимо найти в навигационной цепочке название промежуточного счёта, с которым сопоставлена проведённая оплата. Это должен быть один из тех счетов, которые были указаны при настройке взаимодействия платформ ecommpay и Xero (в соответствующей валюте).

В интерфейсе Xero эта процедура может выглядеть следующим образом.

Рис. 4. Открытие страницы Invoices
Рис. 5. Открытие карточки выставленного счёта
Рис. 6. Проверка названия счёта

Работа с банковскими счетами

Регистрация счёта

Чтобы добавить информацию о банковском счёте мерчанта в платформу Xero, необходимо:

  1. Открыть в интерфейсе Xero раздел Bank accounts с карточками банковских счетов организации мерчанта.

    Для этого необходимо щёлкнуть пункт Accounting в верхнем меню и выбрать в открывшемся контекстном меню раздел Bank accounts либо перейти по адресу https://go.xero.com/Bank/BankAccounts.aspx.

  2. Открыть окно регистрации счёта, щёлкнув кнопку Add Bank Account.
  3. Задать параметры счёта, следуя инструкциям интерфейса, и сохранить изменения.
  4. Убедиться, что счёт зарегистрирован.

    О регистрации счёта свидетельствует отображение карточки этого счёта в разделе Bank accounts.

Использование банковских счетов в сверках

Чтобы просмотреть в интерфейсе Xero информацию об операциях, полученную из платформы ecommpay, и сверить эту информацию с информацией, полученной от банков, необходимо:

  1. Открыть в интерфейсе Xero раздел Bank accounts с банковскими счетами организации мерчанта.

    Для этого необходимо щёлкнуть пункт Accounting в верхнем меню и выбрать в открывшемся контекстном меню раздел Bank accounts либо перейти по адресу https://go.xero.com/Bank/BankAccounts.aspx.

  2. Открыть карточку целевого банковского счёта — того, с которым соотносятся операции, выполненные через платформу ecommpay, в необходимой валюте.

    Для этого следует щёлкнуть ссылку с названием этого счёта.

  3. При необходимости, просмотреть список операций по этому банковскому счёту.

    Для этого следует перейти в открывшейся карточке счёта на вкладку Account Transactions.

  4. При необходимости, выполнить сверку операций, сопоставляя в интерфейсе Xero информацию об этих операциях, полученную от банков и от ecommpay.

    Для этого следует:

    1. Перейти в открывшейся карточке счёта на вкладку Reconcile.
    2. При необходимости, загрузить банковские выписки (через отчёт в формате CSV).
    3. Сопоставить информацию по каждой операции, следуя рекомендациям Xero, и отметить корректные операции с помощью кнопки OK.

      Информация от банка отображается в левой части вкладки, а от ecommpay — в правой.

  5. Убедиться, что информация об операциях корректна.

Работа с оплатами по ссылкам

Настройка возможности проведения оплат по ссылкам

Чтобы настроить возможность проведения оплат по ссылкам из интерфейса Xero с использованием сервиса Xero Invoices и платёжной формы Payment Page от ecommpay, необходимо:

  1. Сформировать в веб-приложении от ecommpay ссылку для использования ecommpay в качестве платёжного сервиса.

    Для этого необходимо:

    1. Открыть веб-приложение и перейти на вкладку Settings.
    2. Включить переключатель I want to offer ecommpay as a payment service on XERO invoices.
    3. Указать идентификатор и ключ рабочего проекта в полях Project ID и Project Secret.
    4. Сохранить изменения, щёлкнув кнопку Save changes.
    5. Скопировать ссылку из поля ecommpay payment service URL с помощью кнопки Copy.
  2. Добавить в интерфейсе Xero платёжный сервис ecommpay.

    Для этого необходимо:

    1. Открыть интерфейс Xero с использованием учётной записи портала Xero Developer.
    2. Открыть раздел со свойствами целевой организации, щёлкнув в левом верхнем углу интерфейса её название и выбрав в открывшемся контекстном меню раздел Settings.
    3. Открыть подраздел со свойствами для управления платёжными сервисами, щёлкнув в группе Features свойство Payment services.
    4. Открыть окно добавления платёжного сервиса, перейдя на вкладку Add new payment service и щёлкнув под панелями с доступными платёжными сервисами ссылку для добавления сервиса, не представленного в списке (If you're wanting a payment service that isn't listed, add another payment option).
    5. Открыть окно для указания платёжного сервиса, активировав в открывшемся окне переключатель Custom Payment URL и щёлкнув кнопку Continue.
    6. Указать в открывшемся окне информацию о сервисе в полях Account name, Your custom URL и Pay now button text название сервиса (ecommpay) в поле Account name, скопированную ссылку из поля ecommpay payment service URL веб-приложения — в поле Your custom URL, текст для кнопки оплаты (при необходимости) — в поле Pay now button text, после чего сохранить изменения, щёлкнув кнопку Save.

      О добавлении сервиса свидетельствует соответствующее уведомление в левом нижнем углу интерфейса и отображение добавленного сервиса в таблице на вкладке Manage connected services.

    7. При необходимости, задать тему оформления писем со ссылками на оплаты для платёжного сервиса ecommpay на вкладке Manage connected services.

      Для этого необходимо перейти на вкладку Manage connected services, щёлкнуть кнопку Manage themes, найти в открывшейся таблице соответствующую строку с актуальной темой, выбрать в столбце Credit card значение ecommpay и сохранить изменения, щёлкнув кнопку Save.

      О применении выбранной темы свидетельствует соответствующее уведомление в левом нижнем углу интерфейса.

  3. Убедиться, что платёжный сервис ecommpay готов к проведению оплат, инициируемых через интерфейс Xero, перейдя на вкладку Manage payment methods и проверив наличие записи ecommpay в группе платёжных сервисов..

    Для этого необходимо перейти на вкладку Manage payment methods и убедиться, что ecommpay отображается в группе платёжных сервисов Connected payment apps и его статус активен (статус, отображаемый справа от названия сервиса, должен принять значение On).

В приложении от ecommpay и интерфейсе Xero эта процедура может выглядеть следующим образом.

Рис. 7. Формирование ссылки
Рис. 8. Добавление платёжного сервиса
Рис. 9. Проверка платёжного сервиса

Формирование платёжных ссылок

После соответствующей настройки (подробнее) в интерфейсе Xero поддерживается возможность проведения оплат по ссылкам с использованием платёжной формы Payment Page от ecommpay. При этом стоит учитывать, что такие оплаты в платформе Xero считаются оплатами с использованием платёжных ссылок, в то время как в платформе ecommpay — разовыми оплатами через Payment Page (подробнее об этом типе платежей — в отдельной статье).

Чтобы провести разовую оплату с использованием платёжной ссылки, следует:

  1. Открыть страницу для работы с платёжными ссылками в интерфейсе Xero, выбрав в верхнем меню пункт Business > Invoices.

    Для этого необходимо перейти в интерфейс Xero, раскрыть в верхнем меню пункт Business и выбрать в нём пункт Invoices.

  2. Открыть форму для задания параметров новой оплаты, щёлкнув кнопку New Invoice на панели управления.

  3. Задать параметры оплаты и сформировать ссылку.Задать параметры оплаты, сформировать ссылку и отправить ссылку пользователю, щёлкнув кнопку Approve & email.

    Для этого необходимо заполнить актуальные поля и отправить ссылку пользователю, щёлкнув кнопку Approve & email. Также можно сохранить изменения без отправления ссылки пользователю (в том числе для последующих уточнений), щёлкнув кнопку Save & close.

    К обязательным для заполнения полям относятся: To, Issue date, Due date, Invoice number, Online payments, Currency, Item, Qty. и Price.

    • To — имя пользователя, которому необходимо отправить платёжную ссылку;
    • Issue date и Due date — даты начала и окончания срока действия ссылки (этот срок не должен превышать 30 суток с даты формирования ссылки);
    • Invoice number — идентификатор платежа, уникальный в рамках используемого проекта в платформе ecommpay (этот идентификатор указывается автоматически, но может быть скорректирован вручную);
    • Online payments — название платёжного сервиса (провайдера), используемого для проведения платежа (в качестве такого провайдера должен быть выбран ecommpay);
    • Currency — название валюты, используемой для позиций выставляемого счёта на оплату (в рамках счёта может использоваться только одна валюта);
    • Item — наименование единицы услуги или товарной позиции;
    • Qty. — количество единиц услуги или товарной позиции;
    • Price — стоимость единицы услуги или товарной позиции.

  4. Отправить ссылку пользователю, щёлкнув кнопку Send email.

    Для этого следует проверить содержание письма на открывшейся странице, при необходимости внести изменения и подтвердить отправку, щёлкнув кнопку Send email.

  5. Убедиться, что оплата проведена.

    При проведении разовой оплаты можно проверять её статус в интерфейсe Xero на странице Invoices (статус должен принять значение paid) и в интерфейсе Dashboard в разделе Платежи (статус должен принять значение success). Список возможных статусов для разовых оплат в платформе ecommpay представлен в отдельной статье.

В интерфейсе Xero эта процедура может выглядеть следующим образом.

Рис. 10. Открытие страницы Invoices
Рис. 11. Открытие формы новой оплаты
Рис. 12. Задание параметров оплаты
Рис. 13. Отправка ссылки пользователю