Организация взаимодействия

Подключение приложения

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

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

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

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

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

  3. Подключить веб-приложение.
    1. Инициировать подключение веб-приложения под учётной записью Xero, перейдя по ссылке https://xero-app.ecommpay.com и предоставив ecommpay доступ к информации об учётной записи Xero и целевых организациях, для которых актуален обмен информацией между платформами ecommpay и Xero.
      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, необходимо настроить взаимодействие между платформами ecommpay и Xero,. Для этого следует:

  1. Открыть приложение от ecommpay и перейти на вкладку Settings.

  2. Выбрать способ синхронизации, включив переключатель I want to synchronize settlements with XERO и выбрав один из способов: по событиям (Live sync) или по периодам (Daily, Weekly, Monthly).

    Для этого необходимо включить переключатель 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) и до конца заданного календарного периода, в то время как последующие группы охватывают полные периоды. Информация о первой группе таких операций отправляется по завершении первого периода (даже если он неполный).

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

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

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

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

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

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

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

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

  6. Сохранить изменения, щёлкнув кнопку Save changes.

  7. По возможности проверить, что изменения применены и синхронизация обеспечена, используя вкладку Monitoring в веб-приложении от ecommpay.

    Для этого можно:

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

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

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

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

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

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

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

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

    1. Открыть веб-приложение и перейти на вкладку Settings.
    2. Включить необходимые переключатели:
      • I want to offer ecommpay as a payment service on XERO invoices — для использования ecommpay в качестве платёжного сервиса при выставлении счетов на оплаты через интерфейс Xero;
      • I want to offer ecommpay Direct Debit (SEPA and BACS) as payment services provider on Xero invoices — для использования методов Direct Debit BACS и Direct Debit SEPА.
    3. Указать идентификатор и ключ рабочего проекта в полях Project ID и Project Secret.
    4. Сохранить изменения, щёлкнув кнопку Save changes.
  2. Открыть страницу управления платёжными сервисами в интерфейсе Xero.

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

    1. Открыть интерфейс Xero с использованием учётной записи портала Xero Developer.
    2. Открыть раздел со свойствами целевой организации, щёлкнув в левом верхнем углу интерфейса её название и выбрав в открывшемся контекстном меню раздел Settings.
    3. Открыть подраздел со свойствами для управления платёжными сервисами, щёлкнув в группе Features свойство Payment services.
  3. Настроить каждый из актуальных сервисов в интерфейсе Xero.

    Для этого необходимо (отдельно для каждого из настраиваемых сервисов):

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

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

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

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

    Дополнительно для любого из методов Direct Debit можно выставить тестовый счёт со ссылкой на оплату и перейти по этой ссылке. Если платёжные сервисы настроены корректно — должна открываться платёжная форма ecommpay для завершения оплаты, в ином случае — страница приложения от ecommpay с записью о том, что платёжный метод не доступен (Payment method not enabled).

Рис. 4. Подтверждение корректности настройки
Рис. 5. Уведомление о недоступности метода

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

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