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

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

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

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

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

Подключение

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

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

1. Согласовать со специалистами технической поддержки ecommpay, в какие сроки можно подключить такую возможность, и обеспечить наличие учётной записи портала Xero Developer.
2. Получить от специалистов ecommpay подтверждение о завершении настройки веб-приложения и его готовности к подключению.

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

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

4. Подключить веб-приложение.
   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.

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

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

   Если подключение выполнено, в интерфейсе 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. При необходимости, задать условия фильтрации операций по валютам и проектам.

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

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

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

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

   

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

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

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

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

   

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

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

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

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 и проверив его наличие в группе платёжных сервисов..

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

   

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

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

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

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

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

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 эта процедура может выглядеть следующим образом.