FAQ
Введение
В данном разделе приводятся ответы на вопросы, которые обычно возникают у технических специалистов мерчантов.
Эти вопросы разбиты на следующие группы:
- Интеграция с платформой — о подключении к платформе и настройке и тестировании различной функциональности.
- Проведение платежей — о порядке проведения разных видов платежей и выполнения разных операций и процедур, а также о правилах указания различных параметров в запросах.
- Приём оповещений — о работе с программными оповещениями от платёжной платформы, в том числе о параметрах и настройках этих оповещений.
- Контроль результатов — о контроле и интерпретации результатов различных платежей, операций и процедур, выполняемых в платформе.
Если информации, представленной в этом и других разделах документации, оказывается недостаточно для решения ваших задач, следует обращаться к нашим специалистам:
- с деловыми и финансовыми вопросами (о стоимости услуг, расчёте комиссий, работе с балансами и так далее) — к курирующему менеджеру;
- с техническими вопросами (о работе с разными интерфейсами, составлении запросов и тому подобном) — к сотрудникам технической поддержки (support@ecommpay.com).
Интеграция с платформой
Рис.: Для чего нужен PCI DSS и как ему соответствовать?
Payment Card Industry Data Security Standard (PCI DSS) — это стандарт по надлежащей защите данных платёжных карт. Он разработан Советом по стандартам безопасности индустрии платёжных карт (PCI SSC) и устанавливает требования для всех организаций, применяющих в своей деятельности обработку, хранение или передачу данных платёжных карт. Соблюдать требования этого стандарта обязаны все стороны, задействованные в проведении платежей с использованием платёжных карт — без соблюдения этих требований проводить такие платежи нельзя.
Чтобы подтверждать соответствие требованиям PCI DSS и иметь возможность проводить платежи с использованием платёжных карт, со стороны мерчанта необходимо своевременно предоставлять соответствующие документы платёжным системам (таким как Visa, Mastercard и Amex), напрямую или через провайдеров. Разные платёжные системы могут предъявлять разные требования к таким документам, в том числе с учётом фактов компрометации данных и прочих факторов, поэтому необходимость предоставления конкретным мерчантом тех или иных документов рассматривается индивидуально.
В случаях с платёжными системами Visa и Mastercard документы о соответствии PCI DSS следует предоставлять ECommPay. К таким документам относятся:
- Для всех мерчантов — отчёт о результатах ASV-сканирования.
Эти сканирования должны выполняться авторизованными поставщиками (PCI SSC Approved Scanning Vendor, ASV) ежеквартально, а также после каждого значительного изменения сетевой инфраструктуры. Мерчанты ECommPay могут выбирать поставщиков самостоятельно и, если это актуально, могут выполнять сканирования с помощью соответствующего партнёра ECommPay. Чтобы организовать сканирования через партнёра ECommPay, можно обращаться к курирующему менеджеру.
- Для мерчантов с количеством операций более 6 миллионов в год (уровня 1) — аттестат соответствия (Attestation of Compliance, AOC).
- Для мерчантов с количеством операций до 6 миллионов в год (уровней 2, 3 и 4) — опросный лист (Self-Assessment Questionnaire, SAQ).
С вопросами о правилах заполнения опросных листов можно обращаться к курирующему менеджеру ECommPay.
После проверки всех требуемых документов можно проводить платежи с использованием карт этих платёжных систем — об этом, как и об истечении сроков действия отдельных документов, мерчанта оповещает курирующий менеджер ECommPay.
В случаях с другими платёжными системами, как правило, документы о соответствии PCI DSS следует предоставлять напрямую этим платёжным системам, но можно уточнять необходимость их предоставления ECommPay у курирующего менеджера.
Рис.: В чём различия между тестовой и рабочей средами?
Обычно при подключении к платёжной платформе мерчанту предоставляется доступ сначала к тестовой среде, а после — к рабочей. Чтобы протестировать основные сценарии работы без проведения реальных платежей и выводить в свет настроенные и проверенные решения.
Для этого специалисты технической поддержки ECommPay создают и настраивают в платформе два проекта взаимодействия с подключаемым веб-сервисом — тестовый и рабочий, с отдельным идентификатором для каждого из них. И как раз при смене в запросах этого идентификатора (project_id
) происходит магия — всё тестовое превращается в настоящее. Поскольку и адреса для приёма запросов, и наборы параметров в тестовой и рабочей средах идентичны, важно не путать идентификаторы проектов и обращаться с ними должным образом.
По умолчанию создаётся один тестовый проект, но при необходимости можно запросить у технической поддержки дополнительные. Также стоит учитывать, что в тестовой среде ограничено количество платёжных методов и сценариев работы. Подробности можно найти в соответствующих разделах о тестировании при прямом использовании платёжных карт (Тестовые карты) и при работе с альтернативными платёжными методами (например, тестирование QIWI-кошелька).
Все тестовые платежи, как и настоящие, учитываются в платформе, и информация о них отображается в интерфейсе Dashboard, а используемые при тестировании реквизиты платёжных инструментов обрабатываются и защищаются, как и реальные, но никаких реальных списаний средств при этом не выполняется. Поэтому при тестировании можно получать полноценное представление о работе с платежами и не бояться использовать разные данные, в том числе данные реальных платёжных карт, кошельков и других инструментов.
И да, что же такое среда в каждом из этих случаев? Это совокупность внутренних программных компонентов платформы, которые в одном случае сконфигурированы для эмулирования процессов проведения платежей, а в другом — для их реального проведения. Вот и всё :)
Рис.: Куда отправлять запросы?
Платёжная платформа ECommPay устроена таким образом, что для каждого из её интерфейсов используется свой базовый адрес.
Это важно учитывать в тех случаях, когда, например, для одних действий используется Payment Page, а для других — Gate. Так, для формирования токена через Payment Page и проведения выплаты по этому токену через Gate потребуются два запроса на два разных адреса: https://paymentpage.ecommpay.com
и https://api.ecommpay.com
. А для получения через Data API информации о балансе средств после проведения этой выплаты — запрос на третий адрес: https://data.ecommpay.com/v1
. Такое изобилие адресов, конечно, может вызвать путаницу, но всё-таки мы верим, что оно вполне поддаётся пересчёту и осмыслению.
Информация о базовых адресах, структурах запросов и прочих особенностях каждого из интерфейсов нашей платформы представлена в описании работы с этими интерфейсами, а полный список адресов для программных и пользовательских действий выглядит следующим образом:
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/v1
для взаимодействия через Data API. Например, адрес для запроса на получение балансов выглядит какhttps://data.ecommpay.com/v1/balance/get
. Подробная информация о работе с запросами к Data API представлена в разделе Использование Data API для Dashboard.- dashboard.ecommpay.com для доступа сотрудников мерчантов к веб-интерфейсу Dashboard.
Рис.: В чём различия между платежом и операцией?
Платёж в контексте платформы — некоторая цельная история одного расчёта между мерчантом и пользователем. При этом в рамках одного платежа может происходить как однократное движение денежных средств (от пользователя к мерчанту при оплате или в обратную сторону при выплате), так и неоднократное (например, при оплате с последующим возвратом или при серии списаний в рамках одной оплаты). Платёж считается завершённым, когда завершены расчёты между мерчантом и пользователем в рамках оказания соответствующей услуги (и соответствующей исходной заявки мерчанта на проведение платежа). И, как и в жизни, может менять конечное состояние: например, оплата может быть успешно проведённой (success
), а спустя некоторое время — частично возвращённой (partially refunded
).
Операция в контексте платформы — это однократное действие над денежными средствами в рамках проведения платежа. Это может быть, в частности, блокировка средств для их последующего списания, само списание, возврат или выплата. Для проведения одного платежа, с учётом его специфики, могут требоваться как одна, так и множество операций, но в любом случае такое разделение помогает контролировать расчёты на уровне цельных историй-платежей и конкретных действий-операций.
Для каждого платежа в платформе используется его идентификатор (payment_id
), который задаётся со стороны мерчанта, передаётся в запросах в платёжную платформу и однозначно идентифицирует платёж в рамках проекта. Такие идентификаторы могут состоять из цифр, букв латинского алфавита и других символов в кодировке UTF-8 и не должны превышать 255 знаков: например, payment-123 или cosmoshop.sale_456. При получении корректного запроса в платформе регистрируется платёж и инициируется выполнение операции по этому платежу. Каждой операции в платформе присваивается идентификатор (operation_id
), уникальный в рамках платформы. Эти идентификаторы передаются в оповещениях и отображаются в интерфейсе Dashboard.
Также следует учитывать, что у платежа и операции могут отличаться статусы, например у платежа со статусом refunded
операция возврата будет иметь статус success
. Подробнее о различиях и особенностях этих понятий можно почитать в разделе Модель проведения платежей.
Рис.: В чём различия между оплатой, возвратом и выплатой?
Давайте уточним:
- Оплата — это платёж с переводом денег от пользователя к мерчанту. Оплатой может быть покупка товаров и услуг, внесение предоплаты за бронирование, платёж по подписке и так далее. И оплаты могут быть как разовыми, так и повторяющимися. А ещё по ним могут выполняться возвраты.
- Возврат — это операция возвращения от мерчанта к пользователю денег по проведённой оплате. Возвратом может быть, например, отмена бронирования или возвращение товара. И возвраты могут быть на всю сумму оплаты (полными) или на часть суммы (частичными).
- Выплата — это платёж с переводом денег от мерчанта к пользователю. Выплатой может быть получение пользователем выигрыша, бонуса или компенсации расходов и так далее.
Проведение оплат возможно через любой из доступных в платёжной платформе интерфейсов. Выплаты и возвраты в платёжной платформе осуществляются через Gate API и Dashboard. Однако следует учитывать, что для альтернативных платёжных методов могут поддерживаться не все эти возможности, в то время как для карточных все они поддерживаются в полной мере. Актуальную информацию о работе с каждым из методов можно получать в разделе с его описанием.
Рис.: В чём различия между оплатами в одну и две стадии?
Если кратко, то отличия в том, насколько быстро списываются деньги и насколько легко и быстро их потом можно полностью или частично вернуть пользователю.
Смысл оплаты в одну стадию в том, что деньги списываются без задержек — с той скоростью, с которой это осуществляется на уровне платёжных систем. Это удобно для оплаты товаров и фактически оказанных услуг, когда сумма оплаты уже определена и не подлежит изменению. Если же после проведения такой оплаты надо вернуть деньги пользователю, для этого требуется выполнить полный или частичный возврат средств. Оплаты в одну стадию поддерживаются при работе с разными платёжными методами и применяются в том числе для погашения кредитов и займов в микрофинансовых организациях. Подробная информация о проведении этих оплат представлена в разделе Оплата в одну стадию.
Смысл оплаты в две стадии в том, что деньги сначала блокируются и позднее, при подтверждении, списываются или возвращаются пользователю — с учётом того, какой оказывается итоговая сумма оказанных услуг. Это удобно при разных видах бронирования и аренды, сервисов с предоплатой и страховыми взносами и так далее. Списание заблокированных средств в таких случаях может выполняться по подтверждающему запросу мерчанта или по истечению заданного времени. Если же необходимо вернуть средства пользователю, то до списания это можно сделать через отмену блокировки, а после списания — через возврат, как и в случаях с оплатами в одну стадию. Оплаты в две стадии в настоящее время поддерживаются только при работе с платёжными картами. Подробная информация об их проведении представлена в разделе Оплата в две стадии.
При выборе варианта, наиболее подходящего для конкретного вида бизнеса в конкретных регионах, всегда можно обращаться за консультациями к курирующему менеджеру ECommPay.
Рис.: В чём различия между платёжными методами?
Платёжные методы в платформе ECommPay — это способы проведения платежей, которые характеризуются поддерживаемыми операциями, валютами, платёжными инструментами и пользовательскими сценариями в доступных регионах для конкретных платёжных систем. Так, оплаты индонезийскими рупиями через системы интернет-банкинга Индонезии представляет собой один метод, а оплаты в сетях индонезийских магазинов той же валютой — другой. И такие отличия, специфичные для разных регионов и видов бизнеса, делают актуальными множество платёжных методов в платёжной платформе. Для уточнения различий между конкретными методами и выбора методов, наиболее подходящих для вида бизнеса мерчанта, следует обращаться к курирующему менеджеру ECommPay.
Проведение платежей
Рис.: Почему отличаются наборы обязательных параметров в разных запросах (и что с этим делать)?
Платёжная платформа позволяет выполнять множество операций с использованием разнообразных платёжных методов. Для выполнения этих операций может требоваться участие разных партнёров (платёжных систем и провайдеров), и у каждого из этих партнёров могут применяться свои правила работы и требования к параметрам для проведения платежей. Поэтому такие параметры, как описание платежа, номер телефона пользователя или адрес его электронной почты и прочие подобные, могут быть обязательны в одних случаях и не обязательны в других.
В платформе мы стараемся обеспечивать максимальную доступность платежей и операций, поэтому в каждом случае сводим число строго обязательных параметров к минимуму и описываем это в спецификациях API и документации. Вместе с тем, для сложных ситуаций, когда для одной операции в рамках одного платёжного метода одни и те же параметры могут быть обязательными или нет с учётом специфических факторов (как, например, в случае с проверкой AVS), мы применяем специальную процедуру с дополнением информации о платеже по ходу его проведения (Дополнение информации о платеже).
Чтобы оптимизировать работу с обязательными и необязательными параметрами, на стороне веб-сервиса можно настроить регистрацию и использование в каждом запросе максимально полного набора данных о пользователях (поскольку именно эти параметры чаще всего могут запрашиваться в качестве дополнительных со стороны провайдеров и платёжных систем). Также с частными вопросами о параметрах и работе с ними всегда можно обращаться к специалистам технической поддержки ECommPay.
Рис.: Зачем указывать платёжный метод при вызове Payment Page?

force_payment_method
, то платёжная форма открывается со страницы для работы с выбранным методом. Как правило, это страница для указания платёжных реквизитов:
Это удобно и помогает улучшать пользовательские сценарии. Однако, стоит учитывать, что при вызове Payment Page с указанием метода выбор пользователем другого метода уже невозможен. Поэтому открывать Payment Page с указанием метода стоит только в тех случаях, когда есть уверенность, что для пользователя актуален ровно один метод оплаты. Подробная информация о работе с этой возможностью представлена в разделе Предварительный выбор платёжных методов.
Вместе с тем, для оптимизации пользовательских сценариев и способов работы с платёжными методами могут быть полезны такие возможности, как ограничение списка платёжных методов (с использованием параметра hide
) и оплата с использованием токенов платёжных карт (Проведение оплат по токенам).
Рис.: Почему важно передавать идентификатор и IP-адрес пользователя?
При работе с платёжной платформой ECommPay к числу обязательных параметров для выполнения финансовых операций относятся IP-адрес и идентификатор пользователя. Они необходимы для анализа операций на предмет мошенничества, и при отсутствии или некорректном указании этих данных операции могут отклоняться, понижая конверсию.
Рис.: Как указывать имя пользователя?
При составлении запросов к платёжной платформе может быть актуальным указывать имя и фамилию пользователя и (или) держателя карты. И в таких случаях важно соблюдать ряд условий, потому что эти параметры проходят проверку не только на корректность формата данных, но и на соответствие различным правилам, в том числе правилам защиты от мошенничества. Так, в платёжной платформе запрещено проведение выплат на неперсонифицированные платёжные карты, поскольку их нельзя проверить на санкционные ограничения, поэтому такие платежи отклоняются. Кроме того, имя и фамилия пользователя могут проверяться и на стороне платёжных систем на соответствие их правилам.
Для корректного проведения платежей и предотвращения отказов из-за ошибок при указании имён и фамилий важно соблюдать следующие рекомендации:
- имя и фамилия должны быть реальными, например, CARD HOLDER или Customer Name некорректны;
- количество символов в значении отдельного параметра должно быть не менее 2 и, по возможности, не более 50;
- допускается использование букв, цифр и других символов в кодировке UTF-8.
Для параметра card_holder
дополнительно к перечисленным применяются следующие ограничения:
- допускается использование букв латинского алфавита без диакритических знаков, букв кириллического алфавита, а также:
- точки в сокращениях, например в словах Mr. или Jr.;
- апострофа, например как в d'Arc или O'Hara;
- дефиса в составных именах и фамилиях, например Anna-Maria или Jean-Baptiste;
- не допускается использование дефиса для сокращений, так как он интерпретируется как разделитель между словами, и поэтому, например, конструкция M-r Holder является некорректной, так как образует три слова, два из которых состоят всего из одной буквы;
- значение должно содержать не менее двух слов и не более одной точки, поэтому, например, конструкция Mr. Alexandre Dumas Jr. является некорректной, а Alexandre Dumas Jr. — допустимой.
Рис.: Как указывать номер телефона?
В связи с тем, что каждый платёжный провайдер принимает и обрабатывает номера телефонов по своим правилам, при указании номера телефона в запросе могут возникнуть трудности с заполнением: прописывать ли в начале «+» или «0», указывать ли код страны, использовать ли скобки и дефисы.
Чтобы избежать таких трудностей, в платёжной платформе поддерживается обработка телефонных номеров: достаточно отправить номер телефона с кодом страны, и этот номер будет обработан таким образом, чтобы он был принят провайдером, через которого проводится платёж. При этом можно использовать разные форматы, с плюсом, дефисом и другими символами, но всё же рекомендуется использовать только цифры (от 4 до 24, без пробелов и знаков препинания: например, 9012345678, 79012345678, 0447307418560, 380671381116, 254712539238), потому что внутри платформы все номера приводятся именно к такому виду.
Если номер должен быть введён пользователем при оплате через Payment Page, пользователю отображается форма с подсказками и защитой от ошибок в формате.
Однако при работе с отдельными платёжными методами к формату номера телефона могут предъявляться особые требования. Подробная информация представлена в описаниях платёжных методов.
Рис.: Что можно передавать в параметре description?
В запросах на проведение платежей через платформу используется параметр description
. В зависимости от типа операции и специфики платёжного метода он может быть обязательным, например, для возвратов, и необязательным. Обязательность для разных случаев можно уточнять в статьях с описаниями используемых методов.
- Если параметр
description
обязателен, в его значении необходимо указывать причину выполнения операции, например: Частичный возврат оплаты в связи с тем, что пользователь вернул часть заказа (не подошёл размер), Полный возврат из-за технических проблем с оказанием услуги или Возврат полной суммы билета из-за отмены сеанса. - Если параметр
description
необязателен, в его значении можно указывать любые дополнительные сведения о платеже, например: Пополнение кошелька 007, Зачисление на счёт 271828, Оплата по промокоду или Вывод средств по заявке № 314.
Если эти описания указываются в запросах, то они передаются в оповещениях и отображаются в интерфейсе Dashboard и при необходимости могут использоваться для дополнительного анализа платежей на стороне мерчанта.
Приём оповещений
Рис.: Какие параметры передаются в оповещениях?
В структуру оповещений, отправляемых от платёжной платформы ECommPay к веб-сервису мерчанта, включаются наборы параметров о последней операции и о платеже, к которому она относится. Стандартные параметры для оповещений о проведении финансовых операций и создании токенов описаны в разделе Оповещения. Вместе с тем, по согласованию со специалистами технической поддержки ECommPay можно настраивать структуру оповещений с учётом предпочтений мерчанта. Просматривать и изменять настройки оповещений мерчант может только по запросу в техническую поддержку ECommPay.
Рис.: Почему могут не приходить оповещения?
Если оповещение не приходит в течение установленного периода времени, необходимо убедиться в следующем:
- Оповещения ожидаются по адресу, который был передан специалистам ECommPay при интеграции.
- Для этого адреса корректно настроен приём HTTP-запросов от платёжной платформы: IP-адреса ECommPay добавлены в список разрешённых и сообщения не блокируются на уровне межсетевого экрана или других сетевых устройств.
- В запросе на проведение платежа не отключена функция отправки оповещений — не передан параметр
callback.force_disable
со значением1
.
Если все эти условия выполнены, но оповещения по-прежнему не приходят, следует связаться со службой технической поддержки ECommPay, указав идентификатор проекта и URL, по которому ожидаются оповещения.
Контроль результатов
Рис.: Как узнать о статусе платежа или операции?
Для этого можно использовать как пользовательский интерфейс Dashboard, так и программные сообщения — оповещения, отправляемые в заданных случаях, и ответы, отправляемые на запросы о состоянии платежа.
В случаях с интерфейсом Dashboard всё сводится к реестрам и карточкам платежей, в которых отображается информация о статусах (подробнее — в разделах Контроль проведения платежей для Dashboard). При этом стоит учитывать, что задержка в отображении данных в этих интерфейсах может достигать нескольких минут.
В случаях с программными сообщениями всё сводится к таким параметрам, как status
, code
и message
в объектах payment
и operation
и в массиве errors
(подробнее — в разделах Оповещения и Получение информации о состоянии платежа). При этом информация является актуальной с точностью до скорости формирования и передачи сообщений.
Рис.: Почему в ответе на запрос статус Success, но средства не списаны?
При работе с интерфейсом Gate надо учитывать, что в синхронных ответах на запросы, обрабатываемые по асинхронной схеме, в параметре status
в теле ответа указывается статус запроса, но не платежа или операции. Статус success
в теле ответа свидетельствует о том, что запрос принят в обработку, а статус error
— о том, что запрос не может быть принят в обработку и выполнен. И не более. Информацию об этих статусах и общей структуре и отправке ответов можно найти в разделе Формат ответа.
Чтобы получать информацию именно о состоянии платежей и операций, а не о приёме запросов, стоит оперировать параметрами status
в соответствующих объектах — payment
и operation
— в оповещениях и ответах на запросы о состоянии платежей, либо использовать интерфейс Dashboard. Информация об этом приведена в ответе на предыдущий вопрос.
Наконец, можно отметить, что в некоторых случаях фактическое зачисление средств на стороне платёжных систем осуществляется с существенной задержкой (вплоть до нескольких суток) после того, как операция была подтверждена и получила конечный статус. Поэтому при вопросах о расхождениях между движением средств и статусами платежей и операций можно обращаться в службу технической поддержки ECommPay, а также уточнять статусы конкретных платежей на стороне провайдеров и платёжных систем.
Рис.: Как узнать причину отклонения операции?
Если во время обработки запроса или выполнения операции возникли ошибки или поводы для отказа, причины их возникновения можно узнать следующими способами:
- В синхронном ответе на запрос, если была обнаружена ошибка при первичной обработке запроса. Подробная информация о таких ошибках представлена в разделе Формат ответа.
- В полученном промежуточном или итоговом оповещении — через код ответа и сообщение, которые могут быть представлены:
- в массиве
errors
, если операция была отклонена на стороне платёжной платформы, например, если операция не прошла проверку на соответствие установленным бизнес-правилам; - в параметрах
operation.code
иoperation.message
, если операция была отклонена на стороне провайдера или платёжной системы.
- в массиве
- В карточке платежа в интерфейсе Dashboard. Подробная информация о работе с реестрами и карточками платежей представлена в разделах Контроль проведения платежей (Dashboard).
Подробная информация о возможных ошибках при выполнении операций и о кодах, которые используются в оповещениях и интерфейсе Dashboard, представлена в разделе Информация об операциях.