Товары, услуги, бизнес

Регламент взаимодействия

с Поставщиками услуг

Версия 11

Ростов-на-Дону

2010г.

Лист контроля версий

ОГЛАВЛЕНИЕ

Регламент взаимодействия с отложенным уведомлением о поступивших платежах

Общие положения

Оператор по Договору - Платежная система «Кампэй», отправляет Поставщику услуг, далее по тексту Поставщику, информацию о поступивших платежах в электронном виде.

Формат документов, способ доставки, периодичность доставки, и, если требуется, шифрование документов оговариваются сторонами.

Формат документов

Минимальный набор реквизитов документа

a) Номер п/п (целое число, максимальное значение 2147483648);

b) Идентификатор плательщика (строка, максимальная длина 12000 символов);

c) Дата платежа (дата в согласованном формате, стандартно YYYYMMDDHHMMSS);

d) Сумма для зачисления на счет абонента (десятичное число с разделителем, формат 19.4);

e) Номер транзакции у Оператора (целое число, максимальное значение 9223372036854775808)

Формат документа

a) CSV, текстовый файл с согласованным сторонами разделителем

b) DBF (по формату согласованному с Поставщиком)

Способ доставки

Доставка по FTP

Поставщик открывает у себя доступ на FTP-сервер, сообщает Оператору адрес, порт, логин, пароль, папку на сервере, куда будут пересылаться файлы с документами. Документ считается отправленным, если при взаимодействии с FTP сервером Поставщика отсутствовали ошибки.

Доставка по электронной почте

Поставщик сообщает Оператору адрес электронной почты, на который будут отправляться файлы с документами. Документ считается отправленным, если при взаимодействии и SMTP сервером Оператора отсутствовали ошибки.

Периодичность доставки

Периодичность доставки может быть любой, но не чаще 1 раза в 15 минут. Так же доставка может осуществляться по расписаниям, например: 10:00 в Пн., Ср., Пт.

Шифрование документов

Для шифрования документов Поставщик должен предоставить Оператору свой открытый ключ PGP (для реализации используется версия PGP GnuPG)

Регламент взаимодействия с непосредственным уведомлением о поступивших платежах

Требования к Поставщику

Требования к протоколу сервера

Для реализации данного способа взаимодействия Поставщик должен у себя организовать прием входящих транзакций по протоколу HTTP или HTTPS.

Требования к методу взаимодействия

Интерфейс должен обрабатывать запросы методом GET. Исключением является запрос на выгрузку списка платежей для сверки (п. 2.7.1), который обрабатывается методом POST

Требования к кодировке при обмене информацией

Ответ должен формироваться в кодировке UTF-8.

Требования к максимальному времени обработки

Время ответа не должно превышать 60 секунд.

Требования к многопоточной коммуникации

Интерфейс должен поддерживать несколько одновременных соединений. Количество соединений зависит от интенсивности поступления платежей.

Требования к обеспечению дополнительной безопасности

Шифрование строки запроса

Может быть обеспечена дополнительная безопасность при обмене данными, путем шифрования запроса и ответа. Шифрование происходит с использование PGP.

Строка запроса, в данном случае, выглядит следующим образом:

...?pgp_data=<PGP encrypted block>

где <PGP encrypted block>, это строка запроса, описанная ниже (например: operation=payment&
id_payment=987654321&account=1234567890&sum=12.34&date=20070918155052), зашифрованная при помощи открытого ключа Поставщика, сконвертированная в Base64 и обработанная согласно требованиям по маскировке специальных символов в URL.

Ответ, соответственно, должен представлять собой полный XML-пакет, аналогичный следующему:

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>check</operation>

<account>1234567890</account>

<result>0</result>

</response>

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

<?xml version=”1.0” encoding=”utf-8” ?>

<pgp_data>

<PGP encrypted block encoded in Base64>

</pgp_data>

где <PGP encrypted block encoded in Base64> - зашифрованные данные в кодировке Base64

Хеширование строки запроса

Так же может быть использован способ хеширования строки запроса. К строке запроса, например:

operation=check&account=1234567890&service=1

добавляется параметр secret=<согласованное значение>, после чего вся строка, например:

operation=check&account=1234567890&service=1&secret=1234567890

хешируется методом sha1 или md5, после чего у исходно строке добавляется парметр sha1=<значение хеша в виде 16-ричной строки> или md5=<значение хеша в виде 16-ричной строки>, и запрос отправляется в виде

operation=check&account=1234567890&service=1&md5=52646422FB9F0A6BE662368EFFDDF5B6

Основные принципы

Уникальный номер транзакции Оператора

Каждый платеж у Оператора имеет уникальный номер транзакции, который передается Поставщику в параметре id_payment, тип – целое число, максимальное значение 9223372036854775808. По этому номеру производится сверка взаиморасчетов и решение спорных вопросов.

В базе Поставщика не должно содержаться записей с одинаковыми id_payment. Если Оператор пришлет запрос с id_payment, который уже есть в базе Поставщика, Поставщик должен вернуть соответствующую ошибку.

Сумма платежа

Сумма платежа передается Поставщику в рублях в параметре sum – десятичное число, точность – до десятитысячных, разделитель – «.» (точка).

Дата платежа

В запросе на добавление платежа, Оператор передает дату платежа (под датой платежа в системе подразумевается дата получения запроса сервером) в переменной date – дата в формате YYYYMMDDHHMMSS. Эту дату необходимо использовать для проведения сверок и бухгалтерских взаиморасчетов. Так как у Оператора учет платежей ведется по дате получения запроса от клиента, то и расчеты с Поставщиком необходимо вести по этой дате. Например ситуация: клиент прислал Оператору запрос 31.12.2005 в 23:59:59, учитывая задержку на обработку данных и пересылку информации по каналам связи, Оператор смог отправить запрос Поставщику 1.1.2006 00:00:05, соответственно платеж будет учтен в системе Поставщика в другом отчетном периоде, что вызовет некоторые проблемы при проведении сверок. Чтобы избежать такой ситуации Оператор передает Поставщику дату, в которой нужно учитывать платеж.

Идентификатор абонента

Поставщик идентифицирует своего абонента по уникальному идентификатору (номер лицевого счета, телефона, логин и т.д.). Перед отправкой Поставщику, идентификатор проходит проверку корректности в соответствии с регулярным выражением, которое должен предоставить Поставщик. Идентификатор абонента передается в переменной account – строка, содержащая буквы, цифры и спецсимволы, длиной до 1200 символов. Поставщик должен учитывать особенности работы с терминалами самообслуживания и допускать прием данного идентификатора в любом регистре.

Этапы взаимодействия

Оплата услуг Поставщика производится системой в 2 этапа – проверка состояния абонента и непосредственно проведение платежа. Тип запроса передается Оператору в переменной operation – строка, принимающая значения «check» и «payment».

Проверка

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

При проверке статуса, в строке запроса может отсутствовать сумма платежа, или сумма может быть равна 0. В таком случае необходимо проверить только внутренние проверки идентификатора.

Дополнительно, на этапе проверки, Поставщик может вернуть расширенную информацию об абоненте, которую можно вывести на экран терминала.

Проведение

При проведении платежа Поставщик должен произвести пополнение баланса абонента.

Тестовая номерная емкость

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

Операции, совершаемые по данным идентификаторам, должны игнорироваться при сверке данных по платежам и взаиморасчетах.

Обработка ошибок

Если любой из запросов Поставщику завершается ошибкой, то Поставщик возвращает код ошибки в соответствии с таблицей приведенной ниже. Все ошибки имеют признак фатальности. Фатальная ошибка означает для системы, что повторная отправка запроса с теми же параметрами, приведет к 100% повторению той же ошибки – следовательно, система прекращает обработку клиентского запроса и завершает его с ошибкой. Не фатальная ошибка – означает для системы, что повторение запроса с теми же параметрами через некоторый промежуток времени, возможно, приведет к успеху. Система будет повторять запросы, завершающиеся не фатальной ошибкой, постоянно увеличивая интервал, пока операция не завершится успехом или фатальной ошибкой или пока не истечет срок жизни клиентского запроса – 2000 попыток. Отсутствие связи с сервером Поставщика является не фатальной ошибкой.

Идентификация сервиса (типа услуги)

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

Например:

...?operation=check&account=1234567890&service=1

...?operation=check&account=1234567890&service=internet

...?operation=check&account=1234567890&service=wifi

Формат запросов Оператора

Запрос на проверку без указания суммы платежа

Строка запроса

https://service.provider.ru/comepay?operation=check&account=1234567890

Данные запроса

operation=check – запрос на проверку платежа

account=1234567890 – номер, подлежащий проверке

Действия Поставщика

Поставщик должен проверить существует ли указанный абонент

Запрос на проверку с указание суммы платежа

Строка запроса

https://service.provider.ru/comepay?operation=check&account=1234567890&sum=12.34

Данные запроса

operation=check – запрос на проверку платежа

account=1234567890 – номер, подлежащий проверке

sum=12.34 – сумма, подлежащая проверке

Действия Поставщика

Поставщик должен проверить может ли абонент зачислить на свой счет указанную сумму.

Запрос на добавление платежа в базу Поставщика

Строка запроса

https://service.provider.ru/comepay?operation=payment&id_payment=987654321&account=1234567890&sum=12.34&date=20070918155052

Данные запроса

operation=payment – запрос на добавление платежа в базы Поставщика

id_payment=987654321 – номер транзакции у Оператора

account=1234567890 – номер, подлежащий добавлению

sum=12.34 – сумма, подлежащая добавлению

date=20070918155052 – дата принятия платежа сервером на обработку

Действия Поставщика

Поставщик должен произвести добавление платежа абонента на указанную сумму.

Форматы ответов Поставщика

В ответах Поставщика должны содержаться все поля запроса.

Т.е. на запрос:

https://service.provider.ru/comepay?operation=payment&id_payment=987654321&account=1234567890&sum=12.34&date=20070918155052&service=wifi

в ответе должны содержаться теги

<operation></operation>

<id_payment></id_payment>

<account></account>

<sum></sum>

<date></date>

<service></service>

с соответствующими значениями.

Это необходимо для контроля правильности обработки Поставщиком запросов в многопоточном режиме.

Положительный ответ на проверку номера

Текст ответа

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>check</operation>

<account>1234567890</account>

<result>0</result>

<services>

<service>

<type>wifi</type>

<description>Прием платежей за WiFi</description>

</service>

<service>

<type>phone</type>

<description>Прием платежей за телефон</description>

</service>

</services>

<ext-info>

<tag1>...</tag1>

<tag2>...</tag2>

...

<tagN>...</tagN>

</ext-info>

</response>

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>check</operation>

<account>1234567890</account>

<sum>12.34</sum>

<result>0</result>

</response>

Описание ответа

Т.о. <result>0</result>, означает, что абонент может совершить данную операцию.

Если у абонента имеется несколько доступных сервисов (п. 2.2.8) и в запросе не указано поле service, Поставщик должен вернуть в ответе список этих сервисов.

Отрицательный ответ на проверку номера с признаком фатальной ошибки

Текст ответа

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>check</operation>

<account>1234567890</account>

<sum>12.34</sum>

<result fatal=”true”>500</result>

</response>

Описание ответа

Данный ответ показывает, что номер абонента указан неверно, и дальнейшие запросы не имеют смысла, т.е. будет возвращен тот же код ошибки.

Отрицательный ответ на проверку номера без признака фатальной ошибки

Текст ответа

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>check</operation>

<account>1234567890</account>

<sum>12.34</sum>

<result fatal=”false”>599</result>

<ext-result>1</ext-result>

<ext-description>Описание ошибки Поставщика с кодом 1<ext-description>

</response>

Описание ответа

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

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

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>payment</operation>

<id_payment>987654321</id_payment>

<ext-id_payment>45612564567</ext-id_payment>

<date>20070918155052</date>

<account>1234567890</account>

<sum>12.34</sum>

<result>0</result>

</response>

Этот ответ показывает, что Поставщик успешно добавил в свою базу платеж. Поле ext-id_payment является номером транзакции в базе Поставщика.

Ответ со списком типов услуг

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>get_service_list</operation>

<services>

<service>

<type>wifi</type>

<description>Прием платежей за WiFi</description>

</service>

<service>

<type>phone</type>

<description>Прием платежей за телефон</description>

</service>

</services>

</response>

Ежедневные сверки (устаревшее, см. п. 2.7)

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

Формат файла

Файл, является плоским текстовым файлом с разделителями строк принятыми в ОС Windows. В качестве разделителя колонок выступает символ с кодом 9 (табуляция).

Пример файла

id_payment<TAB>date<TAB>account<TAB>sum

987654321<TAB>20070918155052<TAB>1234567890<TAB>12.34

Коды ошибок, возвращаемые Поставщиком

Автоматизированные сверки

Требования к ежедневным сверкам (п. 2.5) являются устаревшими. В целях совершенствования процесса взаимодействия вводится механизм автоматизированных сверок.

Механизм реализован следующим образом:

Загрузка реестра

Строка запроса

https://service.provider.ru/comepay?operation=upload_payments&
id_report=987654321

где:

operation=upload_payments – запрос на выгрузку списка платежей

id_report=987654321 – код реестра Оператора

Метод обработки запроса

Запрос обрабатывается методом POST.

Формат выгружаемых данных

<?xml version=”1.0” encoding=”utf-8” ?>

<payments>

<version>1.0</version>

<id_report>987654321</id_report>

<start_date>20070918000000</start_date>

<end_date>20070919000000<end_date>

<payment>

<id_payment>987654321</id_payment>

<date>20070918155052</date>

<account>1234567890</account>

<sum>12.34</sum>

<service>0</service>

</payment>

<payment>

...

</payment>

</payments>

где:

version – версия формата списка платежей

id_report – код реестра Оператора
start_date – начало отчетного периода (включительно)

end_date – окончание отчетного периода (исключительно)

id_payment – номер транзакции Оператора

account – номер счета

sum – сумма

date – дата проведения платежа у Поставщика

service – код услуги (сервиса) Поставщика, при отсутствии кода услуги (сервиса) передается пустой тег.

Текст ответа при удачной загрузке

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>upload_payments</operation>

<version>1.0</version>

<id_report>987654321</id_report>

<result>0</result>

</response>

Текст ответа при ошибке загрузки

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>upload_payments</operation>

<version>1.0</version>

<id_report>987654321</id_report>

<result fatal=”true”>801</result>

<ext-result>Код ошибки в системе Поставщика</ext-result>

<ext-description>Описание причин ошибки загрузки<ext-description>

</response>

Запрос результатов сверки

Строка запроса

https://service.provider.ru/comepay?operation=get_check_result&
id_report=987654321

Текст ответа при наличии ошибок или расхождений

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>get_check_result</operation>

<id_report>987654321</id_report>

<result fatal=”true”>803 или 804</result>

<ext-result>Код ошибки в системе Поставщика</ext-result>

<ext-description>Описание причин ошибки сверки<ext-description>

</response>

Текст ответа при неоконченном процессе сверки

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>get_check_result</operation>

<id_report>987654321</id_report>

<result fatal=”false”>802</result>

<ext-result>Код ошибки в системе Поставщика</ext-result>

<ext-description>Описание причин ошибки сверки<ext-description>

</response>

Текст ответа при отсутствии расхождений

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>get_check_result</operation>

<id_report>987654321</id_report>

<result>0</result>

</response>

Запрос расхождений

Строка запроса

https://service.provider.ru/comepay?operation=get_divergence&
id_report=987654321

Текст ответа при ошибке загрузки списка расхождений

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>get_divergence</operation>

<id_report>987654321</id_report>

<result fatal=”true”>805</result>

<ext-result>Код ошибки в системе Поставщика</ext-result>

<ext-description>Описание причин ошибки сверки<ext-description>

</response>

Текст ответа при загрузке списка расхождений

<?xml version=”1.0” encoding=”utf-8” ?>

<response>

<operation>get_divergence</operation>

<id_report>987654321</id_report>

<result>0</result>

<payments>

<payment>

<id_payment>987654321</id_payment>

<date>20070918155052</date>

<account>1234567890</account>

<sum>12.34</sum>

<service>0</service>

</payment>

</payments>

<ext-payments>

<ext-payment>

<ext-id_payment>987654321</ext-id_payment>

<ext-date>20070918155052</ext-date>

<ext-account>1234567890</ext-account>

<ext-sum>12.34</ext-sum>

<ext-service>0</ext-service>

</ext-payment>

</ext-payments>

</response>

где:

<payments> – раздел с данными Оператора

<ext-payments> – раздел с данными Поставщика

Например:

Оператор:

Поставщик:

Будут сформированы данные:

<payments>

<payment>

<id_payment>2</id_payment>

<date>20090401020000</date>

<account>1111111111</account>

<sum>21</sum>

<service/>

</payment>

<payment>

<id_payment>3</id_payment>

<date>20090401030000</date>

<account>3333333333</account>

<sum>30</sum>

<service/>

</payment>

<payment>

<id_payment>4</id_payment>

<date>20090401040000</date>

<account>4444444444</account>

<sum>40</sum>

<service/>

</payment>

</payments>

<ext-payments>

<ext-payment>

<ext-id_payment>2</ext-id_payment>

<ext-date>20090401020000</ext-date>

<ext-account>1111111111</ext-account>

<ext-sum>20</ext-sum>

<ext-service/>

</ext-payment>

<ext-payment>

<ext-id_payment>3</ext-id_payment>

<ext-date>20090401030000</ext-date>

<ext-account>3333333333</ext-account>

<ext-sum>31</ext-sum>

<ext-service/>

</ext-payment>

<ext-payment>

<ext-id_payment>5</ext-id_payment>

<ext-date>20090401050000</ext-date>

<ext-account>5555555555</ext-account>

<ext-sum>50</ext-sum>

<ext-service/>

</ext-payment>

</ext-payments>