Переводы

Отправка запросов, если не указано иное, осуществляется с заголовком

«Content‑Type: application/x‑www‑form‑urlencoded».

Порядок следования параметров в запросах не важен.

Регистр символов в url‑адресах и параметрах запросов — важен.

Ответ на запрос передается в формате JSON, кодировка UTF‑8.

Ответы API сервиса могут содержать незадокументированные поля. При обработке ответов такие поля должны игнорироваться клиентским кодом.

StartCreditSession

Запрос инициализации перевода. Выполняется перед перенаправлением пользователя на страницу платежного шлюза Payler.

URL запроса: https://{host}.payler.com/cgapi/StartSession

Доступно для: cgapi

Метод отправки запроса: POST

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

Название	Тип	R/O	Описание
key	A..100	R	Идентификатор мерчанта. Выдается с параметрами доступа
password	A..100	R	Пароль мерчанта для проведения операций. Выдается с параметрами доступа
order_id	A..100	R	Идентификатор перевода в системе мерчанта. Для каждого перевода (сессии) требуется использовать уникальный идентификатор. Только печатные ASCII-символы
session_type	N1	O	Тип сессии относительно сохранения карточных данных. При сохранении карточных данных последующие переводы можно совершать просто выбором нужной карты. Если этот параметр равен 1, то нужно передавать также и customer_id. 0 — обычная страница перевода, без сохранения карточных данных, 1 — показать пользователю список сохранённых карт и возможность выбора из списка или ввода полных карточных данных для перевода на карту не из списка. По умолчанию — 0
customer_id	A..100	O	Идентификатор пользователя. Если параметр session_type равен 1, то на странице перевода будет возможность выбрать ранее сохранённую карту (для данного пользователя) или ввести новую. Генерируется мерчантом
amount	N	R	Сумма перевода в минимальной денежной единице (копейки, центы и т. д.)
product	A..256	O	Описание перевода.
template	A..100	O	Используемый шаблон страницы перевода, заданный мерчантом. При отсутствии используется шаблон «по умолчанию»
lang	A2	O	Предпочитаемый язык платёжной формы. en — английский; ru — русский. По умолчанию — ru
userdata	A..1000	O	Пользовательские данные. Можно передать в этой строке любую информацию, которую нужно сохранить вместе с переводом, а потом получить её с помощью метода GetAdvancedStatus
email	A..100	O	Адрес электронной почты пользователя
pay_page_param_*	A..100	O	Параметры для отображения на странице перевода. Можно передать любые параметры, начинающиеся с pay_page_param_, а потом отобразить их на странице оплаты. Для этого необходимо использовать шаблон страницы (см. параметр template)
pay_page_param_addtoreport3	A	O	При сплитовании: суммы переводов для каждого получателя в минимальной денежной единице (копейки, центы и т. д.) через запятую
pay_page_param_addtoreport4	A	O	При сплитовании: ID получателей через запятую. Регистрируются через службу технической поддержки

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

Название	Тип	R/O	Описание
order_id	A..100	R	Идентификатор перевода в системе мерчанта. Соответствует переданному в запросе
amount	N	R	Сумма перевода в минимальной денежной единице (копейки, центы и т. д).
session_id	A..100	R	Идентификатор платёжной сессии

Пример ответа на успешный запрос:

{
         "amount": 30000,
         "session_id": "b088175c-eca6-4317-aa84-74de5080ca20",
         "order_id": "d1434908-7260-483e-8254-fa43af1b835d"
}

CreditGate

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

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

URL запроса: https://{host}.payler.com/cgapi/Credit

Доступно для: cgapi

Метод отправки запроса: GET

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

Название	Тип	R/O	Описание
session_id	A..100	R	Идентификатор платёжной сессии. Содержится в ответе на запрос StartCreditSession

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

Адрес возврата пользователя (URL страницы) — указывается мерчантом заранее в виде URL. Пример адреса возврата: http://myshop.ru/complete?order_id={order_id}

Для получения результатов транзакции следует использовать данные, полученные в рамках запроса статуса транзакции (см. метод GetStatus).

Необходимо учесть, что возврат на указанный URL может быть сделан несколько раз, например когда пользователь запутался, нажимал кнопку «Back» в браузере и несколько раз вводил свои карточные данные для перевода. Если пользователь ошибочно попытается повторно осуществить перевод в рамках одной сессии, то ему будет показано сообщение о том, что перевод уже произведен и сделано перенаправление на сайт мерчанта.

CreditMerchant

Запрос перевода денежных средств на карту пользователя.

Формат запроса: https://{host}.payler.com/cmapi/Credit

Доступно для: cmapi

Метод отправки запроса: POST

Использование данного метода предполагает обязательное соответствие системы мерчанта требованиям PCI DSS.

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

Название	Тип	R/O	Описание
key	A..100	R	Идентификатор мерчанта. Выдается с параметрами доступа
password	A..100	R	Пароль мерчанта для проведения операций. Выдается с параметрами доступа
order_id	A..100	R	Идентификатор перевода в системе мерчанта. Для каждого перевода нужен свой уникальный идентификатор. Только печатные ASCII‑символы
amount	N	R	Сумма перевода в минимальной денежной единице (копейки, центы и т. д.)
product	A..256	O	Описание перевода.
currency	A3	О	Валюта платежа (см. Поддерживаемые валюты). По умолчанию — RUB
card_number	A..19	R	Номер карты. Десятичные цифры без разделителей [0–9]
card_holder	A..100	О	Имя держателя карты. Латинские символы, десятичные цифры, символ пробела [a–zA–Z0–9 ]
lang	A2	О	Предпочитаемый язык ответов сервера. en — английский; ru — русский. По умолчанию — ru
email	A..100	R	Адрес электронной почты пользователя
userdata	A..1000	O	Пользовательские данные. Можно передать в этой строке любую информацию, которую нужно сохранить вместе с переводом, а потом получить её с помощью метода GetAdvancedStatus
user_entered_params	A..100	O	Можно указать дополнительные поля для перевода, начинающиеся с user_entered_. Затем все эти поля возвращаются в GetAdvancedStatus в поле user_entered_params
pay_page_param_addtoreport3	A	O	При сплитовании: суммы переводов для каждого получателя в минимальной денежной единице (копейки, центы и т. д.) через запятую
pay_page_param_addtoreport4	A	O	При сплитовании: ID получателей через запятую. Регистрируются через службу технической поддержки
expired_year	N2	R/O*	Год окончания срока действия карты
expired_month	N2	R/O*	Месяц окончания срока действия карты
secure_code	A	R/O*	Код подлинности карты (CVC2/CVV2). Десятичные цифры [0–9]

R/O

Обязательность параметров зависит от конкретного банка-эквайера. Необходимость передачи уточняется индивидуально для каждого мерчанта.

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

Название	Тип	R/O	Описание
order_id	A..100	R	Идентификатор оплачиваемого заказа в системе мерчанта. Соответствует переданному в запросе
amount	N	R	Сумма в минимальной денежной единице (копейки, центы и т. д.)
card_holder	A..100	R	Имя держателя карты. Соответствует переданному в запросе
card_number	A..19	O	Маскированный номер карты, с помощью которой осуществлен перевод
status	A	R	Статус перевода

Пример ответа на успешный запрос:

{
         "amount": 100,
         "card_number": "555555xxxxxx5599",
         "card_holder": "test",
         "order_id": "19",
         "status": "Pending"
}

После совершения запроса CreditMerchant требуется вызвать запрос GetStatus для получения актуального статуса операции.

RepeatCredit

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

URL запроса: https://{host}.payler.com/cgapi/RepeatCredit

Доступно для: cgapi

Метод отправки запроса: POST

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

Название	Тип	R/O	Описание
key	A..100	R	Идентификатор мерчанта. Выдается с параметрами доступа
password	A..100	R	Пароль мерчанта для проведения операций через Credit Gate API. Выдается с параметрами доступа
order_id	A..100	R	Идентификатор перевода в системе мерчанта. Для каждого перевода нужен свой уникальный идентификатор. Только печатные ASCII‑символы
customer_id	A..100	O	Идентификатор пользователя. Генерируется мерчантом
amount	N	R	Сумма перевода в минимальной денежной единице (копейки, центы и т. д.)
product	A..256	O	Описание перевода.
currency	A3	O	Валюта платежа (см. Поддерживаемые валюты). По умолчанию — RUB
card_id	A..100	R	Идентификатор карты, на которую будет осуществлен перевод
lang	A2	O	Предпочитаемый язык ответов сервера. en — английский; ru — русский. По умолчанию — ru
userdata	A..1000	O	Пользовательские данные. Можно передать в этой строке любую информацию, которую нужно сохранить вместе с платежом, а потом получить её с помощью метода GetAdvancedStatus
pay_page_param_*	A..100	O	Можно передать любые параметры, начинающиеся с pay_page_param_.

Параметр currency

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

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

Название	Тип	R/O	Описание
order_id	A..100	R	Идентификатор перевода в системе мерчанта. Соответствует переданному в запросе
amount	N	R	Сумма в минимальной денежной единице (копейки, центы и т. д.)
card_holder	A..100	O	Имя держателя карты. Соответствует переданному в запросе
card_number	A..19	R	Маскированный номер карты, с помощью которой осуществлен перевод
status	A	R	Статус перевода

Пример ответа на успешный запрос:

{
         "amount": 100,
         "card_number": "555555xxxxxx5599",
         "card_holder": "test",
         "order_id": "19",
         "status": "Pending"
}

Если статус перевода имеет значение «Pending», то запрос статуса следует повторять до изменения статуса. Частоту запроса изменять в геометрической прогрессии. После совершения запроса RepeatCredit требуется вызвать запрос GetStatus для получения актуального статуса операции.

GetBalance

Запрос списка балансов.

URL запроса: https://{host}.payler.com/{api}/v1/GetBalance

Доступно для: cgapi, cmapi

Метод отправки запроса: POST

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

Название	Тип	R/O	Описание
key	A..100	R	Идентификатор мерчанта. Выдается с параметрами доступа

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

Название	Тип	R/O	Описание
balance	Ar	R	Баланс в минимальных единицах валюты
name	A	R	Наименование счета
currency	A3	R	Код валюты
remain	N	R	Остаток

Пример ответа на успешный запрос:

{
         "balance": [
         {
        "name": "Card (Euro)",
        "currency": "EUR",
        "remain": 0
         },
         {
        "name": "Card (United States Dollar)",
        "currency": "USD",
         "remain": 0
         },
         {
        "name": "Card (Russian Ruble)",
        "currency": "RUB",
         "remain": 30000
         },
         {
        "name": "Qiwi (Russian Ruble)",
        "currency": "RUB",
        "remain": 7000
         }
         ]
}