Таблица 3.2.1. Возможные HTTP-коды ответа
HTTP-код
|
Описание
|
200 OK
|
Запрос принят к обработке. Отправлен ответ в соответствии с настоящим протоколом. MIME-тип: application/pkcs7-mime.
|
400 Bad Request
|
Запрос не принят к обработке. Тело запроса испорчено, сервер не смог прочитать или разобрать запрос.
Возможные причины:
запрос невозможно разобрать;
неверный MIME-тип (Content-Type).
|
403 Forbidden
|
Сертификат Контрагента не зарегистрирован в Системе, либо в настоящий момент шлюз отключен.
|
500 Internal Server Error
|
Технические проблемы Системы. Обратитесь в службу поддержки.
|
501 Not Implemented
|
Запрос отправлен методом, отличным от POST.
|
Типы данных
Таблица 3.3.1. Определения типов данных протокола
Тип
|
Описание
|
xs:int
|
32-bit целое знаковое число. Int32, определенный в стандарте: http://www.w3.org/TR/xmlschema-2/#int.
|
xs:long
|
64-bit целое знаковое число. Int64, определенный в стандарте: http://www.w3.org/TR/xmlschema-2/#long.
|
xs:decimal
|
Десятичное число с фиксированной точкой, определенное в стандарте: http://www.w3.org/TR/xmlschema-2/#decimal.
|
xs:string
|
Текстовая строка, определенная в стандарте: http://www.w3.org/TR/xmlschema-2/#string.
|
xs:normalizedString
|
Текстовая строка, определенная в стандарте: http://www.w3.org/TR/xmlschema-2/#normalizedString.
|
xs:dateTime
|
Временная метка в формате согласно рекомендациям:
http://www.w3.org/TR/xmlschema-2/#dateTime
ISO8601:2004
Формат определяется как:
YYYY-MM-DDThh:mm:ss.fZZZZZ
Расшифровка формата:
YYYY
|
год, точно 4 цифры
|
MM
|
месяц, точно 2 цифры (01=январь и т.д.)
|
DD
|
день месяца, точно 2 цифры (от 01 до 31)
|
T
|
латинский символ «T», должен быть в верхнем регистре
|
h
|
часы, точно 2 цифры (24-часовой формат, от 00 до 24)
|
mm
|
минуты, точно 2 цифры (от 00 до 59)
|
ss
|
секунды, точно 2 цифры (от 00 до 59)
|
f
|
дробная часть секунды (от одной до 6 цифр),
может отсутствовать, в этом случае следует опускать и разделитель «.»
|
ZZZZZ
|
описатель временной зоны, обязательный параметр, может принимать значения:
Z – UTC, символ "Z" должен быть в верхнем регистре;
+hh:mm или -hh:mm – смещение относительно UTC (показывает, что указано локальное время, которое на данное число часов и минут опережает или отстает от UTC)
|
Примеры:
2011-07-01T19:00:00.000+04:00 — 19 часов 00 минут 1 июля 2011 года, часовой пояс Санкт-Петербурга (Москвы) — UTC + 4 часа.
|
xs:date
|
Дата в формате, согласно стандарту http://www.w3.org/TR/xmlschema-2/#date.
Формат определяется как:
YYYY-MM-DD
Расшифровка формата:
YYYY
|
год, точно 4 цифры
|
MM
|
месяц, точно 2 цифры (01=январь и т.д.)
|
DD
|
день месяца, точно 2 цифры (от 01 до 31)
|
Примеры:
2011-07-01 — 1 июля 2011 года.
|
ClientTransactionNumber
|
Уникальный идентификатор операции. Должен быть уникальным для Контрагента на протяжении всей истории операций. Значением параметра должна быть строка длиной от 1 до 24 символов, содержащая символы, принадлежащие множеству значений: 0-9 A-Z a-z . , \ | / - + = # ~ ( ) { } [ ] : ; Рекомендуемые значения: целое положительное линейно нарастающее число в десятичной системе счисления.
|
YMAccount
|
Идентификатор получателя перевода, строка десятичных цифр длиной до 33 символов.
В качестве идентификатора может использоваться:
Счет пользователя в Системе (вида 4100175017397; длина существующих в Системе Счетов на данный момент варьируется от 11 до 16 цифр);
номер телефона пользователя, привязанный к Счету в Системе (допускаются номера российских операторов, рекомендуемое представление – 10-значные номера вида 9217575400, без дополнительных символов и пробелов);
код платежа в ООО «Яндекс» (все номера, начинающиеся с «50», «51»).
|
CurrencyAmount
|
Сумма. Положительное десятичное число с фиксированной точкой, кол-во цифр после точки точно равно двум.
|
CurrencyCode
|
Код валюты. Возможные значения:
643 — рубль Российской Федерации;
10643 — тестовая валюта (демо-рублики демо-системы «Яндекс.Деньги»).
|
Операции протокола
Зачисление переводов (makeDeposition).
С помощью данной операции ИС Контрагента информирует Систему о принятом переводе.
Важно! Необходимо осуществлять проверку возможности зачисления перевода (операция testDeposition) до принятия средств от клиента. Запрос testDeposition позволяет проверить возможность зачисления указанной суммы получателю, в том числе корректность и существование идентификатора пользователя (номера счета или телефона), лимиты и отсутствие запретов на проведение операции. При приеме запроса testDeposition зачисление перевода не производится.
Адрес операции проверки возможности зачисления перевода: https://server:port/webservice/deposition/api/testDeposition
Адрес операции зачисления перевода:
https://server:port/webservice/deposition/api/makeDeposition
Правила формирования и обработки запросов на зачисление переводов:
Каждое зачисление должно быть сформировано с уникальным значением идентификатора (clientOrderId).
Если на операцию «зачисление» получен ответ «Успех» (status=0), то перевод зачислен успешно.
Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и остальные параметры запроса, кроме requestDT, совпадают с предыдущей попыткой, то Система вернет результат обработки ранее отправленного запроса.
Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и какие-либо параметры, кроме requestDT, имеют отличные от первой попытки значения, то Система отвергает такой запрос и возвращает в ответе status=3, error=26.
Система обрабатывает полученный запрос немедленно. В случае если запрос невозможно обработать в течение нескольких секунд, возвращается ответ «в процессе обработки» (status=1). В этом случае результат операции неизвестен, и ИC следует повторить запрос с теми же данными для получения окончательного ответа. Рекомендуется следующий режим повтора: первый повтор через 1 минуту, следующие три с промежутком в 5 минут, далее не более одного раза в 30 минут. Аналогичный режим повтора рекомендуется в случае неполучения ответа от Системы или получения ответа HTTP status 500.
При неполучении ответа от Системы, а также при нечетком ответе (например: HTTP status 500) ИС Контрагента следует повторить запрос с теми же данными для получения окончательного ответа. Рекомендуется следующий режим повтора: первый повтор через 1 минуту, следующие три с промежутком в 5 минут, далее не более одного раза в 30 минут.
Статус транзакции, находящейся в обработке (status=1), может измениться как на «успех», так и на «отвергнут».
Если перевод отвергнут Системой, то в ответе возвращается status=3 и error= с расшифровкой причины отказа. В некоторых случаях может присутствовать поле techMessage, содержащее дополнительную поясняющую информацию в виде текста произвольного формата. Этот текст предназначен для анализа техническими специалистами и не должен отображаться в каком-либо интерфейсе пользователя.
Если перевод отвергнут с ошибкой status=3 error=45, Контрагенту необходимо перечислить принятые переводы на расчетный счет Системы, убедиться, что баланс увеличился (отправив запрос баланса), и провести переводы с НОВЫМИ идентификаторами операций (clientOrderId).
Ошибка status=3 error=21 означает, что запрашиваемая операция запрещена для данного Контрагента (см. раздел 2 «Параметры подключения Контрагента»).
Формат запросов ИС
Таблица 4.1.1.1. Параметры запроса операций testDeposition, makeDeposition (все параметры обязательные, кроме отмеченных символом «*»)
Параметр
|
Тип
|
Описание
|
clientOrderId
|
ClientTransactionNumber
|
Идентификатор операции. Должен быть уникальным для Контрагента на протяжении всей истории операций. Рекомендуемые значения: целое положительное число в десятичной системе счисления.
|
requestDT
|
xs:dateTime
|
Дата и время формирования запроса операции на стороне ИС, по часам Контрагента.
|
dstAccount
|
YMAccount
|
Идентификатор получателя перевода, например:
4100175017397
9217575400
5007266583
|
amount
|
CurrencyAmount
|
Сумма перевода, например: 12.34
|
currency
|
CurrencyCode
|
Код валюты перевода. Возможные значения:
643 — рубль Российской Федерации;
10643 — тестовая валюта (демо-рублики демо-системы «Яндекс.Деньги»).
|
agentId
|
xs:long
|
Идентификатор Контрагента. Выдается Системой.
|
subAgentId (*)
|
xs:long
|
Уникальный идентификатор канала приема переводов. Указывается только в случае разделения переводов по нескольким каналам. Выдается Системой.
|
contract
|
xs:normalizedString, до 128 символов
|
Основание для зачисления перевода.
|
Пример запроса проверки возможности зачисления:
clientOrderId="12345"
requestDT="2011-07-01T20:38:00.000Z"
dstAccount="410011234567"
amount="10.00"
currency="643"
contract="Выигрыш в игре Сфера"/>
Пример запроса проверки возможности зачисления c указанием subAgentId:
subAgentId="456"
clientOrderId="12345"
requestDT="2011-07-01T20:38:00.000Z"
dstAccount="410011234567"
amount="10.00"
currency="643"
contract="Выигрыш в игре Сфера"/>
Пример запроса на зачисление:
clientOrderId="12345"
requestDT="2011-07-01T20:38:00.000Z"
dstAccount="410011234567"
amount="10.00"
currency="643"
contract="Выигрыш в игре Сфера"/>
Пример запроса на зачисление c указанием subAgentId:
subAgentId="456"
clientOrderId="12345"
requestDT="2011-07-01T20:38:00.000Z"
dstAccount="410011234567"
amount="10.00"
currency="643"
contract="Выигрыш в игре Сфера"/>
Формат ответов Системы
|
