FAQ

Payment Card Industry Data Security Standard (PCI DSS) — это стандарт по надлежащей защите данных о держателях платежных карт. Он разработан Советом по стандартам безопасности индустрии платежных карт и устанавливает требования для всех организаций, применяющих в своей деятельности обработку, хранение или передачу данных платежных карт. Без соблюдения требований PCI DSS проводить платежи с использованием платежных карт нельзя.

Если мерчант обладает сертификатом на соответствие требованиям PCI DSS, он может предоставить PSPHost копию сертификата и выстраивать работу любым образом, в том числе с хранением данных о картах на своей стороне и передачей этих данных в запросах в явном виде. Если же сертификата нет, необходимо заполнить лист самооценки (с вопросами о его заполнении можно обращаться к курирующему менеджеру PSPHost), после чего можно хранить данные на стороне платежной платформы и проводить оплаты с помощью платежной формы PSPHost, а выплаты — с использованием токенов карт (подробнее о токенах — в разделе Использование токенов).

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

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

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

Среда — это совокупность внутренних программных компонентов платформы, которые в одном случае сконфигурированы для эмулирования процессов проведения платежей, а в другом — для их реального проведения.

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

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

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

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

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

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

Для каждого платежа в платформе используется его идентификатор (payment_id), который задается со стороны мерчанта, передается в запросах в платежную платформу и однозначно идентифицирует платеж в рамках проекта. Такие идентификаторы могут состоять из цифр, букв латинского алфавита и других символов в кодировке UTF-8 и не должны превышать 255 знаков: например, payment-123 или cosmoshop.sale_456. При получении корректного запроса в платформе регистрируется платеж и инициируется выполнение операции по этому платежу. Каждой операции в платформе присваивается идентификатор (operation_id), уникальный в рамках платформы. Эти идентификаторы передаются в оповещениях и отображаются в интерфейсе Dashboard.

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

s

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

Проведение оплат возможно через любой из доступных в платежной платформе интерфейсов. Выплаты и возвраты в платежной платформе осуществляются через Gate API и Dashboard. Однако следует учитывать, что для альтернативных платежных методов могут поддерживаться не все эти возможности, в то время как для карточных все они поддерживаются в полной мере. Актуальную информацию о работе с каждым из методов можно получать в разделе с его описанием.

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

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

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

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

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

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

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

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

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

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

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

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

При работе с платежной платформой PSPHost к числу обязательных параметров для выполнения финансовых операций относятся 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 необязателен, в его значении можно указывать любые дополнительные сведения о платеже, например: Пополнение кошелька 007, Зачисление на счет 271828, Оплата по промокоду или Вывод средств по заявке № 314.

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

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

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

• Ваш веб-сервис ожидает оповещения по URL-адресу, который был передан специалистам PSPHost при интеграции.
• URL-адрес корректно настроен на прием HTTP-запросов от платежной платформы: IP-адреса PSPHost добавлены в список разрешенных и сообщения не блокируются брандмауэром или другими сетевыми устройствами.
• В запросе на проведение платежа не передавался параметр callback.force_disable со значением 1, которое запрещает платежной платформе отправлять оповещения по этому платежу.

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

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

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

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

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

Получать информацию о состоянии платежей и операций, а не о приеме запросов, стоит оперировать параметрами status в соответствующих объектах — payment и operation — в оповещениях и ответах на запросы о состоянии платежей, либо использовать интерфейс Dashboard.

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

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

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

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