Отправка формы или шага формы на сервер

Формат запроса

Адрес для отправки формы содержится в заголовке Location ответа на запрос описания формы или ответа на отправку данных формы предыдущего шага многошаговой формы.

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

Данные следует отправлять методом POST, Сontent-Type: application/x-www-form-urlencoded, кодировка символов — UTF-8.

Запрос должен содержать следующие параметры:

  • содержимое всех видимых UI-контролов формы;
  • содержимое блока hidden_fields, если он присутствует в описании формы.
Примечание. Если UI-контрол формы видимый, необязательный и покупатель ничего в него не ввел — в запрос добавляется имя поля контрола и пустое значение. Таким же образом ведут себя веб-браузеры.

Запрос может содержать следующие HTTP-заголовки:

Заголовок Описание
Accept-Language Код языка, на котором клиент хочет получить описание формы в соответствии с:

RFC-5646: Tags for Identifying Languages

IANA Language Subtag Registry

Возможные значения:

  • ru — русский;
  • en — английский.

По умолчанию: русский.

Accept-Encoding

Указание по поддержке клиентом сжатия трафика. Поддерживаются значения:

По умолчанию: сжатие трафика не применяется.

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

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

Возможные HTTP-коды ответа:

HTTP-код ответа Описание
200 OK Данные, введенные покупателем, проверены успешно; это последний шаг формы. Ответ содержит список параметров для проведения оплаты.
300 Multiple Choices Данные, введенные покупателем, проверены успешно; присутствует следующий шаг формы. Ответ содержит описание следующего шага формы оплаты. Адрес для отправки следующего шага формы указан в HTTP-заголовке Location.
400 Bad Request Клиент указал неверные данные в полях формы. Ответ содержит список ошибок проверки данных формы и описание текущего шага формы с предзаполненными покупателем значениями. Адрес для повторной отправки формы указан в HTTP-заголовке Location. Клиенту следует исправить данные формы и отправить её повторно.
404 Not Found Запрошенная форма оплаты не существует или запрещена к использованию. Тело ответа отсутствует.
500 Internal Server Error Сервис временно недоступен по техническим причинам.

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

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

Формат ответа со списком параметров для проведения оплаты
{
  "params": {
    "param1": "value1",
    "param2": "value2",
    ...
    "paramN": "valueN"
  }
}

Список ошибок проверки данных, введенных покупателем

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

Если найдены ошибки, сервер отдает в ответе:

  • описание текущего шага формы с предзаполненными значениями полей, введенными покупателем;
  • список ошибок в блоке error.

Каждый элемент списка ошибок содержит:

Поле Описание
name Наименование поля, которое содержит недопустимое значение. Если ошибка не может быть отнесена к конкретному полю формы, этот параметр отсутствует.
alert Текст сообщения об ошибке.

Формат ответа со списком ошибок проверки данных введенных покупателем:

{
  ... описание текущего шага формы ...
  "form": [
    ...
  ],
 "error": [
    {
      "name": "field1",
      "alert": "Сообщение об ошибке"
    },
    ...
    {
      "name": "fieldN",
      "alert": "Сообщение об ошибке"
    }
    ...
    {
      "alert": "Сообщение об ошибке, которое не может отнесено к конкретному полю формы"
    }
  ]
}

Примеры

Пример запроса
POST /api/showcase/validate/5551/step_INN_3038 HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded
Content-Length: 115
Accept-Language: ru
Accept-Encoding: gzip

supplierInn=4704020508&ShopID=13423&ShopArticleID=35241&ShowCaseID=3005&ContractTemplateID=524867&budgetDocNumber=0
Введенные покупателем данные проверены успешно, возвращены параметры для проведения оплаты
HTTP/1.1 200 ОК
Content-Type: application/json
Content-Length: 197
Cache-Control: no-cache
 
{"params":{"pattern_id":"5506","ContractTemplateID":"525923","sc_param_scid":"5506","netSum":"2","ShopArticleID":"71747","sc_param_step":"","ShopID":"14061","ShowCaseID":"6101","skypename":"test"}}
Введенные покупателем данные содержат ошибки, возвращен документ, содержащий причину ошибки
HTTP/1.1 400 Bad Request
Location: https://money.yandex.ru/api/showcase/validate/5506/
Content-Type: application/json
Content-Length: 733
Cache-Control: no-cache                                                           
 
{"title":"Skype","form":[{"type":"group","layout":"VBox","items":[{"type":"text","name":"FormComment","value":"Skype","label":"Название","required":false,"readonly":false},{"type":"text","name":"skypename","label":"Логин в Skype","required":true,"readonly":false},{"type":"amount","name":"netSum","value":"2","label":"Сумма","required":true,"readonly":false,"min":0.01,"max":375,"currency":"EUR"}]},{"type":"submit","label":"Заплатить"}],"money_source":["wallet","cards","payment-card","cash"],"hidden_fields":{"ContractTemplateID":"525923","sc_param_scid":"5506","netSum":"2","ShopArticleID":"71747","sc_param_step":"","ShopID":"14061","ShowCaseID":"6101"},"error":[{"name":"skypename","alert":"Пожалуйста, укажите логин в Skype"}]}