Общие принципы взаимодействия

Правила формирования запроса:

1. Используемая кодировка — UTF-8.
2. Имена всех параметров, которые касаются взаимодействия Platron и магазина, имеют префикс pg_. Все прочие параметры его не имеют.
3. Во всех денежных суммах:
   • для отделения дробной части используется точка.
   • если число целое, то указание дробной части необязательно.
   • число знаков после точки – не более двух.
   • тысячи не отделяются никакими знаками.
4. Любые сообщения (запросы и ответы) между Platron и магазином подписываются.

Формирование подписи

Пример вызова http://domain.com/path/to/script.php

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>9imM909TH820jwk387</pg_salt>
    <pg_t_param>value3</pg_t_param>
    <pg_a_param>value1</pg_a_param>
    <pg_z_param>
        <pg_q_subparam>subvalue2</pg_q_subparam>
        <pg_m_subparam>subvalue1</pg_m_subparam>
    </pg_z_param>
    <pg_b_param>value2</pg_b_param>
    <pg_sig>a8a4d5a9188f24038a14a4d65c387bf7</pg_sig>
</request>

В данном примере pg_sig вычисляется по формуле:

pg_sig = md5('script.php' + ';' + pg_a_param + ';' + pg_b_param + ';' + pg_salt + ';' + pg_t_param + ';' + pg_m_subparam + ';' + pg_q_subparam + ';' + secret_key);

Если в настройках было указано, что secret_key равен mypasskey, то после подстановки значений получится:

pg_sig = md5('script.php;value1;value2;9imM909TH820jwk387;value3;subvalue1;subvalue2;mypasskey')
pg_sig = 'a8a4d5a9188f24038a14a4d65c387bf7'

Для обеспечения безопасности все сообщения между Platron и сторонними магазинами подписываются специальным образом. Для формирования подписи необходимо выполнить следующие шаги:

1. Получить имя вызываемого скрипта. Это часть URL от последнего слеша “/" до конца или вопросительного знака “?".
2. Получить все параметры сообщения. Если сообщение в формате XML, то параметры берутся из всех вложенных тегов в алфавитном порядке. Параметры с одинаковыми именами берутся в том порядке, в котором они присутствуют в сообщении.
3. Получить случайную строку pg_salt. Это строка, состоящая из произвольного количества цифр и букв латинского алфавита.
4. Конкатенировать полученные значения с разделителем “;". Порядок конкатенации следующий: имя скрипта, все поля сообщения, pg_salt и платежный пароль secret_key, который задается в настройках магазина.
5. Вычислить MD5-хэш от полученной строки.
6. Записать полученный MD5-хэш в виде шестнадцатеричной строки в нижнем регистре длиной 32 символа (pg_sig).
7. Добавить параметр pg_sig в запрос или ответ.

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

Если Platron не может идентифицировать магазин (мерчанта), поэтому он не знает его секретный ключ (secret_key), то сообщение не подписывается и, следовательно, параметры pg_salt и pg_sig отсутствуют. В этом случае поле pg_error_code, которое содержит числовой код ошибки, принимает значение 101. Для проверки корректности формирования подписи рекомендуется использовать специальный инструмент в личном кабинете магазина: Проверка подписи к запросу.

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

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

https://www.platron.ru/script.php?param_1=val1&m_2[subparam_1]=val2&m_2[subparam_2]=val3&m_3=val4

Пример xml запроса:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_param1>value1</pg_param1>
    <pg_param2>value2</pg_param2>
    <pg_param3>value3</pg_param3>
</request>

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

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_param1>value1</pg_param1>
    <pg_param2>value2</pg_param2>
    <pg_param3>value3</pg_param3>
</response>

Пример ответа с ошибкой:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>19imfwM909TH820jwk387</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>200</pg_error_code>
    <pg_error_description>amount not specified</pg_error_description>
    <pg_sig>ccde41a4f425d124a23c3a53a3140bdc158ac</pg_sig>
</response>

Используются три способа прямой передачи информации между магазином и Platron:

1. Методом GET – данные передаются в параметрах методом GET.
2. Методом POST – данные передаются в параметрах методом POST.
3. Через XML – запросы передаются методом POST в единственном параметре pg_xml:

Независимо от способа формирования запроса (GET, POST или XML) ответ всегда выдается в формате XML.

Ответ всегда содержит параметр pg_status, указывающее на результат выполнения запроса. Оно принимает значение ok в случае успешного выполнения запроса и error – при возникновении ошибки. В последнем случае в ответе будут присутствовать поля:

• pg_error_code – числовой код ошибки (возможные значения перечислены в разделе Справочнике кодов ошибок)
• pg_error_description – описание ошибки (необязательное поле).

Через браузер пользователя

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

Передача информации по действию покупателя

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

1. Ссылка, ведущая на другой сайт
2. Форма, действие которой перенаправляет на другой ресурс. Пользователь сам нажимает кнопку.

Автоматическая передача информации

Пример авто-самбит формы

<html>
<body onload="document.forms[0].submit()">
<form method="POST" action="https://www.platron.ru/payment.php">
    <input type="hidden" name="pg_param1" value="value1"/>
    <input type="hidden" name="pg_param2" value="value2"/>
    <input type="hidden" name="pg_param3" value="value3"/>
    <input type="hidden" name="pg_param4" value="value4"/>
</form>
</body>
</html>

Автоматическая передача покупателя и информации между Platron и магазином возможна следующими способами:

1. Использование HTTP редиректа 302 (заголовок Location) - только для метода GET.
2. Автоматическая отправка формы. Поддерживаются методы GET и POST. Веб-сайт предоставляет пользователю страницу, содержащую форму, действие которой перенаправляет на другой ресурс. Форма содержит только скрытые поля и автоматически отправляется при событии onload, поэтому пользователь не видит эту страницу.

Настройки электронного магазина

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

Все указанные параметры, кроме информации о магазине и secret_key, могут переопределяться для каждого конкретного платежа в момент инициализации платежа.

Список ПС

https://www.platron.ru/ps_list.php?pg_salt=123&pg_merchant_id=456&pg_amount=800.45&pg_currency=RUB&pg_sig=aec5f9d237952f83bd05c602d287098d

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>123</pg_salt>
    <pg_merchant_id>456</pg_merchant_id>
    <pg_amount>800.45</pg_amount>
    <pg_currency>RUB</pg_currency>
    <pg_sig>aec5f9d237952f83bd05c602d287098d</pg_sig>
</request>

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

URL запроса

https://www.platron.ru/ps_list.php

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

Обязательные параметры выделены жирным

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9938745</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_system>
        <pg_name>MIXPLATMTS</pg_name>
        <pg_description>Оплата со счета мобильного телефона МТС</pg_description>
        <pg_payment_scenario>offline</pg_payment_scenario>
        <pg_amount_to_pay>808.67</pg_amount_to_pay>
        <pg_amount_to_pay_currency>RUB</pg_amount_to_pay_currency>
        <pg_category>mobile</pg_category>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>CASH</pg_name>
        <pg_description>Наличные: Евросеть, ОСМП, Элекснет</pg_description>
        <pg_payment_scenario>offline</pg_payment_scenario>
        <pg_amount_to_pay>830.00</pg_amount_to_pay>
        <pg_amount_to_pay_currency>RUB</pg_amount_to_pay_currency>
        <pg_category>cash</pg_category>
        <pg_sub_payment_systems>
            <pg_sub_payment_system>
                <pg_sub_name>ELECSNET</pg_sub_name>
                <pg_sub_description>Elecsnet</pg_sub_description>
            </pg_sub_payment_system>
            <pg_sub_payment_system>
                <pg_sub_name>EUROSET</pg_sub_name>
                <pg_sub_description>Евросеть</pg_sub_description>
            </pg_sub_payment_system>
            <pg_sub_payment_system>
                <pg_sub_name>QIWI</pg_sub_name>
                <pg_sub_description>QIWI</pg_sub_description>
            </pg_sub_payment_system>
        </pg_sub_payment_systems>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>WEBMONEYRBANK</pg_name>
        <pg_description>Система WebMoney</pg_description>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_amount_to_pay>810.35</pg_amount_to_pay>
        <pg_amount_to_pay_currency>RUB</pg_amount_to_pay_currency>
        <pg_category>wallet</pg_category>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>YANDEXMONEY</pg_name>
        <pg_description>Система Яндекс-деньги</pg_description>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_amount_to_pay>812.15</pg_amount_to_pay>
        <pg_amount_to_pay_currency>RUB</pg_amount_to_pay_currency>
        <pg_category>wallet</pg_category>
    </pg_payment_system>
    <pg_sig>73daf9d237952f56bd05c602d2878dc2</pg_sig>
</response>

В теге response находится список платежных систем и подпись. Описание каждой платежной системы находится внутри тега pg_payment_system с уникальным идентификатором в атрибуте pg_name – именем платежной системы. Для каждой системы могут быть возвращены параметры:

Ответ на запрос представляет собой XML (в кодировке utf-8), содержащий список доступных для этого магазина платежных систем и их атрибутов. Атрибутами являются сумма и валюта платежа, имя и описание ПС, а также список дополнительных параметров pg_required, обязательных для данной ПС. Так же в ответе присутствует список параметров, которые можно присылать дополнительно для платежных систем pg_additional.

Магазин должен контролировать заполнение этих параметров. Если выбрана платежная система, для которой есть обязательный к заполнению параметр, но этот параметр не передан, то оно будет запрошено у покупателя на сайте www.platron.ru.

Список платежных систем в ответе отсортирован по параметру pg_name, а внутри группы по pg_sub_name. Если платежная система представляет собой группу платежных систем, то список платежных систем, входящих в группу, представлен в теге pg_sub_payment_systems.

Пример построения списка для выбора платежной системы можно увидеть на сайте www.platron.ru, если не передавать идентификатор ПС при инициализации платежа.

Инициализация платежа

Общее

Для создания платежной транзакции (инициализации платежа) магазин должен выполнить два действия:

1. передать данные о платеже Platron
2. передать покупателя в управление Platron

Это возможно сделать двумя способами:

1. передать информацию о платеже через браузер пользователя, при этом одновременно пользователь переходит на сайт Platron.
2. передать информацию о платеже напрямую в Platron, в ответ получить идентификатор платежной транзакции и URL для последующего перенаправления покупателя, а затем перенаправить покупателя на этот URL.

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

Обязательные параметры:

Не обязательные параметры:

Host-To-Host

При прямой передаче данных от магазина в Platron магазин должен посылать данные на URL

URL запроса

https://www.platron.ru/init_payment.php

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>ijoi894j4ik39lo9</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_id>15826</pg_payment_id>
    <pg_redirect_url>
        https://www.platron.ru/payment_params.php?customer=ccaa41a4f425d124a23c3a53a3140bdc15826
    </pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_sig>af8e41a4f425d124a23c3a53a3140bdc17ea0</pg_sig>
</response>

Ответ в случае ошибки:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_error_code>101</pg_error_code>
    <pg_error_description>Empty merchant</pg_error_description>
</response>

В случае получения магазином ответа с pg_redirect_url_type="need data", магазин может не перенаправлять покупателя по полученному URL, а уточнить недостающие параметры у себя на сайте. В этом случае после уточнения параметров и повторного запроса на создание платежной транзакции будет создана новая транзакция.

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <pg_salt>b54a5e50</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_system>
        <pg_name>CONNECTUMUSD</pg_name>
        <pg_description>Оплата картой</pg_description>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_amount_to_pay>1.09</pg_amount_to_pay>
        <pg_amount_to_pay_currency>usd</pg_amount_to_pay_currency>
        <pg_category>bankcard</pg_category>
        <pg_additional source="merchant">pg_user_email</pg_additional>
        <pg_additional source="merchant">pg_user_login</pg_additional>
    </pg_payment_system>
    <pg_sig>c7c1448d92cb00235a1206d1e46e6bad</pg_sig>
</response>

Если для выполнения платежа с использованием определённой платёжной системы покупателю необходимо знать какие-либо дополнительные данные, ответ содержит эти данные в полях pg_required и pg_additional. Поля, передаваемые при проведении платежа через конкретные платёжные системы, можно посмотреть в разделе Справочник дополнительных параметров ПС.

Через браузер пользователя

https://www.platron.ru/payment.php?pg_merchant_id=111&pg_amount=1000&pg_order_id=123&pg_check_url=http://www.shop.ru/check.php&pg_result_url=http://www.shop.ru/result.php&pg_success_url=http://www.shop.ru/thankyou.php&pg_failure_url=http://www.shop.ru/failed.php&pg_description=Ticket+SU1234+Moscow-Berlin+1+Jun+2008&custom_param1=gagaga&custom_param2=gugugu&pg_sig=af8e41a4f425d124a23c3a53a3140bdc17ea0

При передаче информации через браузер пользователя, пользователь должен передаваться методом POST или GET.

URL запроса

https://www.platron.ru/payment.php

В случае ошибки сообщение об ошибке выводится на экран пользователя.

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

Рекуррентные платежи

Рекуррентные платежи доступны:

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

Для использования профиля рекуррентных платежей магазину следует инициализировать платеж обычным способом c передачей дополнительного параметра pg_recurring_start, обозначающий требование создания рекуррентного профиля и указанием платежной системы, поддерживающей рекуррентные платежи, в параметре pg_payment_system ( см. Справочник платежных систем). Номер профиля для повторения платежа будет передан при оповещении о результате платежа в параметре pg_recurring_profile. Продавец также может определить срок действия рекуррентного профиля (этот параметр необязателен, и если не указан, будет использоваться срок действия карты). Если указанный продавцом параметр pg_recurring_lifetime превышает срок действия карты, то срок действия рекуррентного профиля истекает в дату окончания срока действия карты. Перед использованием рекуррентных платежей необходимо обратиться к менеджеру для уточнения деталей.

Повторение платежа

https://www.platron.ru/make_recurring_payment.php?pg_merchant_id=82&pg_recurring_profile=109642&pg_description=example&pg_salt=my_salt&pg_sig=3fe59db16e24d78bfecfd8d72324b83c

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <pg_salt>my_salt</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_id>22241128</pg_payment_id>
    <pg_amount>1</pg_amount>
    <pg_currency>RUB</pg_currency>
    <pg_recurring_profile_id>109642</pg_recurring_profile_id>
    <pg_recurring_profile_expiry_date>2029-01-29 00:00:00</pg_recurring_profile_expiry_date>
    <pg_sig>5b2ff43cfa1b7588e5844484f0843b11</pg_sig>
</response>

Магазин может повторять платежи по рекуррентному профилю в любой момент по своему усмотрению.

URL запроса

https://www.platron.ru/make_recurring_payment.php

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

О результате платежа, Platron оповестит продавца на Result URL

По расписанию

Для рекуррентного профиля можно указать расписание платежей. В этом случае платежи будут совершаться по указанному расписанию автоматически. Указать расписание можно либо в виде шаблона, либо в виде простого списка дат.

Создание расписания

Пример с указанием шаблона.

Для лучшей читаемости в примере не экранированы служебные символы.
https://www.platron.ru/index.php/api/recurring/set-schedule?pg_merchant_id=82&pg_recurring_profile=337146&pg_amount=21.23&pg_template[pg_start_date]=2018-08-15 15:30:00&pg_template[pg_interval]=week&pg_template[pg_period]=2&pg_template[pg_max_periods]=5&pg_salt=salt&pg_sig=5036eda9b1a31d5d8ed825c5d658ad43

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <pg_merchant_id>82</pg_merchant_id>
    <pg_recurring_profile>337146</pg_recurring_profile>
    <pg_amount>12.41</pg_amount>
    <pg_template>
        <pg_start_date>2018-08-15 15:30:00</pg_start_date>
        <pg_interval>week</pg_interval>
        <pg_period>2</pg_period>
        <pg_max_periods>5</pg_max_periods>
    </pg_template>
    <pg_salt>salt</pg_salt>
    <pg_sig>458a8161df06e21bcc6967c44e9965qw</pg_sig>
</request>

Пример со списком дат.

Для лучшей читаемости в примере не экранированы служебные символы.
https://www.platron.ru/index.php/api/recurring/set-schedule?pg_merchant_id=82&pg_recurring_profile=337146&pg_amount=21.23&pg_dates[]=2018-08-15 14:00:00&pg_dates[]=2018-08-15 14:30:00&pg_dates[]=2018-08-15 15:00:00&pg_salt=salt&pg_sig=0d32e1bfb8795a7c2a7ff86973vct5er

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <pg_merchant_id>82</pg_merchant_id>
    <pg_recurring_profile>337146</pg_recurring_profile>
    <pg_amount>12.41</pg_amount>
    <pg_dates>2018-08-15 14:00:00</pg_dates>
    <pg_dates>2018-08-15 14:30:00</pg_dates>
    <pg_dates>2018-08-15 15:00:00</pg_dates>
    <pg_salt>salt</pg_salt>
    <pg_sig>b71988a7cc47ae411d9292a0933944ac</pg_sig>
</request>

URL запроса

https://www.platron.ru/index.php/api/recurring/set-schedule

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

*Для создания расписания необходимо указать либо данные шаблона, либо список дат. Если одновременно будут указаны данные шаблона и список дат, для создания расписания будет использован список дат.

Параметры шаблона (pg_template):

*Период используется в сочетании с интервалом. Например, 1 month означает раз в месяц, 2 week означает раз в две недели.

Ответ при удачном создании расписания.

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_recurring_profile>337146</pg_recurring_profile>
    <pg_salt>salt</pg_salt>
    <pg_sig>a764fb36af2e607ee2e841989adr65ty</pg_sig>
</response>

Закрытие рекуррентного профиля

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

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

https://www.platron.ru/get_status.php?pg_salt=9865&pg_merchant_id=82&pg_payment_id=765432&pg_sig=a1b7ccc945c0a60949f6bd6383f5f768

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>9865</pg_salt>
    <pg_merchant_id>82</pg_merchant_id>
    <pg_payment_id>765432</pg_payment_id>
    <pg_sig>a1b7ccc945c0a60949f6bd6383f5f768</pg_sig>
</request>

Магазин может запрашивать Platron о статусе любого платежа, инициированного магазином. Это может быть полезно, например, в случае если вызов Result URL не был получен магазином из-за временного сбоя связи, а покупатель уже был передан на Success URL, однако статус транзакции магазину еще не известен.

URL запроса

https://www.platron.ru/get_status.php

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

Все параметры обязательные

*Требуется либо pg_payment_id, либо pg_order_id. В случае с pg_order_id, если он не уникальный, то будет выдана информация для последнего платежа с данным order_id.

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

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_id>1234567</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>1</pg_can_reject>
    <pg_create_date>2009-01-12 10:22:30</pg_create_date>
    <pg_result_date>2009-01-12 10:25:07</pg_result_date>
    <pg_payment_system>RUSSIANSTANDARD</pg_payment_system>
    <pg_card_brand>CA</pg_card_brand>
    <pg_card_pan>527594******4984</pg_card_pan>
    <pg_card_hash>022380c107141f7e11f4271d7f6412a715222c32</pg_card_hash>
    <pg_auth_code>014318</pg_auth_code>
    <pg_captured>0</pg_captured>
    <pg_sig>8380d43c7719e6ce48da0c79aa7eb2ba</pg_sig>
    <pg_qr_code>https://www.platron.ru/index.php/api/qr-code/getcustomer=c79a5520e313a8f836bb6fc17d0ffa7c3504513922
    </pg_qr_code>
</response>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_id>1234567</pg_payment_id>
    <pg_transaction_status>pending</pg_transaction_status>
    <pg_can_reject>1</pg_can_reject>
    <pg_create_date>2009-01-12 10:22:30</pg_create_date>
    <pg_accepted_payment_systems>EUROSET,EUROPLAT,QIWI</pg_accepted_payment_systems>
    <pg_sig>8380d43c7719e6ce48da0c79aa7eb2ba</pg_sig>
    <pg_qr_code>https://www.platron.ru/index.php/api/qr-code/getcustomer=c79a5520e313a8f836bb6fc17d0ffa7c3504513922
    </pg_qr_code>
</response>

Все даты записываются в формате YYYY-MM-DD hh:mm:ss.

Клиринг

https://www.platron.ru/do_capture.php?pg_salt=123&pg_merchant_id=456&pg_payment_id=1234567&pg_sig=7f3af9d237952f56bd05c602d2879a3c

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>123</pg_salt>
    <pg_merchant_id>456</pg_merchant_id>
    <pg_payment_id>1234567</pg_payment_id>
    <pg_sig>7f3af9d237952f56bd05c602d2879a3c</pg_sig>
</request>

Магазин может самостоятельно запрашивать клиринг у банка через Platron, если в банке настроено проведение платежей в два шага – авторизация и клиринг.

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

URL запроса

https://www.platron.ru/do_capture.php

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

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

Пример ответа

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>1111</pg_salt>
    <pg_status>ok</pg_status>
    <pg_clearing_refund_id>449312</pg_clearing_refund_id>
    <pg_sig>c38ebf6a6b7f5e30316bc984dc69ce37</pg_sig>
</response>

Отмена счета

До оплаты

https://www.platron.ru/cancel.php?pg_salt=123&pg_merchant_id=456&pg_payment_id=1234567&pg_sig=628e300c3204c8ee398d878a5109b520

<?xml version="1.0" encoding="utf-8"?>
<request>
  <pg_salt>123</pg_salt>
  <pg_merchant_id>456</pg_merchant_id>
  <pg_payment_id>1234567</pg_payment_id>
  <pg_sig>628e300c3204c8ee398d878a5109b520</pg_sig>
</request>

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

URL запроса

https://www.platron.ru/cancel.php

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>ok</pg_status>
    <pg_sig>48caf9d237952f56bd05c602d28762da</pg_sig>
</response>

В случае ошибки:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>200</pg_error_code>
    <pg_error_description>
        transaction not found
    </pg_error_description>
    <pg_sig>ac08f9d237952f5bc4e5c602d2873481</pg_sig>
</response>

Ответ «ok» означает, что заявка на отмену счёта принята. Счёт всё же может быть оплачен, если ПС, в которую был выставлен счёт, не поддерживает операции аннулирования счёта и не делает предварительных запросов на подтверждение возможности проведения платежа.

Если ПС не поддерживает отмену счёта, но поддерживает возврат денежных средств (например, TRANSCRED), Platron делает попытку отмены полученного платежа. В этом случае может взиматься дополнительная плата за операцию отмены платежа.

После оплаты

https://www.platron.ru/revoke.php?pg_salt=123&pg_merchant_id=456&pg_payment_id=1234567&pg_refund_amount=800&pg_description=возврат%20товара&pg_sig=6dd2a9d237952f56bd05c602d2872af8

<?xml version="1.0" encoding="utf-8"?>
<request>
  <pg_salt>123</pg_salt>
  <pg_merchant_id>456</pg_merchant_id>
  <pg_payment_id>1234567</pg_payment_id>
  <pg_refund_amount>800</pg_refund_amount>
  <pg_sig>6dd2a9d237952f56bd05c602d2872af8</pg_sig>
</request>

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

URL запроса

https://www.platron.ru/revoke.php

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>ok</pg_status>
    <pg_sig>48caf9d237952f56bd05c602d28762da</pg_sig>
</response>

В случае ошибки:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>490</pg_error_code>
    <pg_error_description>this transaction can’t be revoked</pg_error_description>
    <pg_sig>4df0f9d237952f56bd05c602d2873ed0</pg_sig>
</response>

Чеки (ФЗ-54)

Перед настройкой необходимо связаться с менеджером.

Создание чека

https://www.platron.ru/receipt.php?pg_merchant_id=123&pg_salt=your_salt&pg_sig=generated_sig&pg_operation_type=payment&pg_payment_id=payment_id&pg_additional_payment_amount=12.23&pg_additional_payment_type=credit&pg_customer_name=customer_name&pg_customer_inn=12345678901&pg_items[0][pg_label]=item1&pg_items[0][pg_price]=1.1&pg_items[0][pg_quantity]=2&pg_items[0][pg_vat]=20&pg_items[0][pg_type]=product&pg_items[0][pg_payment_type]=full_payment&pg_items[0][pg_agent_type]=agent&pg_items[0][pg_agent_name]=name&pg_items[0][pg_agent_inn]=12345678902&pg_items[0][pg_agent_phone]=79999999999

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_merchant_id>123</pg_merchant_id>
    <pg_salt>your_salt</pg_salt>
    <pg_sig>generated_sig</pg_sig>
    <pg_operation_type>payment</pg_operation_type>
    <pg_payment_id>payment_id</pg_payment_id>
    <pg_additional_payment_amount>12.23</pg_additional_payment_amount>
    <pg_additional_payment_type>credit</pg_additional_payment_type>
    <pg_customer_name>customer_name</pg_customer_name>
    <pg_customer_inn>12345678901</pg_customer_inn>
    <pg_items>
        <pg_label>item1</pg_label>
        <pg_price>1.1</pg_price>
        <pg_quantity>2</pg_quantity>
        <pg_vat>20</pg_vat>
        <pg_type>product</pg_type>
        <pg_payment_type>full_payment</pg_payment_type>
        <pg_agent_type>agent</pg_agent_type>
        <pg_agent_name>name</pg_agent_name>
        <pg_agent_inn>12345678902</pg_agent_inn>
        <pg_agent_phone>79999999999</pg_agent_phone>
    </pg_items>
</request>

Формировать данные для чека необходимо сразу после создания операции. Чек в ОФД и покупателю отправится только после успешного завершения операции.

Для возможности тестирования функционала необходимо связаться с курирующим менеджером.

Если оплата производится в иностранной валюте или используется платежная система, которая взимает дополнительную комиссию сверх суммы платежа, чек должен быть выписан после получения уведомления на Result Url об успешном платеже. Данный запрос не работает для заявок на возврат и возвратов без платежа (moneyback) не привязанных к транзакции.

URL запроса

https://www.platron.ru/receipt.php

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

*Требуется либо pg_payment_id, либо pg_order_id. В случае, если pg_order_id не уникальный, то чек будет создан к последнему заказу.

Параметры позиции в чеке:

Если передан хотя бы один из параметров pg_agent, необходимо заполнение всех оставшихся полей.

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

* Новые ставки НДС будут доступны начиная с 01.01.2025. Перед их использованием необходимо убедиться, что ваша онлайн касса их поддерживает.

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

Ответ на запрос представляет собой XML следующего вида в случае успешного выполнения запроса:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_receipt_id>135</pg_receipt_id>
    <pg_salt>salt</pg_salt>
    <pg_sig>60beff140b3c9c6dt87603522cc1c07f</pg_sig>
</response>

В случае ошибки:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>100</pg_error_code>
    <pg_error_description>Incorrect signature</pg_error_description>
    <pg_sig>4df0f9d237952f56bd05c602d2873ed0</pg_sig>
</response>

Статус чека в ОФД

https://www.platron.ru/get_receipt_status.php?pg_merchant_id=82&pg_receipt_id=10000&pg_salt=aaaaaaaaaa&pg_sig=b2c010162d43d2ba98a7f68caee24761

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_merchant_id>82</pg_merchant_id>
    <pg_receipt_id>10000</pg_receipt_id>
    <pg_salt>aaaaaaaaaa</pg_salt>
    <pg_sig>b2c010162d43d2ba98a7f68caee24761</pg_sig>
</request>

URL запроса

https://www.platron.ru/get_receipt_status.php

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

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

Ответ на запрос представляет собой XML следующего вида в случае успешного выполнения запроса:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_receipt_status>ok</pg_receipt_status>
    <pg_fiscal_receipt_number>6</pg_fiscal_receipt_number>
    <pg_shift_number>23</pg_shift_number>
    <pg_receipt_date>2017-04-12 20:16:00</pg_receipt_date>
    <pg_fn_number>1110000100238211</pg_fn_number>
    <pg_ecr_registration_number>0000111118041361</pg_ecr_registration_number>
    <pg_fiscal_document_number>133</pg_fiscal_document_number>
    <pg_fiscal_document_attribute>3449555941</pg_fiscal_document_attribute>
    <pg_salt>aaaaaa</pg_salt>
    <pg_sig>531b7999c74d984fa8c9e1ff029a40d7</pg_sig>
</response>

В случае, если информации по чеку ещё нет:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>ok</pg_status>
    <pg_receipt_status>pending</pg_receipt_status>
    <pg_sig>75ed486aa0dfd5363e2e5a87e8e30634</pg_sig>
</response>

В случае ошибки:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>100</pg_error_code>
    <pg_error_description>Incorrect signature</pg_error_description>
    <pg_sig>4df0f9d237952f56bd05c602d2873ed0</pg_sig>
</response>

Выплаты

Список ПС для выплат

https://www.platron.ru/moneyback_system_list.php?pg_merchant_id=82&pg_salt=aaaaa&pg_sig=0c86434c28fcc71166b28778c961a5d0

Получение списка контрактов с доступными по ним платежными системами

URL запроса

https://www.platron.ru/moneyback_system_list.php

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_contract_list>
        <pg_contract>
            <pg_contract_id>24258</pg_contract_id>
            <pg_account_amout>-30061.6100</pg_account_amout>
            <pg_moneyback_system_list>
                <pg_moneyback_system>
                    <pg_system_name>YANDEXMONEY_O</pg_system_name>
                    <pg_description>Описание</pg_description>
                    <pg_amout>Сумма</pg_amout>
                    <destination_account>Номер кошелька</destination_account>
                </pg_moneyback_system>
                <pg_moneyback_system>
                    <pg_system_name>CONTACT_O</pg_system_name>
                    <pg_description>Описание</pg_description>
                    <pg_amout>Сумма</pg_amout>
                    <bName>Фамилия получателя</bName>
                    <bLastName>Имя получателя</bLastName>
                    <bSurName>Отчество получателя</bSurName>
                </pg_moneyback_system>
            </pg_moneyback_system_list>
        </pg_contract>
    </pg_contract_list>
    <pg_salt>3399407</pg_salt>
    <pg_sig>700466634e329c11f6bbf094ea264eb8</pg_sig>
</response>

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

Запрос на выплату

https://www.platron.ru/create_moneyback.php?pg_merchant_id=82&pg_contract_id=24258&pg_payment_id=22568489&pg_moneyback_system=CONTACT_O&pg_amount=120.00&pg_description=Тестовая_выплата&pg_salt=732343&bName=Фамилия_получателя&bLastName=Имя&bSurName=Отчество получателя&pg_sig=4f22f5a4903738a69e3ac74b96b23d4e

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

Стандартная выплата осуществляется с привязкой к транзакции.

URL запроса

https://www.platron.ru/create_moneyback.php

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

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_moneyback_id>727188</pg_moneyback_id>
    <pg_salt>kdjdope983</pg_salt>
    <pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig>
</response>

Пример ответа в случае ошибки в запросе:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_error_code>100</pg_error_code>
    <pg_description>Описание ошибки</pg_description>
    <pg_salt>kdjdope983</pg_salt>
    <pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig>
</response>

Ответ будет содержать результат попытки создания выплаты. В случае ошибки, появится параметр pg_error_code с номером ошибки и параметр pg_description с описанием ошибки

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

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

Статус выплаты

https://www.platron.ru/get_moneyback_status.php?pg_merchant_id=1234&pg_moneyback_id=72612&pg_salt=f387f3h3&pg_sig=bfc5f9d2379d287052f56bd05c60296e

URL запроса

https://www.platron.ru/get_moneyback_status.php

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>pending</pg_status>
    <pg_salt>kdjdope983</pg_salt>
    <pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig>
</response>

В случае ошибки ответ будет выглядеть следующим образом:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_error_code>200</pg_error_code>
    <pg_description>Отсутствует необходимый параметр</pg_description>
    <pg_salt>kdjdope983</pg_salt>
    <pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig>
</response>

Отмена выплаты

Отмена выплаты доступна в личном кабинете на сайте Platron по ссылке https://www.platron.ru/admin/moneyback_transactions.php

Реестр Операций

Отправка на email

В параметрах магазина есть возможность задать e-mail, на который каждый день будет высылаться реестр платежей по предыдущему дню. Реестр формируется в 0:10 по московскому времени.

Заголовки письма содержат следующую информацию:

1. X-Merchant-ID: Merchant ID, выданный магазину (пример: 14)
2. X-Registry-Date: Дата, на которую составлен реестр, в формате ГГГГ-ММ-ДД (пример: 2009-12-02)
3. Поле «От» письма содержит info@platron.ru
4. Тема письма: Platron report for merchant #id [ГГГГ-ММ-ДД]

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

Реестр высылается в теле письма или во вложении, в зависимости от настроек в личном кабинете, представляет собой набор данных с разделителями «табуляция». Первая строка содержит названия полей. Если поле не определено, две табуляции следуют подряд.

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

Описание полей реестра

Пример реестра

Запрос реестра

https://www.platron.ru/get_registry.php?pg_merchant_id=1234&pg_date=2016-11-15&pg_salt=f387f3h3&pg_sig=bfc5f9d2379d287052f56bd05c60296e

URL запроса

https://www.platron.ru/get_registry.php

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

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

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

В случае успеха будет возвращен такой ответ:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <operation>
        <type>pay</type>
        <payment_type>direct</payment_type>
        <pg_payment_id>28236796</pg_payment_id>
        <order_id>9789932</order_id>
        <description>hotel reservetion description</description>
        <merchant_id>82</merchant_id>
        <payment_system>GDSHOTELWITHRUSSIANSTANDARD</payment_system>
        <bill_amount>5138.0000</bill_amount>
        <amount>0.0000</amount>
        <currency>RUB</currency>
        <bill_cur_symbol>RUB</bill_cur_symbol>
        <op_date>15.11.2016</op_date>
        <op_time>10:26:45</op_time>
        <to_pay>0.0000</to_pay>
        <pg_commission>0.0000</pg_commission>
        <ps_commission>0.0000</ps_commission>
    </operation>
    <pg_salt>f387f3h3</pg_salt>
    <pg_sig>cac84530938b7e51b2d272e1d0212457</pg_sig>
</response>

В случае ошибки ответ будет выглядеть следующим образом:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_error_code>200</pg_error_code>
    <pg_description>Отсутствует необходимый параметр</pg_description>
</response>

См. описание полей файла отправленного на email

Оповещения

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

Пример GET вызова магазина гейтом:

http://store.ru/check.php?pg_salt=8765&pg_order_id=654&pg_payment_id=765432&pg_payment_system=WEBMONEYR&pg_amount=100.00&pg_currency=RUB&pg_net_amount=95.00&pg_ps_amount=100.00&pg_ps_currency=RUB&pg_ps_full_amount=100.80&pg_sig=bfc5f9d237952f56bd05c602d287096e&uservar1=45363456

Пример xml вызова (POST с XML в параметре pg_xml) магазина гейтом:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>8765</pg_salt>
    <pg_order_id>654</pg_order_id>
    <pg_payment_id>765432</pg_payment_id>
    <pg_payment_system>WEBMONEYR</pg_payment_system>
    <pg_amount>100.00</pg_amount>
    <pg_currency>RUB</pg_currency>
    <pg_ps_currency>RUB</pg_ps_currency>
    <pg_ps_amount>100.00</pg_ps_amount>
    <pg_ps_full_amount>100.00</pg_ps_full_amount>
    <uservar1>45363456</uservar1>
    <pg_sig>bfc5f9d237952f56bd05c602d287096e</pg_sig>
</request>

Перед тем как принять деньги от покупателя по счету, платежный гейт может вызвать скрипт магазина Check URL с помощью метода Request Method.

В случае если при инициализации платежа магазином была выбрана кодировка отличная от utf-8, запрос будет производиться в установленной магазином кодировке. Гейт передает информацию о номере и свойствах заказа и ожидает ответ в течение 30 секунд. Отсутствие ответа за указанное время воспринимается как временный отказ от платежа, в этом случае вызов Check URL может быть повторен позже, если он будет снова инициирован платежной системой.

Вызов скрипта Check URL происходит только в случае, если такая возможность поддерживается платежной системой, через которую происходит платеж. Если Check URL не указан или определен пустым в момент инициализции платежа, а в настройках магазина установлен пустым, то шаг проверки возможности совершить платеж пропускается и считается, что магазин согласен принять платеж.

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

Параметры ответа (мерчанта)

Примеры ответов

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>654j8rlvbyuj</pg_salt>
    <pg_status>ok</pg_status>
    <pg_timeout>300</pg_timeout>
    <pg_sig>6e952f52d23770986bd05c6fc5f902db</pg_sig>
</response>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>654j8rlvbyuj</pg_salt>
    <pg_status>rejected</pg_status>
    <pg_description>Срок оплаты заказа истек</pg_description>
    <pg_sig>d2377096e952f5286bd05c602dbfc5f9</pg_sig>
</response>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>654j8rlvbyuj</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>1000</pg_error_code>
    <pg_error_description>database connection failed</pg_error_description>
    <pg_sig>8a417096e952f5286bd05c602dbfc562</pg_sig>
</response>

В случае если магазин подтверждает готовность заказа и правильность суммы, он должен ответить в виде XML со статусом ok.

Статус rejected воспринимается как окончательный отказ, в этом случае параметр pg_description выводится пользователю как причина отказа (если такая возможность поддерживается платежной системой), а счет аннулируется. Магазин должен быть готов к тому, что даже после ответа rejected, тем не менее, Check URL может быть вызван снова (например, в случае если Platron не дождался ответа магазина).

Статус error воспринимается как временный сбой на стороне магазина. Счет остается активным, а запрос о возможности проведения платежа может быть сделан снова, если повторно будет инициирован пользователем. В случае недоступности сервера продавца в момент вызова Check URL или получения ответа, который невозможно интерпретировать, платеж также будет временно отменен.

Результат платежа

Пример GET вызова магазина гейтом, при оплате по обычной платежной системой:

http://store.ru/result.php?pg_salt=0bd68e&pg_order_id=654&pg_payment_id=765432&pg_amount=100.0000&pg_currency=RUB&pg_net_amount=100.00&pg_ps_amount=105.00&pg_ps_full_amount=105.00&pg_ps_currency=RUB&pg_payment_system=INPLATMTS&pg_result=1&pg_payment_date=2008-12-30+23:59:30&pg_can_reject=0&pg_user_phone=79818244116&pg_need_phone_notification=1&pg_user_contact_email=test@test.ru&pg_need_email_notification=1&uservar1=45363456&pg_sig=da61f9d237952f56bd05c602d28780b3

Пример xml вызова (POST с XML в параметре pg_xml) магазина гейтом, при оплате по обычной платежной системой:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>0bd68e</pg_salt>
    <pg_order_id>654</pg_order_id>
    <pg_payment_id>765432</pg_payment_id>
    <pg_amount>100.0000</pg_amount>
    <pg_currency>RUB</pg_currency>
    <pg_net_amount>100.00</pg_net_amount>
    <pg_ps_amount>105.00</pg_ps_amount>
    <pg_ps_full_amount>105.00</pg_ps_full_amount>
    <pg_ps_currency>RUB</pg_ps_currency>
    <pg_payment_system>INPLATMTS</pg_payment_system>
    <pg_result>1</pg_result>
    <pg_payment_date>2008-12-30 23:59:30</pg_payment_date>
    <pg_can_reject>0</pg_can_reject>
    <pg_user_phone>79818244116</pg_user_phone>
    <pg_need_phone_notification>1</pg_need_phone_notification>
    <pg_user_contact_email>test@test.ru</pg_user_contact_email>
    <pg_need_email_notification>1</pg_need_email_notification>
    <uservar1>45363456</uservar1>
    <pg_sig>da61f9d237952f56bd05c602d28780b3</pg_sig>
</request>

Пример GET вызова магазина гейтом, при оплате по карточной платежной системе:

http://store.ru/result.php?pg_salt=0bd68e&pg_order_id=654&pg_payment_id=765432&pg_amount=100.0000&pg_currency=RUB&pg_net_amount=100.00&pg_ps_amount=105.00&pg_ps_full_amount=105.00&pg_ps_currency=RUB&pg_payment_system=RUSSIANSTANDARD&pg_result=1&pg_payment_date=2008-12-30+23:59:30&pg_can_reject=1&pg_card_brand=CA&pg_card_pan=527594******4984&pg_card_hash=022380c107141f7e11f4271d7f6412a715222c32&pg_auth_code=014318&pg_captured=0&pg_user_phone=79818244116&pg_need_phone_notification=1&pg_user_contact_email=test@test.ru&pg_need_email_notification=1&uservar1=45363456&pg_sig=da61f9d237952f56bd05c602d28780b3

Пример xml вызова (POST с XML в параметре pg_xml) магазина гейтом, при оплате по карточной платежной системе:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>0bd68e</pg_salt>
    <pg_order_id>654</pg_order_id>
    <pg_payment_id>765432</pg_payment_id>
    <pg_amount>100.0000</pg_amount>
    <pg_currency>RUB</pg_currency>
    <pg_net_amount>100.00</pg_net_amount>
    <pg_ps_amount>105.00</pg_ps_amount>
    <pg_ps_full_amount>105.00</pg_ps_full_amount>
    <pg_ps_currency>RUB</pg_ps_currency>
    <pg_payment_system>RUSSIANSTANDARD</pg_payment_system>
    <pg_result>1</pg_result>
    <pg_payment_date>2008-12-30 23:59:30</pg_payment_date>
    <pg_can_reject>1</pg_can_reject>
    <pg_card_brand>CA</pg_card_brand>
    <pg_card_pan>527594******4984</pg_card_pan>
    <pg_card_hash>022380c107141f7e11f4271d7f6412a715222c32</pg_card_hash>
    <pg_auth_code>014318</pg_auth_code>
    <pg_captured>0</pg_captured>
    <pg_user_phone>79818244116</pg_user_phone>
    <pg_need_phone_notification>1</pg_need_phone_notification>
    <pg_user_contact_email>test@test.ru</pg_user_contact_email>
    <pg_need_email_notification>1</pg_need_email_notification>
    <uservar1>45363456</uservar1>
    <pg_sig>da61f9d237952f56bd05c602d28780b3</pg_sig>
</request>

В случае если магазин принимает платеж, он должен ответить в виде XML со статусом ok:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>kdjdope983</pg_salt>
    <pg_status>ok</pg_status>
    <pg_description>Товар передан покупателю</pg_description>
    <pg_sig>9bfc5f602d287096ed237952f56bd05c</pg_sig>
</response>

После приема денег от клиента или при невозможности совершить платеж Platron вызывает Result URL магазина и передает на него методом Request Method информацию о результате платежа. В случае если при инициализации платежа магазином была выбрана кодировка отличная от utf-8, запрос будет производиться в установленной магазином кодировке. При получении данного запроса магазин должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject=1 и магазин не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и Platron отзовет платеж (по INPLAT нет возможности отказа от платежа). В этом случае параметр pg_description из ответа магазина показывается пользователю как причина отказа.

Если сервер продавца недоступен в момент вызова Result URL (нет ответа более 30 секунд) или его ответ не удалось интерпретировать, Platron будет предпринимать повторные попытки его вызвать в течение 2 часов, даже если время жизни счета pg_lifetime истечет. Если первая попытка вызова Result URL оказалась неуспешной, то платеж не отменяется, и если платежная система позволяет отказаться от платежа только сразу после платежа, то Platron принимает платеж у платежной системы и в последующих вызовах Result URL не позволяет магазину отказаться от платежа. Магазин должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции (pg_lifetime) истекло.

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

Параметры ответа (мерчанта)

Если магазин отказывается от платежа, и в запросе был передан параметр pg_can_reject=1, магазин должен ответить в виде XML со статусом rejected:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>kdjdope983</pg_salt>
    <pg_status>rejected</pg_status>
    <pg_description>Бронь истекла</pg_description>
    <pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig>
</response>

Статус rejected может быть возвращен магазином только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject=1, в противном случае, вне зависимости от ответа магазина, платеж будет считаться совершенным. Если магазин отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.

Результат клиринга

Пример GET вызова магазина гейтом:

http://store.ru/onCapture.php?pg_salt=gw41b38vc&pg_order_id=2614&pg_payment_id=825941&pg_sig=afaef9d237932f57bd05c602d287df34&uservar1=45363456

Пример xml вызова (POST с XML в параметре pg_xml) магазина гейтом:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>gw41b38vc</pg_salt>
    <pg_order_id>2614</pg_order_id>
    <pg_payment_id>825941</pg_payment_id>
    <uservar1>45363456</uservar1>
    <pg_sig>afaef9d237932f57bd05c602d287df34</pg_sig>
</request>

Если магазин настроен на проведение транзакций по банковским картам в две стадии – авторизация и клиринг, — Platron оповещает магазин об исполнении клиринга сразу после отправки соответствующей команды в банк.

Обычно клиринг выполняется по инициативе магазина, когда магазин дает Platron команду на клиринг (см. раздел Клиринг), однако если магазин не дал эту команду в течение срока, указанного в настройках магазина (не более 5 дней), после авторизации, Platron самостоятельно отправляет команду на клиринг в банк.

Для оповещения магазина о клиринге Platron вызывает скрипт магазина Capture URL с помощью метода Request Method. Platron передает информацию о номере заказа и ожидает ответ в течение 30 секунд. Если сервер продавца недоступен в момент вызова Capture URL (нет ответа более 30 секунд) или его ответ не удалось интерпретировать, Platron будет предпринимать повторные попытки его вызвать в течение 2 часов.

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

Параметры ответа (мерчанта)

Пример ответа магазина:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>eyhfh42za22h</pg_salt>
    <pg_status>ok</pg_status>
    <pg_sig>ea362f52d23770986bd05c6fc5f9427d</pg_sig>
</response>

Возврат платежа

В случае полного или частичного возврата платежа на стороне Platron или платежной системы платежный гейт вызывает скрипт магазина Refund URL с помощью метода Request Method. Запрос будет производиться в кодировке, установленной магазином при инициализации платежа, по умолчанию utf-8. Гейт передает информацию о номере и свойствах заказа и ожидает ответ в течение 30 секунд. Если сервер продавца недоступен в момент вызова Refund URL (нет ответа более 30 секунд) или его ответ не удалось интерпретировать, Platron будет предпринимать повторные попытки его вызвать в течение 2 часов.

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

Параметры ответа (мерчанта)

Возврат покупателя на сайт продавца

Пример GET или AUTOGET перехода в случае успеха:

https://store.ru/success.php?pg_salt=54c6a8786f19e&pg_order_id=654&pg_payment_id=765432&uservar1=45363456&pg_card_brand=CA&pg_card_pan=527594******4984&pg_card_hash=022380c107141f7e11f4271d7f6412a715222c32&pg_auth_code=014318&pg_auth_code=014318&pg_sig=20bcedd8320ac8868b97706abedec0b4

После завершения платежа в online платежной системе покупатель перенаправляется на страницу продавца Success URL или Failure URL, в зависимости от результата платежа. Перенаправление происходит методом Success URL Method или Failure URL Method, указанным при инициации платежа.

В случае оплаты через offline платежную систему возврат покупателя на сайт магазина не происходит.

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

Если Success URL или Failure URL уже содержат параметры в query string, то дополнительные параметры pg_order_id, pg_payment_id и пользовательские переменные продавца дописываются в конец query string. Магазин должен следить за тем, чтобы имена дополнительных параметров не совпадали с именами уже имеющимися параметров.

Необходимо четко понимать разницу между Result URL и Success URL. Result URL вызывается напрямую с сервера Platron, в то время как Success URL вызывается браузером пользователя, когда пользователь перенаправляется обратно на сайт магазина.

Неправильно использовать Success URL как единственный способ узнать о завершении оплаты, потому что пользователь может по разным причинам (например, прерывание связи) не дойти до Success URL после оплаты. Самый надежный способ узнавать о завершении платежа – это реализовать Result URL, который обязуется вызывать повторно в течение 2 часов после оплаты, если первая попытка по любым причинам не удалась.

Тестирование

Все новые магазины первоначально находятся в тестовом режиме. После завершения тестирования и отправки магазином в Platron подписанного Акта о подключении, его можно скачать по ссылке https://www.platron.ru/admin/documents.php, администрация Platron переводит магазин в рабочий режим.

Для отладки интеграции с Platron в тестовом режиме необходимо выбирать pg_payment_system=TEST или pg_payment_system=TESTCARD, в этом случае будет использоваться фиктивная тестовая ПС, ведущая расчеты в фиктивной валюте «тестики», а реальные средства переводиться не будут. В тестовом режиме можно использовать только тестовые платежные системы, а в рабочем режиме, наоборот, оплата тестовыми платежными системами невозможна. Для тестирования интеграции платежной системы TESTCARD, необходимо использовать валюту — RUB.

После перехода магазина в рабочий режим можно создавать отдельные транзакции в тестовом режиме, передавая параметр pg_testing_mode в запросах на создание платежа, повторение рекуррентного платежа и на получение списка платежных систем. Значение pg_testing_mode=1 включает тестовый режим для одной конкретной транзакции. Если сам магазин находится в тестовом режиме, то значение переданного флага pg_testing_mode не имеет значения. Включение и выключение тестового режима в настройках магазина осуществляется только администрацией Platron.

При заполнении данных для оплаты можно указать следующие специальные номера телефона:

• 79009999999 — для автоматической удачной оплаты
• 79008888888 — для автоматической неудачной оплаты

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

Для эмуляции перехода пользователя на страницу прохождения 3DS при использовании платежной системы TESTCARD, необходимо попросить включить авторизацию клиента по 3DS у вашего менеджера.

В тестовой платежной системе возможно тестирование клиринга, PCI DSS, длинной записи и рекуррентных платежей.

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

• 5285 0000 0000 0005 действительна до 01/2025
• 4276 0000 0000 0009 действительна до 01/2025
• 5241 0000 0000 0016 действительна до 01/2025
• 5326 0000 0000 0006 действительна до 01/2025
• 4257 0000 0000 0002 действительна до 01/2025

Анти-фрод

Задача. Интегрироваться к системе Platron только для анти-фрод решения.

Решение. Интеграция производится стандартным способом. Для передачи карточных реквизитов, магазин должен иметь сертификат PCI DSS. Дополнительную документацию по интеграции с наличием PCI DSS можно запросить у менеджера.

1. Для создания транзакции необходимо использовать метод инициализации платежа — Host-to-host
2. При создании транзакции должна быть указана платежная система ANTIFRAUD (pg_payment_system=ANTIFRAUD).
3. В ответ (см. Результат платежа или Статус платежа) будет отдаваться дополнительный параметр fraud_filter_action

Возможные варианты ответа:

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

Для магазинов сегмента e-travel, в дополнительных полях могут передаваться следующие данные:

Маркетплейс

Маркетплейс подразумевает выплату денежных средств на счета юридических лиц. Инициирование выплаты денежных средств юридическому лицу происходит по схеме, описанной в разделе Запрос на выплату.

Для выплаты в пользу юридического лица используется платежная система BANKTRANSFER_WALLET_ONE_LEGAL.

В случае выплаты по платежной системе BANKTRANSFER_WALLET_ONE_LEGAL, параметр pg_description добавляется в платежное поручение в качестве описания платежа. Максимальное количество символов — 90.

Зачисление денежных средств на счет для выплат происходит по стандартному протоколу Инициализации платежа.

Справочники

Платежные системы

Боевые платежные системы

Тестовые платежные системы

Банковские карты

Тестовые платежные системы

Доп. параметров ПС

Валюты

В настоящий момент поддерживаются все валюты, которые имеют официальный обменный курс ЦБ РФ.

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

Каждая платежная транзакция может находиться в одном из следующих состояний:

Коды ошибок

*Чтобы проанализировать причины возникшей ошибки подписи, можно воспользоваться страницей «Проверка подписи к запросу» в Личном Кабинете.

Причины отказа

Системы для выплат и параметры

BANKTRANSFER_WALLET_ONE_LEGAL

Сперва все получатели должны быть зарегистрированы в системе через менеджера.

TEST

Статусы выплат