• История изменений
• Предисловие
• Термины и определения
• Введение
• Регистрация
• Процесс обработки Платежа
  1. Однофазный платеж
  2. Двухфазный платеж
  3. Платеж с криптограммой

• Статусы Платежа
  1. Однофазный платеж
  2. Двухфазный платеж

• Отмена Платежа
• Формирование криптограммы
• Протокол взаимодействия
  1. Операция CreatePayment
  2. Операция InitRecurrent
  3. Операция ProcessPayment
  4. Работа с 3-D Secure аутентификацией
  5. Оповещение ЭМ о результате платежа и возврат Клиента на сайт ЭМ
  6. Операция GetPaymentStatus
• Операция ConfirmPayment
  1. Операция CancelPayment
  2. Операция ReversalPayment
  3. Операция RefundPayment
  4. Операция LinkCard
  5. Операция CheckCard
  6. Операция UnlinkCard
  7. Операция GetLinkedCards
  8. Операция SendLinkCode
  9. Операция ConfirmLinkCode

• Приложение № 1
• Приложение № 2
• Приложение № 3 - пример страницы работающей с криптограммой

История изменений

Изменения в 3.6.x помечены *

Предисловие

Данный документ описывает техническое взаимодействие ТСП с сервисом интернет-эквайринга компании ЗАО «МОБИ.Деньги» для проведения платежей за товары и услуги с использованием банковских карт.

Термины и определения

Введение

Сервис Интернет-эквайринга Компании (далее Сервис) позволяет оплачивать Клиентам торгово-сервисного предприятия (ТСП) товары и/или услуги через интернет с банковских карт платежных систем Visa, MasterCard, JCB и DCL.

Взаимодействие Сервиса происходит с одним или несколькими электронными магазинами (ЭМ), через которые ТСП производит распространение своих товаров.

Сервис предоставляет возможность проводить однофазные и двухфазные платежи:

• Однофазный платеж - списание денежных средств с Карты Клиента в счет ТСП происходит в момент подтверждения Клиентом Платежа без предварительного резервирования средств.
• Двухфазный платеж - в момент подтверждения Клиентом Платежа происходит резервирование денежных средств на Карте Клиента, списание денежных средств с Карты Клиента происходит после подтверждения ЭМ (в случае возможности предоставления Товара Клиенту). Если товар не может быть предоставлен Клиенту резервирование денежных средств может быть отменено по инициативе ЭМ, либо автоматически по истечению срока резервирования.

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

Взаимодействие с ЭМ осуществляется по протоколу HTTP.

Сервис позволяет получать автоматические оповещения о результатах Платежа, а так же получить их по запросу.

При настройке подключении ЭМ доступна опция отображения результатов Платежа Клиенту после его проведения.

Регистрация

Для начала технического взаимодействия с Сервисом, необходимо зарегистрировать ТСП, продаваемый товар(ы) (или услугу) и один или несколько ЭМ. Для этого необходимо указать:

• Наименование ТСП;
• Наименование ЭМ;
• Для каждого ЭМ:По каждому товару заполнить анкету, приведенную в Приложение № 1;
  • Адрес обратной связи общий (CALLBACK_URL) и, при желании, адрес обратной связи в случае неудачи (CALLBACK_FAIL_URL) - для автоматического оповещения;
  • Адрес по умолчанию для возврата пользователя (DEF_RETURN_URL) и, при желании, адрес возврата пользователя в случае неудачи (DEF_FAIL_URL) - указанные адреса будут использоваться если RETURN_URL и FAIL_URL не будут переданы в CreatePayment, LinkCard, CheckCard.
  • Необходимость показывать страницу с результатами платежа Клиенту перед перенаправлением обратно в ЭМ (Да/Нет);
• Передать файл логотипа магазина (установленного формата и размера);
• С целью усиления информационной безопасности, возможно, настроить список IP адресов, с которых будет происходить обращение от ЭМ в Сервис.

Если регистрируемый товар связан с пополнением лицевого счета Клиента (определяется Компанией), то ЭМ должен указывать счет-получатель в отдельном параметре операции CreatePayment при создании платежа за этот товар (см. раздел «Операция  CreatePayment»).
В результате регистрации, ТСП получает следующую информацию:

• MERCHANT_ID - уникальный идентификатор ТСП;

для каждого зарегистрированного ЭМ:

• TERMINAL_ID - уникальный идентификатор ЭМ;
• LOGIN - логин для авторизации запросов;
• PASSWD - пароль для авторизации запросов;
• Если для ЭМ доступна возможность оплаты по криптограмме: ссылка для загрузки скрипта шифрования данных и UUID (дополнительный идентификатор для создания криптограммы) *

для каждого зарегистрированного товара:

• ARTICLE_ID - уникальный идентификатор товара;
• признак необходимости передавать счет-получатель.

Выданные логин и пароль являются конфиденциальной информацией. ТСП ни в коем случае не должно передавать третьим лицам эту информацию. В случае подозрения на компрометацию этой информации сотрудники ТСП должны незамедлительно обратиться в Службу информационной безопасности Компании: телефон: +7 960 270 50 42, e-mail: isecurity@1mps.ru.

Процесс обработки Платежа

Тип проводимого платежа: однофазный или двухфазный, определяется параметром  PTYPE в операции  CreatePayment (см. раздел «Операция  CreatePayment»). Процесс оплаты зависит от типа платежа.

Однофазный платеж

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

1. Клиент в ЭМ выбирает опцию оплатить товар с помощью Сервиса.
2. ЭМ инициирует Платеж в Сервисе (операция  CreatePayment, параметр PTYPE=1).
3. ЭМ переадресовывает Клиента на страницу оплаты Сервиса.
4. Клиент указывает реквизиты банковской карты и авторизует Платеж с помощью одноразового пароля высылаемого в sms сообщении на указанный им телефон.
5. Сервис проводит списание денежных средств с банковской карты.
6. Сервис оповещает ЭМ о результатах проведения Платежа.
7. Сервис отображает Клиенту страницу с результатами проведения Платежа и кнопкой возврата в ЭМ.
8. Клиент обратно возвращается в ЭМ.

ВНИМАНИЕ: клиент должен быть перенаправлен на страницу оплаты не позже чем спустя 1 час после выполнение шага 2. Иначе созданный Платеж автоматически отменяется по таймауту.
Шаги 6 и 7 являются опциональными:

• Шаг 6 может быть пропущен, если ЭМ не подразумевает обратной связи от Сервиса. В этом случае ЭМ должен самостоятельно запросить статус платежа (операция  GetPaymentStatus).
• Шаг 7 может быть пропущен, если Клиент должен автоматически перенаправляться обратно в ЭМ. В этом случае ожидается, что ЭМ самостоятельно отобразит результаты проведения Платежа.

Логика оповещения ЭМ и возврата Клиента на сайт ЭМ описана в разделе «Оповещение ЭМ о результате платежа и возврат Клиента на сайт ЭМ».

Двухфазный платеж

В случае если на момент проведения Платежа ТСП не может гарантировать поставку товара Клиенту, ЭМ должен использовать двухфазный платеж. Первая фаза такого полностью совпадает с однофазным платежом, описанным в разделе выше, с тем отличием, что на шаге 5 происходит не списание, а резервирование денежных средств на карте Клиента. После того как определяется доступность товара ЭМ должен подтвердить или отменить платеж, что является второй фазой двухфазного платежа. Таким образом, полный процесс оплаты при двухфазном платеже выглядит следующим образом:

1. Клиент в ЭМ выбирает опцию оплатить товар с помощью Сервиса.
2. ЭМ инициирует Платеж в Сервисе (операция  CreatePayment, параметр  PTYPE=2).
3. ЭМ переадресовывает Клиента на страницу оплаты Сервиса.
4. Клиент указывает реквизиты банковской карты и авторизует Платеж с помощью одноразового пароля высылаемого в sms сообщении на указанный им телефон.
5. Сервис проводит резервирование денежных средств на банковской карте.
6. Сервис оповещает ЭМ о результатах проведения Платежа.
7. Сервис отображает Клиенту страницу с результатами проведения Платежа и кнопкой возврата в ЭМ.
8. Клиент обратно возвращается в ЭМ.
9. После того как доступность товара Клиенту будет определена, но не позднее чем спустя 12 часов после выполнения шага 5, ЭМ производит:
   • подтверждение Платежа (операция  ConfirmPayment)
   • или отмену Платежа (операция  CancelPayment)

ВНИМАНИЕ: клиент должен быть перенаправлен на страницу оплаты не позже чем спустя 1 час после выполнение шага 2. Иначе созданный Платеж отменится по таймауту.
Шаги 6 и 7 являются опциональными:

• Шаг 6 может быть пропущен, если ЭМ не подразумевает обратной связи от Сервиса. В этом случае ЭМ должен самостоятельно запросить статус платежа (операция  GetPaymentStatus).
• Шаг 7 может быть пропущен, если Клиент должен автоматически перенаправляться обратно в ЭМ. В этом случае ожидается, что ЭМ самостоятельно отобразит результаты проведения Платежа.

Логика оповещения и возврата Клиента описана в разделе «Оповещение ЭМ о результате платежа и возврат Клиента на сайт ЭМ».
Если ЭМ не выполняет шаг 9 в течение обозначенного времени (12 часов), Платеж автоматически отменяется, и резервирование денежных средств на Карте Клиента снимается.

Платеж с криптограммой

Если для ЭМ включена возможность работы с криптограммами, то вместо перенаправления пользователя на сайт Сервиса в однофазном и двухфазном платежах выполняется:

1. Клиент вводит данные карты на странице ЭМ и формируется криптограмма
2. Криптограмма передается в ЭМ на время проведения платежа
3. ЭМ вызывает в Сервисе операцию ProcessPayment, в том числе передав криптограмму
4. При необходимости, Клиент направляется на страницу 3-D Secure аутентификации, и после возврата пользователя повторно вызывается ProcessPayment
5. Средства списываются (1Ф платеж) или резервируются (2Ф платеж)

Статусы Платежа

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

Однофазный платеж

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

• preauthorized (0) - Платеж успешно инициирован ЭМом в Сервисе. Ожидается ввод реквизитов Карты и авторизация Платежа Клиентом.
• inprogress (4) - Платеж находится в обработке.
• completed (2) - Платеж успешно завершен.
• canceled (3) - Платеж отменен.
• declined (5) - Платеж отвергнут Сервисом или платежной системой.
• partially refunded* (6) - По платежу выполнен частичный возврат средств

Для статуса  canceled (3) могут быть следующие детализирующие коды:

401 - Платеж отменен, т.к. Клиент не авторизовал его в течение одного (1) часа после создания;
402 - Платеж отменен, т.к. ЭМ не подтвердил его в течение двенадцати (12) часов после успешного резервирования денежных (только для двухфазных платежей);
403 - Платеж явно отменен Клиентом (т.е. Клиент нажал кнопку отмены на сайте ввода реквизитов);
404 - Платеж отменен ЭМом;
405 - Платеж отменен тех. поддержкой Компании.

*Для статуса  partially refunded (6) могут быть следующие детализирующие коды:

404 - Платеж отменен ЭМом;
405 - Платеж отменен тех. поддержкой Компании.

Для статуса  declined могут быть следующие детализирующие коды:

1 - при обработке Платежа возник внутренний сбой в Сервисе;
101 - Клиент ошибся критическое число раз при вводе данных;
210 - в обработке операции по указанным платежным реквизитам отказано;
220 - операции по указанным платежным реквизитам временно запрещены;
303 - недостаточно средств;
304 - неверный код CVC2/CVV2;
307 - карта просрочена;
309 - отклонено платежной системой;
310 - техническая ошибка взаимодействия с платежной системой;
311 - карта не найдена;
312 - ошибка 3-D Secure;
313 - превышен лимит суммы операций по карте;
314 - превышен лимит активности использования карты;

Рис. 1 иллюстрирует логику изменения статуса у однофазного платежа.

Рис. 1 Изменение статуса однофазного платежа

В случае если ЭМ инициирует Платеж, а Клиент по какой-либо причине не авторизует Платеж и не отменит его (например, просто закроет браузер), Платеж останется в состоянии  preauthorized.

При необходимости ЭМ может снова перенаправить Клиента для проведения этого Платежа (если прошло менее одного (1) часа), либо инициировать новый платеж.

*Если платёж имеет статус  completed (2), можно выполнить отмену платежа или возврат средств, полный или частичный. При полном возврате средств платёж перейдет в статус  canceled (3), при частичном в  partially refunded (6).

*Если платеж имеет статус  partially refunded (6), можно выполнить частичный возврат на сумму не превышающую разницу между суммой платежа и суммой ранее совершенных частичных возвратов. Если сумма частичных возвратов сравняется с суммой платежа,

тогда платеж перейдет в статус  canceled (3).

Двухфазный платеж

У двухфазного платежа множество статусов, в котором он может находиться, расширено одним дополнительным:
authorized (1) - денежные средства на Карте Клиента успешно зарезервированы, Платеж ожидает подтверждения со стороны ЭМ.
Для статуса  authorized могут быть следующие детализирующие коды (см. описание изменения статусов ниже):
1 - при обработке Платежа возник внутренний сбой в Сервисе;
210 - операция отвергнута платежной системой;
309 - техническая ошибка взаимодействия с платежной системой.

Рис. 2 иллюстрирует логику изменения статуса у двухфазного платежа.

Рис. 2 Изменение статуса двухфазного платежа

После авторизации Платежа Клиентом происходит резервирование денежных средств (Платеж находится в статусе inprogress) и в случае успешного резервирования принимает статус  authorized.

Если резервирование прошло неуспешно, то Платеж принимает статус  cancel или  declined.

В статусе  authorized Платеж ожидает подтверждения или отмены от ЭМ. В случае отмены он принимает статус canceled. Иначе происходит запрос на списание денежных средств (Платеж находится в это время опять в статусе  inprogress).

Если списание проходит успешно, то он принимает статус  completed. Если списание проходит неуспешно, то Платеж опять принимает статус  authorized. В данном случае причиной неуспешного списания может быть только технический сбой (причину определяет детализирующий код). Поэтому ЭМ может попробовать довести Платеж повторно.

В случае неуспешных повторений следует обратиться в техническую поддержку Компании (email: support@mobi-money.ru) и обработать данный платеж в частном порядке.

*Если платёж имеет статус  completed (2), можно выполнить отмену платежа или возврат средств, полный или частичный. При полном возврате средств платёж перейдет в статус canceled (3), при частичном в  partially refunded (6).

*Если платеж имеет статус  partially refunded (6), можно выполнить частичный возврат на сумму не превышающую разницу между суммой платежа и суммой ранее совершенных частичных возвратов. Если сумма частичных возвратов сравняется с суммой платежа,

тогда платеж перейдет в статус  canceled (3).

Отмена Платежа

Если для ЭМ отключена возможность самостоятельно выполнять отмены и возвраты, то в случае возникновения необходимости отменить один или несколько проведенных Платежей надо обратиться в Службу технической поддержки Компании (email: support@mobi-money.ru) с предоставлением Поручения о возврате средств, согласно агентскому договору.

Формирование криптограммы

Для формирования криптограммы должен использоваться специальный скрипт с сайта Сервиса, ссылка на скрипт выдается ЭМ.

Скрипт указывается на странице вашего сайта, и с помощью него формируется криптограмма алгоритмом RSA.

Криптограмма передается по защищенному каналу (SSL) на сервер ЭМ, затем передается в Сервис, в запросе ProcessPayment.

ВНИМАНИЕ: взаимодействие с Сервисом со страницы ЭМ напрямую недопустимо!

Требования к форме ввода данных:

1. У полей с карточными данными не должно быть атрибута "name", чтобы данные не попали на сервер при отправке формы.

1. Данные из формы должны передаваться по SSL с корректным сертификатом

Требования к криптограмме:

1. Должна формироваться оригинальным скриптом, загруженным с Сервиса

1. Криптограмму нельзя хранить после оплаты и использовать повторно

Требования к безопасности по PCI DSS:

С точки зрения PCI DSS, подобный способ подключения классифицируется как "E-commerce merchants who outsource all payment processing to PCI DSS validated third parties, and who have a website(s) that doesn't directly receive cardholder data but that can impact the security of the payment transaction. No electronic storage, processing, or transmission of any cardholder data on the merchant's systems or premises.", то есть обработка платежных данных выполняется третьей стороной, но сайт влияет на безопасность карточных данных.

Для соблюдения требований стандарта, необходимо заполнять лист самооценки  SAQ-EP и ежеквартально проходить ASV тестирование.

Сканирование должно проводится аккредитованным вендором (ASV) из  списка, представленного на сайте совета PCI.

Пример формы:

Поля с данными карты должны быть помечены следующими атрибутами:

• data-mm="cardNumber" - поле с номером карты
• data-mm="expDateMonthYear" - поле со сроком действия в формате MMYY
• data-mm="expDateMonth" - поле с месяцем срока действия
• data-mm="expDateYear" - поле с годом срока действия
• data-mm="cvv" - поле с кодом CVV
• data-mm="name" - поле с именем держателя карты

Пример скрипта по созданию криптограммы:

Полный пример страницы приведен в Приложении № 3

Протокол взаимодействия

ЭМ взаимодействует с Сервисом по HTTPS. Вызов операции представляет собой HTTP-POST запрос, в котором в параметре OPERATION передается название операции, а в других параметрах запроса передаются url encoded параметры операции. Все значения параметров должны быть в кодировке UTF-8.

В ответ на этот вызов Сервис возвращает HTTP ответ с кодом 200 в теле, которого указываются результаты операции как

<имя1>=<значение1>&<имя2>=<значение2>&...

Все значения возвращаются url encoded в кодировке UTF-8.

Пример успешного ответа на операцию  CreateTransaction:

RESULT=0&STATUS=0&SDCODE=-1&PAY_LINK=http%3A%2F%2Fwww.mobimoney.ru%3 FPAY_ID%3D123456%26SIG%3D3cb32e05315c4792b75448cefd158a3a&SIG=3cb32e05315c4792b75448cefd158a3a&PAY_ID=123456

В каждом вызове операции Сервиса присутствует входной параметр IDENTITY или HASH, который удостоверяет сторону делающую вызов. Значение IDENTITY ЭМ должен вычислить, используя хеш-функцию md5 для строки, состоящей из следующих значений: ID_TERMINAL, LOGIN, PASSWD. Значения должны быть склеены без всяких разделяющих символов. Т.е. если номер ЭМ 233, его логин «goodshop», а пароль «3xe45OQ», то хеш необходимо вычислить от следующей строки:

233goodshop3xe45OQ

Он будет равен

f88182579ad3372015780385beef5753

Вычисление HASH описано в разделах соответствующих операций (ReversalPayment, RefundPayment)

ЭМ должен адекватно реагировать (сохранять работоспособность) при получении «неожиданных» параметров в ответах и неизвестных ему кодов ошибок. Неизвестные ЭМ параметры нужно игнорировать, неизвестные коды ошибок интерпретировать как неизвестную ошибку.

Для проведения тестовых платежей запросы необходимо отправлять по адресу:

Тестовый адрес: ???

Тестовые платежные реквизиты и получаемые результаты указаны в Приложении №2.

Примечание: с Сервисом обязательно взаимодействует ЭМ, а не пользователь через браузер.

Операция CreatePayment

Операция  CreatePayment создает платеж.  CreatePayment должна быть выполнена перед перенаправлением Клиента на платежную страницу Сервиса.

С точки зрения Сервиса платеж ЭМ определяется параметром MPAY_ID.

В штатных ситуациях для каждого платежа в ЭМ должен быть выполнен один вызов  CreatePayment. В случае если Платеж не завершился по той или иной причине, допустимо инициировать новый Платеж с таким же значением MPAY_ID.

ВНИМАНИЕ: между инициацией Платежа и авторизацией Платежа Клиентом на стороне Сервиса должно пройти не более одного (1) часа. Иначе созданный Платеж считается устаревшим и отменяется автоматически.

Входные параметры:

«YYYY-MM-DDThh:mm:ss[±hhmm]»

Кроме перечисленных выше параметров запрос может содержать любые другие параметры, которые будут присутствовать в оповещении ТСП о результатах платежа и в запросе на перенаправление Клиента обратно на сайт ТСП.

Максимальная суммарная длина таких параметров, включая их имена, значения, знаки «=» и «&» не должна превышать 512 символов.

Результат:

Если операция вернула результат RESULT=106, т.е. Платеж либо проведен, либо находится в обработке, - в параметрах PAY_ID, STATUS и SDCODE возвращаются ее идентификатор, статус и детализирующий код соответственно.

При формировании ссылки для направления Клиента на страницу оплаты вручную, - необходимо убедиться, что в ней указаны параметры PAY_ID и SIG, которые были возвращены в результате выполнения операции  CreatePayment.

Если Платеж оказался неуспешным (отменен или отвергнут), либо Клиент не авторизовал Платеж и не отменил его явно, - ЭМ может инициировать новый Платеж с таким же MPAY_ID как и предыдущий и перенаправить Клиента на форму оплаты для новой попытки.

Если Платеж оказался успешным (статус  completed), либо находится в обработке (статус  inprogress), либо ожидает подтверждения от ЭМ (статус  authorized), то на вызов  CreatePayment с таким же MPAY_ID, вернется ошибка RESULT=106.

Операция InitRecurrent

Операция  InitRecurrent создает и проводит платеж без перенаправления клиента на платежную страницу сервиса. У клиента запрашивается подтверждение на проведение платежа в большинстве случаев.

С точки зрения Сервиса платеж ЭМ определяется параметром MPAY_ID.

В штатных ситуациях для каждого платежа в ЭМ должен быть выполнен один вызов  InitRecurrent. В случае если Платеж не завершился по той или иной причине, допустимо инициировать новый Платеж с таким же значением MPAY_ID.

ВНИМАНИЕ: между инициацией Платежа и подтверждением платежа пользователем должно пройти не более одного (1) часа. Иначе созданный Платеж считается устаревшим и отменяется автоматически.

Входные параметры:

«YYYY-MM-DDThh:mm:ss[±hhmm]»

Кроме перечисленных выше параметров запрос может содержать любые другие параметры, которые будут присутствовать в оповещении ТСП о результатах.

Максимальная суммарная длина таких параметров, включая их имена, значения, знаки «=» и «&» не должна превышать 512 символов.

Результат:

Если операция вернула результат RESULT=106, т.е. Платеж либо проведен, либо находится в обработке, - в параметрах PAY_ID, STATUS и SDCODE возвращаются ее идентификатор, статус и детализирующий код соответственно.

Если Платеж оказался неуспешным (отменен или отвергнут), либо Клиент не авторизовал Платеж и не отменил его явно, - ЭМ может инициировать новый Платеж с таким же MPAY_ID.

Если Платеж оказался успешным (статус  completed), либо находится в обработке (статус  inprogress), либо ожидает подтверждения от ЭМ (статус  authorized), то на вызов  CreatePayment с таким же MPAY_ID, вернется ошибка RESULT=106.

Операция ProcessPayment

Операция ProcessPayment для проведения ранее созданного платежа (см. CreatePayment) с использованием криптограммы или Apple Payment Token, без перенаправления клиента на страницу Сервиса.

Входные параметры:

{"paymentData":{"version":"EC_v1", ...... }

Если указана привязанная карта (CARD_ID), то в криптограмме необходимо зашифровать только CVV код (см. "Формирование криптограммы"), остальные данные на форме не вводятся.

Если платеж создан с помощью CheckCard, то CARD_ID нужно указывать обязательно, если с помощью LinkCard, то параметр CARD_ID должен отсутствовать.

AP_TOKEN можно использовать только для платежей созданных с помощью CreatePayment.

ВНИМАНИЕ: для возможности оплаты через Apple Pay, ЭМ должен передать публичный сертификат и приватный ключ, чтобы данные могли быть расшифрованы на стороне Сервиса. Передавать сертификаты/ключи необходимо по защищенным каналам связи по согласованию с менеджером и службой безопасности.

Результат:

ВНИМАНИЕ: при получении кода "21" следует ожидать нотификации от Системы или самостоятельно опрашивать состояние платежа (GetPaymentStatus), до тех пор, пока статус платежа не сменится с 4 (в процессе) на другой. Статус необходимо опрашивать не чаще чем раз в 5 минут, и не более 3 часов. Если после 3-х часов статус платежа не изменится, рекомендуется обратиться в поддержку.

Работа с 3-D Secure аутентификацией

Если в ответе на ProcessPayment получен RESULT=20, то плательщика необходимо направить на адрес указанный в ACSURL и передать следующие параметры:

• TermUrl - адрес на сайте ЭМ для возврата плательщика после 3-D Secure аутентификации
• PaReq - параметр PAREQ полученный в ответе на ProcessPayment
• MD - параметр MD полученный в ответе на ProcessPayment, либо своё значение, которое потом вернется

ВНИМАНИЕ: названия параметров чувствительны к регистру

Пример:

После проверки, плательщик будет возвращен по адресу TermUrl с параметрами PaRes и MD, переданными методом POST.

Для завершения оплаты необходимо повторно вызвать ProcessPayment передав параметры PaRes и MD.

ВНИМАНИЕ: оповещения ЭМ о результате платеже после данной операции не будет, т.к. все необходимые данные переданы в ответе. При необходимости, можно вызвать GetPaymentStatus.

Оповещение ЭМ о результате платежа и возврат Клиента на сайт ЭМ

Внимание! При перенаправлении Клиента обратно на сайт ЭМ результат Платежа не передается. Это сделано для исключения возможного мошенничества с подменой результатов. Для определения результата Платежа ЭМ должен ориентироваться на автоматическое оповещение, либо самостоятельно запросить статус (операция  GetPaymentStatus).

Автоматическое оповещение является простым HTTP запросом, в котором передаются результаты методом POST. В ответ на этот запрос ЭМ может выдать HTTP ответ с кодом 200 или 202 без содержания странички.

Автоматическое оповещение о результатах Платежа происходит только для тех ЭМ, которые указали при регистрации адрес обратной связи. Для оповещения об успешном Платеже или успешном резервировании денежных средств используется адрес CALLBACK_URL, указываемый ТСП при регистрации (см. раздел «Регистрация»). Если Платеж неуспешен, используется адрес CALLBACK_FAIL_URL, а если он не указан, то CALLBACK_URL. Если автоматическое оповещение не используется магазином, ЭМ должен самостоятельно запросить у Сервиса результат Платежа, используя операцию GetPaymentStatus.

После оповещения ЭМ Сервис переадресовывает Клиента обратно на сайт ЭМ. В случае если Платеж прошел успешно, либо резервирование прошло успешно Клиент перенаправляется по адресу RETURN_URL. В случае если Платеж неуспешен, перенаправление производится на адрес, указанный в FAIL_URL, а если он не указан, то RETURN_URL.

Если ЭМ не указал в Платеже значения для параметра RETURN_URL, после успешного завершения Платежа Клиент перенаправляется на сайт ЭМ по адресу, указанному в DEF_RETURN_URL. Если Платеж завершился неуспешно, то используется адрес DEF_FAIL_URL.

После проведения Платежа Клиенту отображается страница с результатом и кнопкой возврата в ЭМ. По желанию ТСП для ЭМ можно отключить отображение страницы с результатом. Тогда Клиент будет перенаправлен на сайт ЭМ сразу после проведения Платежа. В этом случае ожидается, что ЭМ самостоятельно отобразит результаты проведения Платежа.

ВНИМАНИЕ: в некоторых случаях возможна ситуация, когда Клиент вёрнется на сайт ЭМ, а платёж при этом останется в статусе 4 (в процессе) и магазину не будет отправлено оповещение. В таком случае, следует ожидать нотификации от Системы или самостоятельно опрашивать состояние платежа (GetPaymentStatus), до тех пор, пока статус платежа не сменится с 4 (в процессе) на другой. Статус необходимо опрашивать не чаще чем раз в 5 минут, и не более 3-х часов. Если после 3-х часов статус платежа не изменится, рекомендуется обратиться в поддержку.

В запросе автоматического оповещения в ЭМ приходят следующие параметры:

Результаты проведения Платежа, которые передаются в оповещении, подписываются Сервисом для обеспечения должного уровня безопасности.  ЭМ настоятельно рекомендуется проверять подпись сразу после получения оповещения.

Подпись передается в параметре HASH и является результатом вычисления хеш-функции md5 от следующей строки (порядок параметров важен):

PAY_ID=<payid>&MPAY_ID=<mpayid>&DATETIME=<datetime>&STATUS=<status>&AMOUNT=<amount>&CURRENCY=<currency>&LOGIN=<login>&PASSWD=<password>

Для проверки подписи ЭМ должен составить из полученных в оповещении значений, а также известного только ему и Сервису логина и пароля подобную строку и вычислить ее хеш используя функцию md5. После чего сравнить полученное значение с тем, что пришло в параметре HASH. Если значения совпадают, то проверка успешна. Если значения отличны, то проверка не пройдена, Платеж необходимо отменить и сотрудники ТСП должны незамедлительно обратиться в Службу информационной безопасности Компании: телефон: +7 960 270 50 42, e-mail: isecurity@1mps.ru.

При перенаправлении Клиента обратно на сайт ЭМ передаются следующие параметры:

Операция GetPaymentStatus

Позволяет получить статус Платежа.

Входные параметры:

Результат:

Операция ConfirmPayment

В случае инициации двухфазного платежа (т.е. в операции  CreatePayment значение  PTYPE=2) после успешного резервирования денежных средств Платеж ожидает подтверждения, либо отмены со стороны ЭМ. Операция  ConfirmPayment подтверждает Платеж и списывает ранее зарезервированные денежные средства с банковской карты Клиента. Операцию  ConfirmPayment для Платежа необходимо выполнить не позднее чем через двенадцать (12) часов после успешного резервирования денежных средств. Иначе резервирование будет снято, а Платеж отменен по таймауту.

Входные параметры:

Результат:

ВНИМАНИЕ: при получении кода "21" следует ожидать нотификации от Системы или самостоятельно опрашивать состояние платежа (GetPaymentStatus), до тех пор, пока статус платежа не сменится с 4 (в процессе) на другой. Статус необходимо опрашивать не чаще чем раз в 5 минут, и не более 3 часов. Если после 3-х часов статус платежа не изменится, рекомендуется обратиться в поддержку.

Операция CancelPayment

В случае инициации двухфазного платежа (т.е. в операции  CreatePayment значение  PTYPE=2) после успешного резервирования денежных средств Платеж ожидает подтверждения, либо отмены со стороны ЭМ.

Операция  CancelPayment отменяет Платеж и снимает резервирование денежных средств на банковской карте Клиента.

Входные параметры:

Результат:

Операция ReversalPayment *

Отмена платежа в статусе  completed (2), если по данному платежу невозможно сделать отмену, будет возвращен RESULT=112. В таком случае можно воспользоваться операцией по возврату средств RefundPayment.

Входные параметры:

Значение HASH является результатом вычисления хеш-функции md5 от следующей строки (порядок параметров важен):

OPERATION=ReversalPayment&TERMINAL_ID=<terminalid>&PAY_ID=<payid>&LOGIN=<login>&PASSWD=<password>

<terminalid> - идентификатор ЭМ из запроса

<payid> - идентификатор платежа из запроса

<login> - логин ЭМ

<password> - пароль ЭМ

Результат:

Операция RefundPayment *

Полный или частичный возврат средств. Данную операцию можно выполнить если платеж находится в статусе  completed (2) или  partially refunded (6).

Входные параметры:

Значение HASH является результатом вычисления хеш-функции md5 от следующей строки (порядок параметров важен):

OPERATION=RefundPayment&TERMINAL_ID=<terminalid>&PAY_ID=<payid>&REFUND_AMOUNT=<refundamount>&LOGIN=<login>&PASSWD=<password>

<terminalid> - идентификатор ЭМ из запроса

<payid> - идентификатор платежа из запроса

<refundamount> - сумма возврата из запроса

<login> - логин ЭМ

<password> - пароль ЭМ

Результат:

Операция LinkCard

Запрос адреса страницы для привязки новой банковской карты к номеру телефона.

Привязка карты производится за счет холдирования небольшой случайной суммы (обычно от 1 до 10 рублей) на карте клиента и последующего автоматического возврата. Для контроля процесса привязки, ЭМ в ответе получает PAY_ID. Который затем будет использоваться в нотификации ЭМ о результате платежа, или ЭМ сам может проверить статус с помощью GetPaymentStatus.

В случае успеха, ЭМ привязывает карту с помощью SendLinkCode + ConfirmLinkCode.

Операция доступна для ЭМ, для которых включен функционал работы с привязанными картами.

Параметры запроса:

Кроме перечисленных выше параметров запрос может содержать любые другие параметры, которые будут присутствовать в оповещении ТСП о результатах.

Максимальная суммарная длина таких параметров, включая их имена, значения, знаки «=» и «&» не должна превышать 512 символов.

Параметры ответа:

Операция CheckCard

Запрос адреса страницы для проверки ранее привязанной банковской карты.

Проверка карты производится за счет холдирования небольшой случайной суммы (обычно от 1 до 10 рублей) на карте клиента и последующего автоматического возврата. Для контроля процесса проверки, ЭМ в ответе получает PAY_ID. Который затем будет использоваться в нотификации ЭМ о результате платежа, или ЭМ сам может проверить статус с помощью GetPaymentStatus.

Операция доступна для ЭМ, для которых включен функционал работы с привязанными картами.

Параметры запроса:

Кроме перечисленных выше параметров запрос может содержать любые другие параметры, которые будут присутствовать в оповещении ТСП о результатах.

Максимальная суммарная длина таких параметров, включая их имена, значения, знаки «=» и «&» не должна превышать 512 символов.

Параметры ответа:

Операция UnlinkCard

Удаление привязки банковской карты к телефону.

Операция доступна для ЭМ, для которых включен функционал работы с привязанными картами.

Параметры запроса:

Параметры ответа:

Операция GetLinkedCards

Возвращает список банковских карт привязанных к указанному номеру телефона.

Операция доступна для ЭМ, для которых включен функционал работы с привязанными картами.

Параметры запроса:

Параметры ответа:

[{"name":"mama","pan":"**** **** **** 1234",


"card_id":123456,"cardtype":"VISA",


"cardhash":"51fad05a838b1fe8375a26ca2f12932b6debaccd"},


{"name":"papa","pan":"**** **** **** 1245",


"card_id":123457,"cardtype":"VISA",


"cardhash":"739d43bda8435f03b4bf23104aded07cd39df23e"}]

Операция SendLinkCode

Формирует и отправляет случайный пароль клиенту, по которому будет производиться привязка карты в ConfirmLinkCode. Номер телефона определяется по проведенной транзакции (PAY_ID), транзакция должна быть успешно завершена с использованием 3d-secure.

Операция доступна для ЭМ, для которых включен функционал работы с привязанными картами.

Параметры запроса:

Параметры ответа:

Операция ConfirmLinkCode

Подтверждение привязки. Передается код, который ввел клиент (см. SendLinkCode), если проверка кода пройдет, то карта будет привязана данному клиенту. Номер телефона определяется по проведенной транзакции (PAY_ID), транзакция должна быть успешно завершена с использованием 3d-secure.

Операция доступна для ЭМ, для которых включен функционал работы с привязанными картами.

Параметры запроса:

Параметры ответа:

[{"payer_phone":"79998887766","card_id":123456},
{"payer_phone":"79998887767","card_id":123457}]

Приложение № 1

Перечень товаров/услуг, оплачиваемых через ЭМ ТСП с использованием банковских карт

Приложение № 2

*Перечень реквизитов платежа и соответствующие им ошибки и статусы платежа
Обозначения:*

XXX% - значение атрибута начинается с «XXX»

• * - любое значение атрибута
• > - значение числового атрибута больше чем указанное значение
• < - значение числового атрибута меньше чем указанное значение

Успешные платежи:

Ошибки, получаемые клиентом при оплате товара:

Ошибки, приводящие к отрицательному результату оплаты товара:

Ошибки, происходящие при подтверждении 2-х фазного платежа, в зависимости от платежных реквизитов, указанных клиентом:

OPERATION

Строка

Операция, которая инициировала данный платеж: CreatePayment, InitRecurrent, LinkCard, CheckCard.
Присутствует для ЭМ, которые поддерживают версию интернет-эквайринга 3 или выше.
Присутствует, если найден платеж.

STATUS

Число (int)

Статус Платежа (см. раздел «Статусы Платежа»).
Присутствует, если RESULT=0.

SDCODE

Число (int)

Код, детализирующий статус Платежа (см. раздел «Статусы Платежа») или «-1», если детализации нет.
Присутствует всегда, когда указан статус.

PAY_ID

Число (long)

Уникальный идентификатор платежа в системе учета Сервиса (равен переданному на вход).
Присутствует, если RESULT=0.

MPAY_ID

Строка, длиной до 150 символов

Идентификатор Платежа в системе учета ЭМ.
Присутствует если его указали при инициализации платежа, т.к. является необязательным параметром для LinkCard, CheckCard.
Присутствует для ЭМ, которые поддерживают версию интернет-эквайринга 3 или выше.

DATETIME

Дата в формате «YYYY-MM-DDThh:mm:ss±hhmm»

Время создания платежа в системе учета Сервиса. Например: «2011-01-31T13:48:22+0300»
Присутствует, если RESULT=0.

AMOUNT

Целое (int)

Сумма платежа в копейках.
Присутствует, если RESULT=0.

CURRENCY

Константа

«RUR»
Присутствует, если RESULT=0.

ACNUMBER

Строка, длиной до 20 символов

Маскированный номер карты, с которой Клиент произвел оплату.
Например, « ** **** **** 1234».
Присутствует, если RESULT=0 и Платеж успешно проведен, либо зарезервирован.

CARDTYPE

Строка, длиной до 10 символов

Тип банковской карты, с которой произведена оплата («VISA», «MASTERCARD», «JCB», «DCL»)
Присутствует, если RESULT=0 и Платеж успешно проведен, либо зарезервирован.

PAYER_PHONE

11 цифр

Номер телефона плательщика, включая код страны - 11 цифр. Например: 79998887766
Если ЭМ не передал номер телефона в CreatePayment, LinkCard, CheckCard, то будет передано значение, которое ввёл клиент.
Присутствует для ЭМ, для которых включен функционал работы с привязанными картами и которые поддерживают версию интернет-эквайринга 3 или выше.

PTYPE

Число («1», «2» или «3»)

Тип платежа:
«1» - однофазный платеж;
«2» - двухфазный платеж;
«3» - тестовый платеж (LinkCard или CheckCard)
Присутствует для ЭМ, которые поддерживают версию интернет-эквайринга 3 или выше.

CARD_ID

Целое (long)

Идентификатор карты, который можно использовать в CreatePayment, InitRecurrent, UnlinkCard.
Присутствует если платеж был сделан с привязанной карты, либо идентификатор привязываемой карты через LinkCard.

CARD_NAME

Строка

Имя карты.
Присутствует если платеж был сделан с привязанной карты и имя карты не пустое.

RETURN_URL

Строка

Адрес возврата Клиента на сайт ЭМ, переданный в CreatePayment, LinkCard, CheckCard.
Присутствует для ЭМ, которые поддерживают версию интернет-эквайринга 3 или выше.

FAIL_URL

Строка

Адрес возврата Клиента на сайт ЭМ в случае неуспешного платежа, переданный в CreatePayment, LinkCard, CheckCard.
Присутствует для ЭМ, которые поддерживают версию интернет-эквайринга 3 или выше.

3DS

Число («0» или «1»)

Признак аутентификации 3DS:
«0» - платеж без 3DS
«1» - платеж с 3DS

AUTHCODE

Строка, длиной до 8 символов

Авторизационный код транзакции.
Присутствует, если RESULT=0, Платеж успешно проведен, либо зарезервирован, и код был выдан платежной системой.

HASH

Строка, длиной 32 символа

Подпись результата. Формируется аналогичным образом, как и в оповещении. Детальное описание см. в разделе «Оповещение ЭМ о результате платежа и возврат Клиента на сайт ЭМ».
Присутствует, если RESULT=0.

Другие параметры

Приложение № 3 - пример страницы работающей с криптограммой