FAQ

Введение

В данном разделе приводятся ответы на часто задаваемые вопросы технических специалистов о работе с платёжной платформой ECommPay.

Эти вопросы разбиты на следующие группы:

  • Интеграция с платформой — о подключении к платформе и настройке и тестировании различной функциональности.
  • Проведение платежей — о порядке проведения разных видов платежей и выполнения разных операций и процедур.
  • Приём оповещений — о работе с программными оповещениями от платёжной платформы.
  • Контроль результатов — о контроле и интерпретации результатов различных платежей, операций и процедур, выполняемых в платформе.

Если информации, представленной в этом и других разделах документации, оказывается недостаточно для решения ваших задач — стоит обращаться к нашим специалистам технической поддержки support@ecommpay.com.

Интеграция с платформой

Рис.: В чём различия между тестовой и рабочей средами?

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

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

По умолчанию создаётся один тестовый проект, но при необходимости можно запросить у технической поддержки дополнительные. Также стоит учитывать, что в тестовой среде ограничено количество платёжных методов и сценариев работы. Подробности можно найти в соответствующих разделах о тестировании при прямом использовании платёжных карт (Тестовые карты) и при работе с альтернативными платёжными методами (например, Тестирование QIWI-кошелька).

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

И да, что же такое среда в каждом из этих случаев? Это совокупность внутренних программных компонентов платформы, которые в одном случае сконфигурированы для эмулирования процессов проведения платежей, а в другом — для их реального проведения. Вот и всё :)

Рис.: Куда отправлять запросы?

Платёжная платформа ECommPay устроена таким образом, что для каждого из её интерфейсов используется свой базовый адрес.

Это важно учитывать в тех случаях, когда, например, для одних действий используется Payment Page, а для других — Gate. Так, для формирования токена через Payment Page и проведения выплаты по этому токену через Gate потребуются два запроса на два разных адреса: https://paymentpage.ecommpay.com и https://api.ecommpay.com. А для получения через Data API информации о балансе средств после проведения этой выплаты — запрос на третий адрес: https://data.ecommpay.com. Такое изобилие адресов, конечно, может вызвать путаницу, но всё-таки мы верим, что оно вполне поддаётся пересчёту и осмыслению :)

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

  • https://api.ecommpay.com для взаимодействия через Gate. Например, адрес для запроса на получение статуса платежа выглядит как https://api.ecommpay.com/v2/payment/status. Подробная информация о работе с запросами к Gate API представлена в разделе Формат запроса.
  • https://paymentpage.ecommpay.com для взаимодействия через Payment Page. Например, GET запрос на проведение платежа выглядит как GET /payment?payment_currency=EUR&project_id=42&payment_amount=1000&... HTTP/1.1 Host: https://paymentpage.ecommpay.com. Подробная информация о работе с запросами к Payment Page API представлена в разделе Формат запроса.
  • https://data.ecommpay.com для взаимодействия через Data API. Например, адрес для запроса на получение балансов счетов выглядит как https://data.ecommpay.com/v1/balance/get. Подробная информация о работе с запросами к Data API представлена в разделе Использование Data API для Dashboard Light и Формат запроса в Dashboard для Dashboard.
  • dashboard.ecommpay.com для доступа сотрудников мерчантов к веб-интерфейсу Dashboard.
  • dash-light.ecommpay.com для доступа сотрудников мерчантов к веб-интерфейсу Dashboard Light.

Рис.: В чём различия между оплатами в одну и две стадии?

Если кратко, то отличия в том, насколько быстро списываются деньги и насколько легко и быстро их потом можно полностью или частично вернуть пользователю.

Смысл оплаты в одну стадию в том, что деньги списываются без задержек — с той скоростью, с которой это осуществляется на уровне платёжных систем. Это удобно для оплаты товаров и фактически оказанных услуг, когда сумма оплаты уже определена и не подлежит изменению. Если же после проведения такой оплаты надо вернуть деньги пользователю, для этого требуется выполнить полный или частичный возврат средств. Оплаты в одну стадию поддерживаются при работе с разными платёжными методами и применяются в том числе для погашения кредитов и займов в микрофинансовых организациях, с использованием канала приёма платежей Analog Facility Terminal (AFT). Подробная информация о проведении этих оплат представлена в разделе Оплата в одну стадию.

Смысл оплаты в две стадии в том, что деньги сначала блокируются и позднее, при подтверждении, списываются или возвращаются пользователю — с учётом того, какой оказывается итоговая сумма оказанных услуг. Это удобно при разных видах бронирования и аренды, сервисов с предоплатой и страховыми взносами и так далее. Списание заблокированных средств в таких случаях может выполняться по подтверждающему запросу мерчанта или по истечению заданного времени. Если же необходимо вернуть средства пользователю, то до списания это можно сделать через отмену блокировки, а после списания — через возврат, как и в случаях с оплатами в одну стадию. Оплаты в две стадии в настоящее время поддерживаются только при работе с платёжными картами. Подробная информация об их проведении представлена в разделе Оплата в две стадии.

При выборе варианта, наиболее подходящего для конкретного вида бизнеса в конкретных регионах, всегда можно обращаться за консультациями к курирующему менеджеру ECommPay.

Проведение платежей

Рис.: Зачем указывать платёжный метод при вызове Payment Page?

Платёжная форма Payment Page по умолчанию открывается со страницы выбора платёжного метода:

Но порой это может быть лишним. Например, если пользователь выбирает метод оплаты до вызова платёжной формы или если ему по каким-то причинам надо предоставить конкретный метод, предпочтительный для оплат из конкретного региона. Для таких случаев предусмотрен вызов Payment Page с указанием конкретного платёжного метода. И если в запросе на открытие формы использовать параметр force_payment_method, то платёжная форма открывается со страницы для работы с выбранным методом. Как правило, это страница для указания платёжных реквизитов:

Это удобно и помогает улучшать пользовательские сценарии. Однако, стоит учитывать, что при вызове Payment Page с указанием метода выбор пользователем другого метода уже невозможен. Поэтому открывать Payment Page с указанием метода стоит только в тех случаях, когда есть уверенность, что для пользователя актуален ровно один метод оплаты. Подробная информация о работе с этой возможностью представлена в разделе Предварительный выбор платежного метода.

Вместе с тем, для оптимизации пользовательских сценариев и способов работы с платёжными методами могут быть полезны такие возможности, как ограничение списка платёжных методов (с использованием параметра hide) и оплата с использованием токенов платёжных карт (Проведение оплат по токенам).

Рис.: Почему важно передавать идентификатор и IP-адрес пользователя?

При работе с платёжной платформой ECommPay к числу обязательных параметров для выполнения финансовых операций относятся IP-адрес и идентификатор пользователя. Они необходимы для анализа операций на предмет мошенничества, и при отсутствии или некорректном указании этих данных операции могут отклоняться, понижая конверсию.

Рис.: В чём различия между платёжными методами?

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

Рис.: Почему отличаются наборы обязательных параметров в разных запросах (и что с этим делать)?

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

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

Чтобы оптимизировать работу с обязательными и необязательными параметрами, на стороне веб-сервиса можно настроить регистрацию и использование в каждом запросе максимально полного набора данных о пользователях (поскольку именно эти параметры чаще всего могут запрашиваться в качестве дополнительных со стороны провайдеров и платёжных систем). Также с частными вопросами о параметрах и работе с ними всегда можно обращаться к специалистам технической поддержки ECommPay.

Приём оповещений

Рис.: Какие параметры передаются в оповещениях?

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

Рис.: Почему не приходит оповещение?

Если оповещение не приходит в течение установленного периода времени, необходимо убедиться в следующем:

  1. Оповещения ожидаются по адресу, который был передан специалистам ECommPay при интеграции.
  2. Для этого адреса корректно настроен приём HTTP-запросов от платёжной платформы: IP-адреса ECommPay добавлены в список разрешённых и сообщения не блокируются на уровне межсетевого экрана или других сетевых устройств.
  3. В запросе на проведение платежа не отключена функция отправки оповещений — не передан параметр callback.force_disable со значением 1.

Если все эти условия выполнены, но оповещения по-прежнему не приходят, следует связаться со службой технической поддержки ECommPay, указав идентификатор проекта и URL, по которому ожидаются оповещения.

Контроль результатов

Рис.: Как узнать о статусе платежа или операции?

Для этого можно использовать как пользовательский интерфейс Dashboard Light (Dashboard), так и программные сообщения — оповещения, отправляемые в заданных случаях, и ответы, отправляемые на запросы о состоянии платежа.

В случаях с интерфейсами Dashboard Light и Dashboard всё сводится к реестрам и карточкам платежей, в которых отображается информация о статусах (подробнее — в разделах Контроль проведения платежей для Dashboard Light и Платежи для Dashboard). При этом стоит учитывать, что задержка в отображении данных в этих интерфейсах может достигать нескольких минут.

В случаях с программными сообщениями всё сводится к таким параметрам, как status, code и message в объектах payment и operation и в массиве errors (подробнее — в разделах Оповещения и Получение информации о состоянии платежа). При этом информация является актуальной с точностью до скорости формирования и передачи сообщений.

Рис.: Почему у платежа статус Success, но средства не списаны?

При работе с интерфейсом Gate надо учитывать, что в синхронных ответах на запросы в параметре status в теле ответа указывается статус запроса, но не платежа или операции. Статус success в ответе свидетельствует о том, что запрос принят в обработку, а статус decline — о том, что запрос не может быть принят в обработку и выполнен. И не более. Информацию об этих статусах и общей структуре и отправке ответов можно найти в разделе Формат ответа.

Чтобы получать информацию именно о состоянии платежей и операций, а не о приёме запросов, стоит оперировать параметрами status в соответствующих объектах — payment и operation — в оповещениях и ответах на запросы о состоянии платежей, либо использовать интерфейс Dashboard Light (Dashboard). Информация об этом приведена в ответе на предыдущий вопрос.

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

Рис.: Как узнать причину отклонения операции?

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

  • В синхронном ответе на запрос, если была обнаружена ошибка при первичной обработке запроса. Подробная информация о таких ошибках представлена в разделе Формат ответа.
  • В полученном промежуточном или итоговом оповещении — через код ответа и сообщение, которые могут быть представлены:
    • в массиве errors, если операция была отклонена на стороне платёжной платформы, например, если операция не прошла проверку на соответствие установленным бизнес-правилам;
    • в параметрах operation.code и operation.message, если операция была отклонена на стороне провайдера или платёжной системы.
    Подробная информация о работе с оповещениями представлена в разделе Оповещения.
  • В карточке платежа в интерфейсе Dashboard Light (Dashboard). Подробная информация о работе с реестрами и карточками платежей представлена в разделах Контроль проведения платежей (Dashboard Light) и Платежи (Dashboard).

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