providers.ini и providers_user.ini - системные параметры провайдеров

providers.ini

Файл providers.ini хранит в себе системные настройки провайдеров для ввода данных пользователем, оплаты и проведения платежей. Настройки хранятся в открытом виде и доступны для редактирования.

Несмотря на расширение ini данный файл не является стандартным ini-файлом, а представляет собой симбиоз ini-файла с элементами XML.
По этой же причине данный файл не может быть изменен спец.командой INIQuery, т.к. не содержит секций в явном виде.

Такой нестандартный формат был выбран для того, чтобы пользователи понимали принцип функционирования ПО, самостоятельно могли вносить в него изменения системных настроек провайдеров (даже непосредственно на терминале). Точно такой же формат файла используется для описания собственных провайдеров в файле MyProviders.ini (описание собственных провайдеров представлено в разделе "Собственные провайдеры или прием платежей без платежной системы"), поэтому нередко за основу для собственного провайдера берут описание уже существующего провайдера из providers.ini.

Мы не рекомендуем изменять файл providers.ini.

Только если вы адаптируете программу для работы за пределами России имеет смысл вносить изменения в файл providers.ini. В этом случае вам необходимо будет пользоваться специальными обновлениями не содержащими системных файлов с региональными настройками (это файлы providers.ini, def.base и другие). В такие обновления входят только файлы, отвечающие исключительно за функционал ПО (t.exe, config.exe, updater.exe и т.д.).

Учтите, что файл providers.ini присутствует практически во всех обновлениях ПО. Поэтому если вы вносили изменения в providers.ini, то после обновления файл будет перезатерт стандартным файлом providers.ini из обновления.

Для того, чтобы защитить ваши индивидуальные изменения от обновлений нужно создать файл providers_user.ini. Этот файл должен содержать не копию providers.ini, а только изменения.
Подробнее в главе "providers_user.ini".

Регистр написания наименований параметров не имеет значения.

Так код e-port равносилен написанию Код E-Port.

Параметры провайдеров

Таблица 1. Общие параметры провайдеров

Приведенные ниже параметры чаще всего применяются ко всем провайдерам: стандартных, переопределенных и собственных.

параметр тип значение по умолчанию описание
номер число 0 Обязательное свойство провайдера, должно указываться первым параметром. Именно оно является фактическим разделителем одного провайдера от другого.
✘ номер провайдера число 0 = «номер». Устар. с версии 4.1.2
наименование строка Уникальное наименование провайдера,выводится в списке платежей на сервере. Для собственных провайдеров передается на сервер в платеже.
краткое наименование строка Отображается при оплате, в чеке. Если не указано используется «наименование»
✘ наименование провайдера строка = «Краткое наименование». Устар. с версии 4.1.2
✘ альтернативное наименование провайдера строка Альтернативное наименование используется в Конфигураторе. Если значение не задано, то в качестве Альтернативного наименования провайдера используется Наименование провайдера.
Например, наименование провайдера может быть «Мегафон», а альтернативное «Мегафон Сибирь»; тогда пользователь при оплате увидит просто «Мегафон», а при настройке комиссии в Конфигураторе будет не 8 одинаковых Мегафонов, а 8 разных.
Используется для тех случаев, когда пользователю нужно вывести одинаковое наименование разных провайдеров, разделив их для себя. Устар. с версии 4.1.2
комментарий строка Выводится при оплате под Наименованием провайдера.
✘ регион строка Устаревший синоним параметра Комментарий. Рекомендуется использовать наименование параметра Комментарий.
организация строка Получатель средств. Используется при печати в чеке.
✘ наименование организации-получателя средств строка = «Организация». Устар. с версии 4.1.2
инн строка Используется при печати в чеке.
тип строка
(массив чисел через запятую)
1 Тип провайдера отвечает за то, в какой группе кнопок будет отображен провайдер при автоматическом формировании списка провайдеров на экране. Можно указывать через запятую без пробела, например, 1,20. См. описание типов.
справочный телефон строка Используется при печати в чеке.
форма ввода строка Путь до ini-файла, описывающего форму ввода данных. Как правило все формы ввода находятся в папке IMG\Keyboards\. Форма ввода содержит разметку дизайна: положение кнопок, полей ввода, ссылки на используемые изображения и другую информацию.
форма оплаты строка Путь до ini-файла, описывающего форму оплаты. Эту команду нужно применять только если вы используете стандартную форму ввода и онлайн проверку. На этой форме вы можете использовать дополнительные 3 команды (ShowStandartAccount, ShowStandartLogo, ShowStandartLabels) описание которых вы найдете здесь. По умолчанию для провайдера с включенной онлайн проверкой и стандартной формой ввода используется форма оплаты FormPay_Online.ini
формат поля ввода[N] строка ########## Параметр задает формат, по которому будут вводится символы в поле. Значимыми являются только символы решетки #. Все другие символы будут отображаться такими, какими описаны в формате поля ввода. По мере ввода символов в формате решетки замещаются вводимыми символами, формируя видимое значение поля ввода (чистое значение поля ввода формируется только за счет вводимых символов).
Особым форматом является 8-###-###-##-##, при автоопределении провайдера по введенному номеру телефона срабатывают более сложные правила ввода (ввод не более одной восьмерки и т.п.).
✘ формат ввода строка ########## Устаревший синоним параметра формат поля ввода. Рекомендуется использовать наименование параметра формат поля ввода или формат поля ввода1.
✘ формат строка ########## Устаревший синоним параметра формат поля ввода. Рекомендуется использовать наименование параметра формат поля ввода или формат поля ввода1.
приставка формата поля ввода[N] строка [N] не обязательный параметр, при его опущении значение считается равным 1.
В общем виде формат поля ввода выглядит следующим образом: формат поля ввода = приставка формата поля ввода + формат поля ввода + окончание формата поля ввода

Приставку формата имеет смысл использовать тогда:
1. Когда в пакете в ПС используется не чистые введенные данные, а форматированные (переменная {VALUE_FORMATED}).
2. Когда требуется ввод данных начало формата которых всегда едино (как правило приставку можно просто поместить в формат).
окончание формата поля ввода[N] строка [N] не обязательный параметр, при его опущении значение считается равным 1.
В общем виде формат поля ввода выглядит следующим образом: формат поля ввода = приставка формата поля ввода + формат поля ввода + окончание формата поля ввода

Окончание формата имеет смысл использовать тогда:
1. Когда в пакете в ПС используется не чистые введенные данные, а форматированные (переменная {VALUE_FORMATED}).
2. Когда требуется ввод данных окончание формата которых всегда едино. В отличие от приставки формата, окончание нельзя поместить в формат. Например, окончание формата поля ввода провайдера РОЛ имеет значение @ rol.ru, при этом формат ###############. Если мы поместим окончание @ rol.ru, то это окончание появится только по окончанию ввода всех символов в формате (заполнению всех решеток). Если же мы поместим @ rol.ru в окончание, то окончание будет отображаться независимо от основного формата. Таким образом при вводе электронного адреса будет постоянно отображаться @ rol.ru (при вводе каждого следующего символа @ rol.ru будет сдвигаться).
наименование поля ввода[N] строка [N] не обязательный параметр, при его опущении значение считается равным 1.
Параметр предназначен для хранения наименования полей ввода, которые требуются для оплаты. Значение параметра может быть использовано в формах ввода, а также чеке. Макроподстановка данного поля: {PROVIDER_FIELD_NAME[N]}.
✘ наименование основного поля строка Устаревший синоним параметра Наименование поля ввода. Рекомендуется использовать наименование параметра Наименование поля ввода или Наименование поля ввода1.
приставка поля ввода[N] строка [N] не обязательный параметр, при его опущении значение считается равным 1.
После ввода данных и нажатия кнопки «Приступить к оплате» к введенному полю добавляется приставка в начале введенных данных. В общем виде чистое значение введенного поля будет выглядеть следующим образом: чистое значение поля = приставка поля ввода + чистые введенные пользователем данные + окончание поля ввода

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

Пример: Приставка поля ввода для Яндекс.Денег - 41001. Это общие данные, которые пользователю нет необходимости вводить, они всегда одинаковые для всех кошельков Яндекс.Денег.
окончание поля ввода[N] строка [N] не обязательный параметр, при его опущении значение считается равным 1.
После ввода данных и нажатия кнопки «Приступить к оплате» к введенному полю добавляется окончание в конце введенных данных. В общем виде чистый значение введенного поля будет выглядеть следующим образом: чистое значение поля = приставка поля ввода + чистые введенные пользователем данные + окончание поля ввода

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

Пример: Приставка поля ввода для РОЛ - @ rol.ru. Это общие данные, которые пользователю нет необходимости вводить, они всегда одинаковые для всех аккаунтов РОЛ.
✘ приставка номера строка Устаревший синоним параметра Приставка поля ввода. Рекомендуется использовать наименование параметра Приставка поля ввода или Приставка поля ввода1.
✘ окончание номера строка Устаревший синоним параметра Окончание поля ввода. Рекомендуется использовать наименование параметра Окончание поля ввода или Окончание поля ввода1.
минимальная длина поля ввода[N] число 0 [N] не обязательный параметр, при его опущении значение считается равным длине формата поля ввода.
Минимальное количество символов в заполненном форматированном значении поля, после которого поле будет считаться введенным. Когда на форме все поля значатся введенными, т.е. введенное количество символов во всех полях удовлетворяет их условиям, возможен переход к оплате или к следующей форме ввода. Максимальная длина поля определяется количеством символов формата поля ввода.
✘ минимальная длина номера число 0 Устаревший синоним параметра Минимальная длина поля ввода. Рекомендуется использовать наименование параметра Минимальная длина поля ввода или Минимальная длина поля ввода1.
код поля ввода[N] строка Используется при отправке в ПС Рапида. DELETEME
Данный параметр следует заменить на Опция Rapida.
путь к изображению логотипа строка Путь до файла c изображением логотипа, включая имя файла (path\ProviderName.bmp).

Задается относительно корня ПО. При наличии в пути макроподстановки {SKIN_NAME} включается более сложный алгоритм - сначала изображение ищется в папке со скином, если не находит - тогда в общей папке IMG\Providers\. Поддерживается только формат BMP (один цвет можно назначить прозрачным).

Пример: Путь к изображению логотипа=IMG\{SKIN_NAME}\Providers\dalsv.bmp
путь к изображению пассивной кнопки строка Путь до файла c изображением пассивной (ненажатой) кнопки (path\ProviderName_pas.bmp).
1. Задается относительно корня ПО.
2. При наличии в пути макроподстановки {SKIN_NAME} включается более сложный алгоритм - сначала изображение ищется в папке со скином, если не находит - тогда в общей папке IMG\Providers\.
3. Поддерживается только формат BMP (один цвет можно назначить прозрачным).
4. Если в имени файла (включая путь) встречается _pas.bmp, то автоматически заполнится параметр Путь к изображению активной кнопки и его можно будет не задавать отдельным параметром (путем замены _pas.bmp на _act.bmp). При этом если принудительно задать параметр Путь к изображению активной кнопки, то он будет иметь больший приоритет.

Пример: Путь к изображению пассивной кнопки=IMG\{SKIN_NAME}\Providers\dalsv_adv_1_pas.bmp
путь к изображению активной кнопки строка Путь до файла c изображением активной (ненажатой) кнопки (path\ProviderName_pas.bmp).
1. Задается относительно корня ПО.
2. При наличии в пути макроподстановки {SKIN_NAME} включается более сложный алгоритм - сначала изображение ищется в папке со скином, если не находит - тогда в общей папке IMG\Providers\.
3. Поддерживается только формат BMP (один цвет можно назначить прозрачным).
4. Если в имени файла (включая путь) встречается _act.bmp, то автоматически заполнится параметр Путь к изображению пассивной кнопки и его можно будет не задавать отдельным параметром (путем замены _act.bmp на _pas.bmp). При этом если принудительно задать параметр Путь к изображению пассивной кнопки, то он будет иметь больший приоритет.

Пример: Путь к изображению активной кнопки=IMG\{SKIN_NAME}\Providers\dalsv_adv_1_act.bmp
логотип строка Универсальный параметр, рекомендуем использовать для замены трех предыдущих параметров. Если все три файла изображений находятся в папке IMG\Имя_скина\Prov​iders\, либо все три находятся в папке IMG\Providers\. В этом случае пути к изображению пассивной и активной кнопки должны иметь окончание _pas и _act перед расширением .bmp (например, если логотип beeline.bmp, то файлы кнопок должны иметь имена beeline_pas.bmp и beeline_act.bmp).

1. В первую очередь файлы ищутся в папке IMG\Имя_скина\Prov​iders\, в случае отсутствия - в папке IMG\Prov​iders\.
2. Поддерживается только формат BMP (один цвет можно назначить прозрачным).

Пример: Логотип=dalsv.bmp
подчиненные провайдеры строка
(массив чисел через запятую)
Используется для простого создания провайдеров-групп, обычно с цифровой формой ввода. Позволяют при вводе номера предложить выбор какую конкретно услугу хочет оплатить пользователь. Например, при вводе городского номера можно предложить оплатить Абон.плату, Межгород, Интернет, Кабельное ТВ и т.п. (если они привязаны к одному номеру). Провайдер с данным параметром перестает быть обычным провайдером (его нельзя оплатить) - он только реализует механизм выбора других конечных провайдеров.
адрес предпроверки [наименование_ПС] строка Адрес предпроверки используется для проверки возможно ли совершить платеж с введенными реквизитами. Это обязательный этап проведения платежей в CyberPlat, только на основании предпроверки CyberPlat разрешает проведение платежа.
Также используется для он-лайн проверки, т.к. возвращает данные клиента (например, ФИО и т.д.).

Данный параметр используется только ПС CyberPlat (а также собственными провайдерами), т.к. в других ПС адрес для всех операций с платежами единый.
адрес оплаты [наименование_ПС] строка Адрес оплаты используется для непосредственного проведения платежа после получения разрешения в ходе предпроверки. Без успешной предпроверки CyberPlat не проведет платеж.

Данный параметр используется только ПС CyberPlat (а также собственными провайдерами), т.к. в других ПС адрес для всех операций с платежами единый.
адрес оплаты2 строка Запасной адрес оплаты если первый не ответил
адрес проверки статуса [наименование_ПС] строка Адрес проверки статуса используется для уточнения статуса платежа, если полученный ответ от сервера CyberPlat не позволяет однозначно определить состояние платежа. Используется для платежей со статусом 12.

Данный параметр используется только ПС CyberPlat (а также собственными провайдерами), т.к. в других ПС адрес для всех операций с платежами единый.
внесенная сумма при online проверке дробное число 50.0 Передается в качестве внесенной суммы при он-лайн проверке платежей. Следует изменять в том случае, если значение по умолчанию не удовлетворяет, например, если минимальный платеж больше значения по умолчанию.
сумма к зачислению при online проверке дробное число 50.0 Передается в качестве суммы к зачислению (внесенная сумма - комиссия) при он-лайн проверке платежей. Следует изменять в том случае, если значение по умолчанию не удовлетворяет, например, если по провайдеру обязательно взимание комиссии (ГИБДД, Avon и др.).
код [наименование_ПС] число Идентификационный код провайдера в каждой из платежных систем, подключенных в ПО PayPRO. Если для платежной системы указан код, это означает, что оплата провайдера потенциально возможна через эту ПС. Конфигуратор и Диспетчерская используют эту информацию для вывода доступных ПС при настройке комиссии и выборе через какую ПС следует проводить провайдера.

Следует иметь ввиду:
1. Код PinPay всегда отрицательный (за знаком минус).
2. Код CyberPlat не существует. Вместо этого в ПС CyberPlat используются разные адреса для отправки платежей у каждого провайдера (задаются в параметрах адрес предпроверки cyberplat, адрес оплаты cyberplat, адрес проверки статуса cyberplat).

[наименование_ПС] смотри в таблице кодов платежных систем.
опция [наименование_ПС] строка Опция облегчает настройку нестандартных пакетов провайдеров. На момент написания статьи использовалось только для пакетов КиберПлат. В описании пакета {PROVIDER-OPTION_PS} заменяется на Опция [наименование_ПС].

[наименование_ПС] смотри в таблице кодов платежных систем.
шаблон пакета [наименование_ПС] число Ссылка на описание пакета другого провайдера. Удобно использовать, если у какого-либо провайдера используется нестандартный пакет отправки данных, при этом такой же пакет уже был описан у другого провайдера (типичный пример - описание пакетов СибирьТелекома для разных регионов).

[наименование_ПС] смотри в таблице кодов платежных систем.
код услуги строка Используется при запросе данных плательщика по оригинальному протоколу СибирьТелекома, через PinPay. Является фильтром вывода полученной от сервера информации по конкретной услуге (абон.плата, межгород), например, вывести задолженность только по абон.плате.
DELETEME дополнительно печатать в у.е. В настоящий момент параметр не используется. Ранее использовался в E-Port.
выполнить Строка Запуск программы или скрипта на выполнение, Команда Выполнить (exec)
создать файл по шаблону Строка Команда Создать файл по шаблону (CreateFileFromTemplate)
ввод контактного телефона Строка Не задано Параметр ввод контактного телефона предназначен для управления вывода на экран формы ввода контактного телефона, для провайдеров которым он требуется для передачи в ПС или просто для информации (чтобы можно было связаться с абонентом), отображается в Диспетчерской. Параметр может принимать одно из перечисленных значений:
Рекомендован - форма будет подгружаться если в config_comission.ini не задан параметр need_client_phone.
Всегда - форма будет подгружаться в независимости от параметра в config_comission.ini
Никогда - форма вообще не будет подгружаться.
Не задано (по умолчанию) - загрузка формы будет зависеть от параметра need_client_phone в config_comission.ini.
Внимание! Если в шаблоне отправки встречается параметр {CLIENT_PHONE} то форма загрузится в любом случае, независимо от параметра ввод контактного телефона.
форма ввода контактного телефона строка Задается форма ввода контактного (мобильного) телефона, которая будет отображена перед платежом.
По умолчанию = IMG\keyboards\FormInput_ContactPhone.ini
диалог печати Бит Показать диалог «печатать чек?». 0-нет, 1-да, иное-по умолчанию, зависит от config.ini[printer]printreceiptask
печать Бит Параметр печати чека, если «Диалог печати» не включен. 0-не печатать чек, 1-печатать, иное-по умолчанию, зависит от config.ini[printer]printreceipt
пересчет комиссии Пересчет комиссии при перепроведении (с версии 4.2.2.4)
Следующий Число Смена провайдера при автоопределении если текущий выключен.
БезКомиссии Число Устанавливает параметр Следующий если тот не задан.

Таблица 2. Характерные параметры переопределенных провайдеров

Приведенные ниже параметры чаще всего применяются к переопределенным провайдерам (через providers_user.ini).

параметр тип значение по умолчанию описание
обнулить настройки провайдера
(команда)

(команда)
Очищает все настройки провайдера. Команда актуальна для полного переопределения провайдера в providers_user.ini. Наглядный пример использования в примере 2.
передать наименование провайдера в мониторинг строка При указании этого параметра при выгрузке платежей на сервер PayPRO будет передано указанное в данном параметре наименование провайдера. Таким образом в поиске платежей и в ежедневном реестре платежей будет отображено наименование провайдера, заданное в этом параметре. Данный параметр удобно использовать при полном переопределении провайдера.

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

Таблица 3. Характерные параметры собственных провайдеров

Приведенные ниже параметры чаще всего применяются к собственным провайдерам (через MyProviders\MyProviders.ini).

1. Параметр наименование серверной переменой[N] иногда может использоваться и в описании стандартных провайдеров для отображения данных, полученных при он-лайн проверке (например, ФИО).

2. Параметры адрес предпроверки, адрес оплаты, адрес проверки статуса являются частным случаем общих параметров провайдера: адрес предпроверки [наименование_ПС], адрес оплаты [наименование_ПС], адрес проверки статуса [наименование_ПС], только без наименования ПС (наименование ПС для собственных провайдеров при загрузке из myproviders.ini считается пустым значением).

3. Собственные провайдеры имеют в ПО хранятся с отрицательными номерами. При описании номер указывается положительный, однако при использовании нужно использовать отрицательные номера. Допускается при описании указывать отрицательный номер (знак - игнорируется при обработке параметра номер провайдера).

параметр тип значение по умолчанию описание
наименование серверной переменой[N] строка Наименование серверной переменной
метод отправки get
(команда)

(команда)
При указании команды в настройке собственного провайдера, данные на сервер собственного провайдера будут отправляться методом GET. Если команда не указана, то отправка будет осуществляться методом POST.
адрес предпроверки строка Адрес используется для он-лайн проверки после нажатия кнопки «Приступить к оплате». Возможно как простое запрещение или разрешение оплаты в зависимости от результатов он-лайн проверки. При использовании параметров наименование серверной переменой[N] и описания правил получения значений серверных переменных возможно выводить полученную информацию на экран и в чек (правила получения серверной переменной описываются в полях начало поиска первого символа серверной переменной и начало поиска последнего символа серверной переменной). Например, ФИО клиента, адрес, задолженность, рекомендованный платеж и т.п.
адрес оплаты строка Адрес используется для непосредственного проведения платежей после нажатия кнопки «Оплатить». На данный момент платеж считается успешный если пакет с платежом физически удалось отправить на сервер (при сбоях связи платеж будет отправляться пока не получит любой непустой ответ сервера).
адрес проверки статуса строка Пока не реализована, т.к. не было потребности в реализации. По аналогии с платежными системами данный адрес может использоваться для запросов получения статуса по платежу. На данный момент платеж считается успешный если пакет с платежом физически удалось отправить на сервер (при сбоях связи платеж будет отправляться пока не получит любой непустой ответ сервера).
SSLVersion (SSLv23, SSLv3, TLSv1) SSLv2 Версия SSL для HTTPS
http логин строка Логин для HTTP-Basic авторизации.
http пароль строка Пароль для HTTP-Basic авторизации.
сертификат строка Путь где лежит сертификат(*.crt) относительно T.exe
ключ строка Путь где лежит ключ(*.key) относительно T.exe
пароль от сертификата строка Пароль от сертификата, если нет, то не указывать
интервалы автоопределения строка Интервалы автоопределения загружаются в память ПО вместе с базой номеров ПО (файл DEF.base). Используются в тех случаях, когда требуется чтобы ваш собственный провайдер автоматически определялся по введенному номеру (как это сделано для сотовых операторов).
Способ записи следующий:
123-456,60-79 - ПО сначала достроит числа до формата. Так если формат ######, то данные интервалы преобразуются в 123000-456999,600000-799999. После этого ПО оптимизирует скорость распознавания номера попарно удаляя символы 0 и 9 в начале и конце каждого интервала соответственно. После оптимизации номер интервалы будут выглядеть так: 123-456,6-7. Таким образом при вводе цифры 6 или 7 уже определится ваш провайдер, вторую цифру вводить не потребуется для определения провайдера.
123,6-7 - данный способ записи равносилен 123-123,6-7.
Как вы видите не обязательно вводить интервалы полностью 123000-456999,600000-799999, достаточно более короткой записи 123-456,6-7.

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

(команда)
При указании команды в настройке собственного провайдера, данные на сервер собственного провайдера будут отправляться в URL-кодированном виде. Если команда не указана, то отправка будет осуществляться без URL-кодирования.
Команда практически не актуальна, т.к. фактически всегда URL-кодирование требуется обязательно.
разделитель&
(команда)

(команда)
При отправке пакета методом post в ПО каждая строка считается отдельным параметром, а разделяются они пробелом. Данный параметр заменяет пробелы на амперсант для пакетов платежей и онлайн проверки. Большинство современных серверов корректно работают с обоими вариантами.

Сборка платежного пакета

Общее описание и схема сборки платежного пакета

В общем виде сборка пакета представлена на схеме 1 (слева). Каждый пакет содержит общую часть (заголовок и подвал), которая не связана непосредственно с платежом. А также сами платежи. Платежи в свою очередь делятся на два типа: неотправленные и действующие. Неотправленные платежи - это те платежи, которые еще не отправлялись в ПС, либо более редкий случай - платежи которые ПС не приняла в обработку. Действующие платежи - это платежи, которые уже отправлялись в ПС и в дальнейшем требуется только получение статуса по таким платежам. Как правило неотправленные платежи помещаются в обертку (контейнер). Действующие также помещаются в свою обертку. Это действительно для XML-протокола, в то время как для простого текстового протокола (pain text) обертка может не использоваться.

При сборке пакета ПО PayPRO сначала объединяет все неотправленные платежи, помещает их в контейнер для неотправленных платежей (группу неотправленных платежей). Аналогично поступает с действующими (группа действующих платежей). Далее начинается непосредственно сборка пакета

Пакет = Заголовок + Группа неотправленных платежей + Группа действующих платежей + Подвал

PayPRO. Схема 1. Общая схема состава платежного пакета PayPRO. Схема 2. Реализация сборки платежного пакета через providers.ini

Алгоритм сборки пакета в ПО PayPRO

Реализация механизма настраиваемой сборки пакета в ПО PayPRO продемонстрирована на схеме 2 (справа). Фактически она заключается в описании содержимого каждого из элементов пакета в файле providers.ini (а также его разновидностей: providers_user.ini и MyProviders.ini).

1. Получение текстового содержания всех неотправленных платежей (переменная {NOTSENDED_OPERATION}).

1.1. Сначала ПО определяет, сколько неотправленных платежей подходит для отправки в данный момент (в ПО PayPRO существует система ранжирования платежей по большому количеству критериев). В зависимости от протокола выбираются от 1 до 15 платежей которые следует отправить сейчас (более 15 платежей лучше не отправлять на терминале через GPRS, т.к. конечный пакет для отправки может стать большим).

1.2. Каждый пакет преобразуется в текст Неотправленного пакета N согласно описанию Неотправленного пакета в providers.ini (<начало Неотправленного пакета> . . . <конец Неотправленного пакета>). Для получения этого текста берется описание пакета, в тексте которого заменяются все {ПЕРЕМЕННЫЕ} на их значения. Аналогичный механизм используется и для других частей пакета.

1.3. Далее на основе текста каждого выбранного платежа формируется переменная {NOTSENDED_OPERATION}:

{NOTSENDED_OPERATION} = текст Неотправленного пакета 1 + текст Неотправленного пакета 2 + ... + текст Неотправленного пакета N

2. Получение текстового содержания всех действующих платежей (переменная {NOTREPLY_OPERATION}).

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

2.2. Каждый пакет преобразуется в текст Действующего пакета N согласно описанию Действующего пакета в providers.ini (<начало Действующего пакета> . . . <конец Действующего пакета>).

2.3. Далее на основе текста каждого выбранного платежа формируется переменная {NOTREPLY_OPERATION}:

{NOTREPLY_OPERATION} = текст Действующего пакета 1 + текст Действующего пакета 2 + . . . + текст Действующего пакета N

В некоторых ПС (например, CyberPlat, E-Port и др.) описание Действующего пакета не отличается от описания Неотправленного пакета. Т.е. при опросе и при проведении платежей используется один и тот же текст запроса. Однако он может быть отправлен на разные адреса (например, в CyberPlat) или платежная система сама определит есть ли у нее такой платеж или нет (если есть, то сообщит его статус, если нет - примет на проведение; например, в E-Port). В этом случае можно ограничиться только описанием Неотправленного пакета.
Текст Действующего пакета N в этом случае будет получен согласно описанию Неотправленного пакета в providers.ini (<начало Неотправленного пакета> . . . <конец Неотправленного пакета>).

3. Получение Группы неотправленных платежей и Группы Действующих платежей.

3.1. Текстовое содержание неотправленных платежей может быть использовано в чистом виде (как переменная {NOTSENDED_OPERATION}), а может быть обернуто для получения Группы неотправленных платежей. Для этого используется описание Неотправленного тела шаблона в providers.ini (<начало Неотправленного тела шаблона> . . . <конец Неотправленного тела шаблона>).

3.2. Если текстовое содержание неотправленных платежей не нужно оборачивать, то описание Неотправленного тела шаблона можно упустить, а переменную {NOTSENDED_OPERATION} использовать непосредственно в заголовке пакета (или подвале). В этом случае понятие Группа неотправленных платежей будет отсутствовать (внутренняя переменная в ПО иметь пустое значение).

3.3. Аналогичные правила действуют и для Группы действующих платежей. Переменная {NOTREPLY_OPERATION} может быть обернута для получения Группы действующих платежей (как правило для XML-протокола) или использоваться в чистом виде (например, для простых текстовых протоколов).

4. Получение Пакета.

4.1. Получение Заголовка (шапки). Сборка Заголовка пакета происходит согласно описанию Общего заголовка шаблона в providers.ini (<начало Общего заголовка шаблона> . . . <конец Общего заголовка шаблона>). В Заголовке возможно использование переменных {NOTSENDED_OPERATION} и {NOTREPLY_OPERATION}, например, в тех случаях когда эти переменные не нужно оборачивать или передача нескольких платежей в пакете не поддерживается принимающим сервером (в этом случае саму обертку, если она требуется можно сделать непосредственно в Заголовке).

4.2. Получение Подвала. Сборка Подвала пакета происходит согласно описанию Общего подвала шаблона в providers.ini (<начало Общего подвала шаблона> . . . <конец Общего подвала шаблона>). В Подвале также возможно использование переменных {NOTSENDED_OPERATION} и {NOTREPLY_OPERATION}.

4.3. Получение Пакета происходит по уже описанному правилу:

Пакет = Заголовок + Группа неотправленных платежей + Группа действующих платежей + Подвал

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

Запрос баланса

Часто для запроса баланса в ПС используются сокращенные пакеты:

Пакет = Заголовок + Подвал

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

* Для КиберПлата схема иная. Переход на следующий статус.

providers_user.ini

Файлы providers.ini и providers_user.ini считываются программой одним и тем же алгоритмом, единожды во время запуска ПО. Поэтому если вы внесли изменения в эти файлы, то они вступят в силу только после перезапуска ПО.

Первым идет загрузка файла providers.ini, а затем файла providers_user.ini (если он имеется).
Важной особенностью обработки файла providers_user.ini является то, что данные содержащиеся в нем «наслаиваются» на данные в providers.ini. За основу берутся данные из файла providers.ini, а данные в providers_user.ini корректируют загруженную информацию из providers.ini.

В файле providers_user.ini применимы те же параметры провайдеров, что и в файле providers.ini (см. таблицы параметров провайдеров).


Пример 1

Для наглядности примера, посчитаем, что нам необходимо изменить наименование провайдера НТК и его код ОСМП.

  1. Назовем провайдера вместо «НТК» - «Новая телефонная компания».
  2. Код ОСМП вместо 127 установим 721.

Найдем описание провайдера в providers.ini (этой провайдер номер 39):

...

<Провайдер>
Номер провайдера=38
Наименование провайдера=ЗАО "НСС" Нижний Новгород
Наименование организации-получателя средств=ЗАО "Нижегородская Сотовая Связь"
Тип=1
ИНН=5260053878
Справочный телефон=8(831)415-15-15, 8-908-750-01-11
Логотип=nss.bmp
Код e-port=5535
Код PinPay=-1542
Код OSMP=32
Код Qiwi=32
Код DeltaPay=50
Адрес предпроверки CyberPlat=https://service.cyberplat.ru/cgi-bin/ns/ns_pay_check.cgi
Адрес оплаты CyberPlat=https://service.cyberplat.ru/cgi-bin/ns/ns_pay.cgi
Адрес проверки статуса CyberPlat=https://service.cyberplat.ru/cgi-bin/ns/ns_pay_status.cgi
Формат поля ввода=8-###-###-##-##




<Провайдер>
Номер провайдера=39
Наименование провайдера=НТК
Наименование организации-получателя средств=ОАО "Новая Телефонная Компания"
Тип=1
ИНН=2540040971
Справочный телефон=0515
Логотип=ntk.bmp
Код e-port=6007
Код PinPay=-151
Код OSMP=127
Код Qiwi=127
Код DeltaPay=361
Адрес предпроверки CyberPlat=https://service.cyberplat.ru/cgi-bin/nk/nk_pay_check.cgi
Адрес оплаты CyberPlat=https://service.cyberplat.ru/cgi-bin/nk/nk_pay.cgi
Адрес проверки статуса CyberPlat=https://service.cyberplat.ru/cgi-bin/nk/nk_pay_status.cgi
Формат поля ввода=8-###-###-##-##




<Провайдер>
Номер провайдера=40
Наименование провайдера=Ульяновск-GSM
Наименование организации-получателя средств=ЗАО "Ульяновск-GSM"
Тип=1
ИНН=7303022888
Справочный телефон=117
Логотип=ulgsm.bmp
Код e-port=5916
Код OSMP=144
Код Qiwi=377
Код DeltaPay=1319
Адрес предпроверки CyberPlat=https://service.cyberplat.ru/cgi-bin/ge/ge_pay_check.cgi/63
Адрес оплаты CyberPlat=https://service.cyberplat.ru/cgi-bin/ge/ge_pay.cgi/63
Адрес проверки статуса CyberPlat=https://service.cyberplat.ru/cgi-bin/ge/ge_pay_status.cgi
Формат поля ввода=8-###-###-##-##

...

Теперь нам нужно открыть файл providers_user.ini (если его нет, то создать пустой). В конец этого файла дописать нашего нового провайдера, удалив те настройки, которые не хотим фиксировать (оставляем только те, которые хотим поменять).

<Провайдер>
Номер провайдера=39
Наименование провайдера=НТК
Наименование организации-получателя средств=ОАО "Новая Телефонная Компания"
Тип=1
ИНН=2540040971
Справочный телефон=0515
Логотип=ntk.bmp
Код e-port=6007
Код PinPay=-151
Код OSMP=127
Код Qiwi=127
Код DeltaPay=361
Адрес предпроверки CyberPlat=https://service.cyberplat.ru/cgi-bin/nk/nk_pay_check.cgi
Адрес оплаты CyberPlat=https://service.cyberplat.ru/cgi-bin/nk/nk_pay.cgi
Адрес проверки статуса CyberPlat=https://service.cyberplat.ru/cgi-bin/nk/nk_pay_status.cgi
Формат поля ввода=8-###-###-##-##

Выделенные строки удаляем, т.к. наша цель зафиксировать изменения только Наименование провайдера и Код OSMP. Также следует оставить две строки. Первая описывает начало описания провайдера. Вторая - какого именно провайдера.

<Провайдер>
Номер провайдера=39

В итоге получаем такое содержание файла providers_user.ini с измененными параметрами:

<Провайдер>
Номер провайдера=39
Наименование провайдера=Новая телефонная компания
Код Qiwi=721

Таким образом файл providers_user.ini представляет собой сокращенную версию файла providers.ini в котором перечислены только изменения, которые мы хотим произвести со стандартными провайдерами.


Пример 2

Добавим провайдера, который есть в какой-либо ПС, однако стандартно не добавлен в наше ПО. Такого провайдера можно добавить самостоятельно, не обращаясь к нам.

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

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

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

Итак, выберем провайдера «СкайЛинк Омск» (номер провайдера 64). Вместо него создадим более полезного для кого-то провайдера «Красноярскэнергосбыт», оплата которого возможна через Е-Порт, ОСМП, PinPay и мобильный кошелек QIWI.

Добавим в файл providers_user.ini нового провайдера:

<Провайдер>
Номер провайдера=64
Обнулить настройки провайдера
Наименование провайдера=Красноярскэнергосбыт
Передать наименование провайдера в мониторинг=Красноярскэнергосбыт
Наименование организации-получателя средств=ОАО "Красноярскэнергосбыт"
ИНН=2466132221
Комментарий=Введите номер лицевого счета
Наименование поля ввода=Номер лицевого счета
Тип=20
Логотип=kek.bmp
Код e-port=7571
Код PinPay=-2136
Код OSMP=929
Код Qiwi=20911
Формат поля ввода=##############
Минимальная длина номера=5
Форма ввода=IMG\keyboards\FormInput_nmb_smb_RUS.ini

Напомню важную особенность файла providers_user.ini: содержащиеся в нем данные накладываются на этого же по номеру провайдера из файла providers.ini. Таким образом настройки «Красноярскэнергосбыт» из файла providers_user.ini наложатся поверх настроек «СкайЛинк Омск» из providers.ini.

Приведем алгоритм наложения настроек на примере провайдера 64.

Параметр providers.ini providers_user.ini конечная конфигурация провайдера
Номер провайдера 64 64 64
Наименование провайдера СкайЛинк Красноярскэнергосбыт Красноярскэнергосбыт
Передать наименование провайдера в мониторинг Красноярскэнергосбыт Красноярскэнергосбыт
Альтернативное наименование провайдера СкайЛинк Омск СкайЛинк Омск
Наименование организации-получателя средств ЗАО «Дельта - Телеком» ОАО «Красноярскэнергосбыт» ОАО «Красноярскэнергосбыт»
ИНН 7803032718 2466132221 2466132221
Комментарий Введите номер лицевого счета Введите номер лицевого счета
Наименование поля ввода Номер лицевого счета Номер лицевого счета
Тип 1 20 20
Логотип skylink.bmp kek.bmp kek.bmp
Код e-port 6955 7571 7571
Код PinPay -51 -2136 -2136
Код OSMP 390 929 929
Код Qiwi 479 20911 20911
Код DeltaPay 225 225
Адрес предпроверки CyberPlat https://service.cyberplat.ru/cgi-bin/ge/ge_pay_check.cgi/384 https://service.cyberplat.ru/cgi-bin/ge/ge_pay_check.cgi/384
Адрес оплаты CyberPlat https://service.cyberplat.ru/cgi-bin/ge/ge_pay.cgi/384 https://service.cyberplat.ru/cgi-bin/ge/ge_pay.cgi/384
Адрес проверки статуса CyberPlat https://service.cyberplat.ru/cgi-bin/ge/ge_pay_status.cgi https://service.cyberplat.ru/cgi-bin/ge/ge_pay_status.cgi
Номер провайдера 64 64 64
Формат поля ввода 8-###-###-##-## ############## ##############
Минимальная длина номера 5 5
Форма ввода IMG\keyboards\FormInput_nmb_smb_RUS.ini IMG\keyboards\FormInput_nmb_smb_RUS.ini

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

Чтобы избежать такого эффекта нужно добавить параметр (а точнее команду) Обнулить настройки провайдера. Данная команда очистит все настройки провайдера и после этого ни один параметр переопределяемого провайдера не будет унаследован из providers.ini. Данную команду нужно обязательно использовать только в случае полного переопределения провайдеров. Иначе вы рискуете получить неожиданные свойства провайдера, которые перешли к нему из исходного провайдера в providers.ini.

Пример 3

Соберем воедино оба примера, чтобы продемонстрировать реальное содержимое файла providers_user.ini, который должен получиться.

providers_user.ini
<Провайдер>
Номер провайдера=39
Наименование провайдера=Новая телефонная компания
Код Qiwi=721
 
 
<Провайдер>
Номер провайдера=64
Обнулить настройки провайдера
Наименование провайдера=Красноярскэнергосбыт
Передать наименование провайдера в мониторинг=Красноярскэнергосбыт
Наименование организации-получателя средств=ОАО "Красноярскэнергосбыт"
ИНН=2466132221
Комментарий=Введите номер лицевого счета
Наименование поля ввода=Номер лицевого счета
Тип=20
Логотип=kek.bmp
Код e-port=7571
Код PinPay=-2136
Код OSMP=929
Код Qiwi=20911
Формат поля ввода=##############
Минимальная длина номера=5
Форма ввода=IMG\keyboards\FormInput_nmb_smb_RUS.ini

:!: При нажатии на заголовок примера providers_user.ini вы можете скачать данный пример.

В данном примере провайдер 39 частично изменен, а провайдер 64 переопределен полностью.
Системные настройки провайдеров, содержащиеся в этом файле будут защищены от изменений при обновлении ПО.


ОСТОРОЖНО! Не копируйте в providers_user.ini изменений больше, чем необходимо и только по действительно изменяемым провайдерам.

Уже неоднократно случались ситуации, когда пользователь хотел поменять, например, «Код OSMP», а скопировал «на всякий случай» всё описание нужного ему провайдера из providers.ini в providers_user.ini. Таким образом пользователь зафиксировал от изменений не только «Код OSMP», но и все другие параметры провайдера. Однако бывает, когда какая-либо платежная система меняет код провайдера или формат отправки данных - в этом случае мы оперативно меняем настройки такого провайдера в providers.ini. Например, платежная система КиберПлат изменила параметры этого провайдера. Однако пользователь в providers_user.ini зафиксировал не только параметры связанные с ОСМП, но и все другие параметры, включая КиберПлат. Таким образом у него будут зафиксированы старые изменения по КиберПлат и платежи провайдера через КиберПлат проходить перестанут. Проблему отклонения платежей в этом случае будет сложно найти.
Правильнее в этом случае было вынести в providers_user.ini только «Код OSMP» по требуемому провайдеру.

Еще более страшное и, к сожалению, тоже распространенное явление, когда пользователь столкнувшись с тем, что во время очередного обновления его файл providers.ini был затерт, копирует ВСЁ его содержимое в providers_user.ini (видимо, чтобы в следующий раз точно ничего не произошло). В этом случае ситуация подобна описанной выше, однако в больших масштабах. Вероятность того, что появятся изменения в одном из сотен провайдеров - очень велика, поэтому по прошествию некоторого времени у пользователя наверняка начнутся проблемы с отклоненными платежами то по одному провайдеру, то по другому.
Правильнее в этом случае было вынести в providers_user.ini описания только действительно измененных провайдеров. Если провайдер был изменен не полностью, то только изменения по ним.

Полностью копировать измененного провайдера из providers.ini в providers_user.ini следует только, если провайдер был полностью изменен (как в примере 2). В этом случае не забывайте использовать параметр «Обнулить настройки провайдера»

Добавление провайдеров

Если вы хотите добавить провайдера, который есть в какой-либо платежной системе - напишите об этом на электронную почту providers@paypro.ru (услуга бесплатная).

Если вы хотите добавить собственного провайдера, которого нет в платежных системах - напишите об этом на электронную почту myproviders@paypro.ru (услуга платная).
Подробная иллюстрированная инструкция с примерами по самостоятельному добавлению собственных провайдеров.