Описание формы
Описание формы оплаты — это JSON-документ в кодировке UTF‑8.
Примеры форм
Заглавные поля формы
Блок title
Наименование оплачиваемого товара. Тип поля:
string
.Пример
JSON
"title": "Ростелеком Северо-Запад"
Блок hidden_fields
Служебные поля формы. Тип поля:
object
, набор ключ-значение.Клиент должен прозрачно передать этот набор полей при отправке данных формы на сервер.
Пример
JSON
"hidden_fields": { "targetcurrency": "643", "ShopArticleID": "35241" }
Блок money_source
Список доступных методов оплаты. Тип поля:
array
.Метод оплаты | Описание |
---|---|
wallet | Оплата из кошелька ЮMoney. |
cards | Оплата с привязанных к счету банковских карт. |
payment-card | Оплата с банковской карты. |
cash | Оплата наличными. |
Пример
JSON
"money_source": [ "wallet", "cards", "payment-card", "cash" ]
Блок form
Описание формы, которую необходимо отобразить покупателю.
Элемент
form
является корневым контейнером формы, содержащим список (группу) UI-контролов и контейнеров.Клиенту следует отрисовывать элементы внутри
form
вертикально, сверху вниз.Пример
JSON
"form": [ ... UI-контролы и контейнеры ... ]
UI-контролы
UI-контрол — это поле формы, предназначенное для пользовательского ввода.
По умолчанию значения всех контролов должны быть заполнены покупателем, если явным образом не указана необязательность заполнения поля (
required=false
).Тип данных поля и правила проверки его значений на стороне клиента определены типом и атрибутами контрола.
Все описанные ниже атрибуты контрола всегда присутствуют в описании, если явным образом не указано иное.
Общие атрибуты контролов
Атрибут | Тип | Описание |
---|---|---|
type | string | Тип UI-контрола. Обязательный атрибут. |
name | string | Имя поля формы, имя параметра запроса отправки данных формы. Обязательный атрибут. |
value | string | Предварительно заполненное значение контрола (кроме checkbox ). Необязательный атрибут, по умолчанию отсутствует. |
value_autofill | string | Макрос автоподстановки для предварительного заполнения значения поля клиентом. Необязательный атрибут, по умолчанию отсутствует. Если клиент обрабатывает макросы, то их значение переопределяет value . |
hint | string | Подсказка для покупателя о назначении и формате данных поля. Необязательный атрибут, по умолчанию отсутствует. |
label | string | Наименование поля формы для отображения покупателю, надпись над контролом. Необязательное поле, по умолчанию отсутствует. |
alert | string | Текст ошибки, который следует отображать покупателю при ошибке проверки введенных в данное поле данных. Необязательное поле, по умолчанию отсутствует. Текст предназначен для отображения при ошибке проверки данных на стороне приложения клиента. |
required | boolean | Обязательность заполнения поля покупателем. По умолчанию true . |
readonly | boolean | Признак запрета изменения значения поля формы. По умолчанию false . |
text — Поле ввода текста
Однострочное поле ввода текста. Подробнее
Специфичные атрибуты контрола:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: text . |
minlength | int | Минимально допустимая длина строки. Необязательный параметр, по умолчанию не определено. |
maxlength | int | Максимально допустимая длина строки. Необязательный параметр, по умолчанию не ограничено. |
pattern | string | Регулярное выражение для проверки введенного покупателем значения. Формат регулярного выражения: ECMA-262 RegExp (JavaScript RegExp). Необязательный параметр, по умолчанию отсутствует. |
keyboard_suggest | enum | Рекомендуемый тип экранной клавиатуры для мобильных устройств. Возможные значения: number — отображать цифровую клавиатуру для поля. По умолчанию атрибут не определен, будет отображена текстовая клавиатура. |
Пример
JSON
{ "type": "text", "name": "surname", "label": "Фамилия", "required": true, "readonly": false }
Пример для поля с набором десятичных цифр
JSON
{ "type": "text", "name": "kbk", "label": "КБК", "pattern": "[0-9]{20}", "required": true, "readonly": false, "keyboard_suggest": "number" }
number — Поле ввода числа
Пример для поля с набором десятичных цифр. Подробнее
Специфичные атрибуты контрола:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: number . |
min | decimal number | Минимально допустимое значение. Необязательный атрибут, по умолчанию не определен (любое). |
max | decimal number | Максимально допустимое значение. Необязательный атрибут, по умолчанию не определен (любое). |
step | Минимальная градация числа («step scale factor»). Необязательный атрибут, значение по умолчанию — 1 . Примеры возможных значений:
|
Пример
JSON
{ "type": "number", "name": "qty", "label": "Количество, шт.", "step": 1, "required": true, "readonly": false }
Пример
JSON
{ "type": "number", "name": "coins", "label": "Количество единиц игровой валюты", "step": 0.01, "required": true, "readonly": false }
amount — Поле ввода суммы
Однострочное поле ввода суммы, расширяет тип
number
.Специфичные атрибуты контрола:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: amount . |
min | decimal number | Минимально допустимое значение. По умолчанию — 0.01 . |
max | decimal number | Максимально допустимое значение. Необязательный атрибут, по умолчанию не определен (любое). |
step | decimal number | Кратность значения суммы. По умолчанию — 0.01 . |
currency | string, [A-Z]{3} | Трехсимвольный буквенный код валюты по стандарту ISO-4217. По умолчанию — RUB . |
fee | object | Информация о комиссии с покупателя. Если этот блок присутствует — это признак того, что с покупателя взимается комиссия. По умолчанию комиссия с покупателя отсутствует. |
Атрибуты блока
fee
:Атрибут | Тип | Описание |
---|---|---|
type | enum | Тип комиссии с покупателя. Может иметь значения:
По умолчанию — std . |
a | decimal number | Коэффициент от суммы к перечислению в магазин (netAmount ). По умолчанию — 0 . |
b | decimal number | Фиксированная сумма комиссии за операцию в единицах currency. По умолчанию — 0 . |
c | decimal number | Минимальная комиссия за операцию в единицах currency. По умолчанию — 0 . |
d | decimal number | Максимальная комиссия за операцию в единицах currency. По умолчанию — 0 . |
amount_type | enum | Тип суммы на форме оплаты. Возможные значения:
По умолчанию — amount . |
Пример: комиссия 2% сверх суммы к перечислению в магазин
JSON
{ "type": "amount", "name": "sum", "label": "Сумма", "min": 0.01, "step": 0.01, "currency": "RUB", "fee": { "a": 0.02, "amount_type": "netAmount" }, "required": true, "readonly": false }
Пример: присутствует комиссия, рассчитываемая на стороне партнера при платеже
JSON
{ "type": "amount", "name": "sum", "label": "Сумма", "min": 0.01, "step": 0.01, "currency": "RUB", "fee": { "type": "custom" }, "required": true, "readonly": false }
Информация о комиссиях
На форме оплаты может быть определена комиссия с покупателя.
Комиссия описывается формулой:
amount = netAmount + fee
Где:
amount
— сумма к списанию со счета покупателя;netAmount
— сумма к перечислению в магазин (к получению);fee
— величина комиссии с покупателя.
Стандартная формула расчета комиссии
fee = min(max(a * netAmount + b, c), d)
Вычисление
amount
из netAmount
amount = netAmount + min(max(a * netAmount + b, c), d)
Вычисление
netAmount
из amount
netAmount = amount - min(max(max(amount * (a / (1 + a)) + b / (1 + a), b), c), d)
Правило минимальной комиссии
Если определено наличие комиссии с покупателя, то, вне зависимости от коэффициентов формулы, комиссия не может быть меньше 0.01 единицы валюты счета (1 копейки).
В случае, если при расчете комиссии получается сумма менее 0.01, она всегда округляется в большую сторону до 0.01.
Правило минимальной суммы
При расчете
netAmount
из amount
можно указать только такой amount
, при котором netAmount
будет больше или равен 0.01 единицы валюты счета (1 копейки).Если указан меньший
amount
, это ошибочная ситуация — такой платеж невозможен.Типовые виды комиссий
Вид | Коэффициенты |
---|---|
Без комиссии | a=0, b=0, c=0, d=<не определено> . Блок fee отсутствует |
Процент от суммы | a=<коэффициент>, b=0, c=0, d=<не определено> |
Фиксированная комиссия за операцию | a=0, b=<сумма, руб>, с=0, d=<не определено> |
Процент от суммы И фиксированная комиссия за операцию | a=<коэффициент>, b=<сумма>, c=0, d=<не определено> |
Процент от суммы ИЛИ минимальная комиссия за операцию | a=<коэффициент>, b=0, c=<сумма>, d=<не определено> |
email — Поле ввода email
Поле ввода адреса электронной почты. Подробнее
Специфичные атрибуты контрола:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: email . |
Пример
JSON
{ "type": "email", "name": "email", "label": "Email", "required": true, "readonly": false }
tel — Поле ввода номера телефона
Поле ввода номера телефона. Подробнее
Формат значения номера телефона, отправляемого на сервер, — ITU-T T.164, полный номер телефона, без знака +, например
79999999999
.Клиент может отображать контрол по своему усмотрению, равно как и выбрать формат пользовательского ввода.
Специфичные атрибуты контрола:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: tel . |
Пример
JSON
{ "type": "tel", "name": "phone", "value": "79210000000", "hint": "Полный международный номер", "label": "Номер телефона", "alert": "Номер телефона должен содержать только цифры", "required": true, "readonly": false }
checkbox — Флажок (чекбокс)
Поведение контрола определено спецификацией HTML5:
- атрибут
value
определяет значение, которое будет отправлено на сервер, если флажок установлен; может содержать произвольное строковое значение; - состояние контрола определяется атрибутом
checked
— флажок установлен или сброшен; - на сервер отправляются только те поля, у которых флажок установлен (
checked=true
).
Специфичные атрибуты контрола:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: checkbox . |
value | string | Значение, которое будет отправлено на сервер, если флажок установлен. |
checked | boolean | Начальное состояние контрола:
Необязательный атрибут, по умолчанию false . |
required | boolean | Возможные значения:
|
Пример
JSON
{ "type": "checkbox", "name": "notify_me", "value": "agreed", "checked" : true, "label": "Уведомлять меня о начислениях", "readonly": false, "required": false }
date — Выбор даты (день/месяц/год)
Календарь с выбором полной даты. Подробнее
Специфичные атрибуты контрола:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: date . |
min | date string или период | Минимально допустимая дата. Необязательный атрибут, по умолчанию — любая. |
max | date string или период | Максимально допустимая дата. Необязательный атрибут, по умолчанию — любая. |
При отправке данных формы на сервер значение поля должно быть в формате date string, например
12.02.2015
.Пример
JSON
{ "type": "date", "name": "receipt_date", "label": "Дата постановления", "required": true, "readonly": false }
month — Выбор месяца и года
Календарь с выбором только месяца и года. Подробнее
Специфичные атрибуты контрола:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: month . |
min | month string или период | Минимально допустимый месяц и год. Необязательный атрибут, по умолчанию — любой. |
max | month string или период | Максимально допустимый месяц и год. Необязательный атрибут, по умолчанию — любой. |
При отправке данных формы на сервер значение поля должно быть в формате month string, например
2015-02
.Пример
JSON
{ "type": "month", "name": "period", "label": "Период оплаты", "required": true, "readonly": false }
select — Выбор значения из списка
Контрол, предназначенный для выбора одного значения из списка. Предоставляет только модель данных — визуальное отображение контрола может быть любым на усмотрение клиента (ComboBox, Select, RadioGroup, Spinner и так далее). Подробнее
Контрол может изменять визуальное состояние формы, переключая видимые состояния формы.
Специфичные атрибуты контрола:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: select . |
value | string | Значение, выбранное по умолчанию, необязательное поле. Отсутствие атрибута или пустое значение означает «ничего не выбрано». |
options | array of object | Список значений для выбора. |
style | enum | Рекомендуемое клиенту отображение контрола. Необязательный атрибут, по умолчанию клиент сам принимает решение о том, как отображать этот контрол. Возможные значения:
|
Атрибуты элементы списка значений для выбора:
Атрибут | Тип | Описание |
---|---|---|
value | string | Выбранное значение, которое будет отправлено на сервер как значение этого поля формы. Обязательный атрибут, его значение не может быть пустым. |
label | string | Текст отображаемый покупателю в списке значений. |
group | array of object | Список (группа) UI-контролов и/или контейнеров, который становятся видимыми, если выбрать это значение. Может содержать другие вложенные select .Необязательный атрибут, по умолчанию не определен (визуальное состояние формы не изменяется). |
Пример
JSON
{ "type": "select", "name": "country", "value": "gb", "label": "Страна для звонков", "options": [ { "value": "gb", "label": "Великобритания" }, { "value": "de", "label": "Германия" }, { "value": "es", "label": "Испания" }, { "value": "it", "label": "Италия" } ], "required": true, "readonly": false }
Пример: выбор изменяет видимое состояние формы
JSON
{ "type": "select", "name": "DeliveryType", "value": "ym_msk", "label": "Где получить ридер", "options": [ { "value": "ym_msk", "label": "в офисе ЮMoney в Москве" }, { "value": "russianPost", "label": "в отделении Почты России (после доставки)", "group": [ // группа UI контролов и/или контейнеров, которая становится видимой если // выбрать это значение (список полей для заполнения почтового адреса) ] } ], "required": true, "readonly": false }
textarea — Поле ввода многострочного текста
Поле для ввода произвольного текста, который может состоять из множества строк. Подробнее
Специфичные атрибуты контрола:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: textarea . |
maxlength | int | Максимально допустимая длина текста, символов. Необязательный атрибут, по умолчанию не ограничено. |
minlength | int | Минимально допустимая длина текста, символов. Необязательный атрибут, по умолчанию не определено. |
Пример
JSON
{ "type": "textarea", "name": "comment", "label": "Комментарий к переводу", "hint": "Здесь можно написать что-нибудь получателю", "maxlength": 150, "required": false, "readonly": false }
submit — Кнопка отправки формы
Кнопка в форме, инициирующая ее отправку на сервер. Подробнее
Специфичные атрибуты контрола:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: submit . |
Пример
JSON
{ "type": "submit", "label": "Заплатить", "required": true, "readonly": false }
UI-контейнеры
Контейнер — это группа UI-контролов или статических данных для отображения покупателю.
Общие атрибуты контейнеров
Атрибут | Тип | Описание |
---|---|---|
type | string | Тип контейнера. Обязательный атрибут. |
group — Группа контролов или контейнеров
Группа, содержащая список UI-контролов и/или вложенных контейнеров
Все атрибуты обязательные, если явным образом не указано иное.
Специфичные атрибуты контейнера:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: group . |
items | array | Список контролов и/или вложенных контейнеров. |
label | string | Заголовок группы (надпись над группой). Необязательный атрибут, по умолчанию отсутствует. |
layout | enum | Рекомендуемое расположение элементов внутри группы. Возможные значения:
Необязательный атрибут, по умолчанию: VBox . |
Пример
JSON
{ "type": "group", "label": "Получатель перевода", "layout": "VBox", "items": [ { "type": "text", "name": "surname", "label": "Фамилия", "required": true, "readonly": false, "maxlength": 50, "alert": "Пожалуйста, укажите фамилию получателя" }, { "type": "text", "name": "name", "label": "Имя", "required": true, "readonly": false, "maxlength": 50, "alert": "Пожалуйста, укажите имя получателя" }, { "type": "text", "name": "patronymic", "label": "Отчество", "required": true, "readonly": false, "maxlength": 50, "alert": "Пожалуйста, укажите отчество получателя" } ] }
p — Параграф текста
Блок статического текста, может содержать гиперссылки. Подробнее
Специфичные атрибуты контейнера:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: p . |
items | Array | Список элементов параграфа. |
label | string | Заголовок параграфа (надпись над блоком текста). Необязательный атрибут |
Элементы параграфа могут быть:
- строки текста (тип
string
). - гиперссылки (тип
object
).
Атрибуты гиперссылки:
Атрибут | Тип | Описание |
---|---|---|
type | string | Фиксированное значение: a . |
href | URL | HTTP (S)-гиперссылка. |
label | string | Текст ссылки, отображаемый покупателю. |
Пример
JSON
{ "type": "p", "items": [ "Нажимая \"Заплатить\", вы соглашаетесь с", { "type": "a", "href": "http://example.com/doc/12345567890", "label": "условиями покупки" }, "пин-кода iTunes." ] }
ViewState — изменяемые состояния форм
Можно менять набор видимых элементов формы в зависимости от выбранных значений определенных контролов типа select.
Правила работы форм с изменяемым состоянием:
- форма может быть как одношаговой, так и шагом многошаговой формы;
- описание формы или шага формы содержит полный список UI-контролов и контейнеров;
- каждый UI-контрол или контейнер имеет состояние видимости: отображается на форме или нет;
- ViewState (состояние формы) — это список контролов/контейнеров, отображаемых на форме в текущем состоянии;
- один из UI-контролов формы — это переключатель состояний.
Логика переключателя состояний аналогичная оператору
switch-case
в популярных языках программирования:select { option X => элементы видимые в состоянии X option Y => элементы видимые в состоянии Y option Z => .... }
UI-контролы и контейнеры, которые находятся внутри определенного
option
select, становятся видимыми, только если выбрано значение этого option
.При отправке данных формы на сервер в запрос добавляются значения только видимых в данном состоянии UI-контролов.
Пример: форма оплаты mPOS-ридера
JSON
{ "title": "Ридер для мобильного терминала (mPOS)", "hidden_fields": { "rnd": "77122820", "scid": "6953", "shn": "Ридер для мобильного терминала (mPOS)", "targetcurrency": "643", "SuccessTemplate": "ym2xmlsuccess", "ErrorTemplate": "ym2xmlerror", "ShowCaseID": "7", "isViaWeb": "true", "try-payment": "true", "FormComment": "Ридер для мобильного терминала (mPOS)" }, "form": [ { "type": "text", "name": "Ewallet", "label": "Номер счета", "hint": "На этот счет будут зачисляться деньги", "value_aurofill": "currentuser_accountkey", "pattern": "[0-9]{11,33}", "required": true, "readonly": false }, { "type": "tel", "name": "contactPhoneNumber", "label": "Номер телефона", "required": true, "readonly": false }, { "type": "text", "name": "LastName", "label": "Фамилия", "maxlength": 150, "required": true, "readonly": false }, { "type": "text", "name": "FirstName", "label": "Имя", "maxlength": 150, "required": true, "readonly": false }, { "type": "text", "name": "MiddleName", "label": "Отчество", "maxlength": 150, "required": true, "readonly": false }, { "type": "select", "name": "DeliveryType", "value": "ym_msk", "label": "Где получить ридер", "options": [ { "value": "ym_msk", "label": "в офисе ЮMoney в Москве" }, { "value": "ym_spb", "label": "в офисе ЮMoney в Петербурге" }, { "value": "russianPost", "label": "в отделении Почты России (после доставки)", "group": [ { "type": "select", "name": "country", "value": "Россия", "label": "Страна", "options": [ { "value": "Россия", "label": "Россия" }, { "value": "Белоруссия", "label": "Белоруссия" }, { "value": "Украина", "label": "Украина" }, { "value": "Молдавия", "label": "Молдавия" }, { "value": "Армения", "label": "Армения" }, { "value": "Азербайджан", "label": "Азербайджан" }, { "value": "Киргизия", "label": "Киргизия" }, { "value": "Казахстан", "label": "Казахстан" }, { "value": "Таджикистан", "label": "Таджикистан" }, { "value": "Туркмения", "label": "Туркмения" }, { "value": "Узбекистан", "label": "Узбекистан" } ] }, { "type": "text", "name": "index_address", "label": "Индекс", "pattern": "[0-9]{6,8}", "required": true, "readonly": false }, { "type": "text", "name": "deliveryRegion", "label": "Регион", "maxlength": 44, "required": true, "readonly": false }, { "type": "text", "name": "address_1", "label": "Населенный пункт", "maxlength": 150, "required": true, "readonly": false }, { "type": "text", "name": "deliveryStreet", "label": "Улица", "maxlength": 44, "required": true, "readonly": false }, { "type": "text", "name": "deliveryHouse", "label": "дом", "maxlength": 9, "required": true, "readonly": false }, { "type": "text", "name": "deliveryCorpus", "label": "корпус", "maxlength": 9, "required": true, "readonly": false }, { "type": "text", "name": "deliveryBuilding", "label": "стр.", "maxlength": 9, "required": true, "readonly": false }, { "type": "text", "name": "deliveryFlat", "label": "кв.", "maxlength": 9, "required": true, "readonly": false } ], "required": true, "readonly": false } ] }, { "type": "p", "items": [ "Нажимая на эту кнопку, я принимаю", { "type": "a", "href": "http://example.com/doc.xml?id=526489", "label": "условия использования мобильного терминала" }, "." ] }, { "type": "submit", "label": "Продолжить", "required": true, "readonly": false } ] }
Макросы автоподстановки
Макросы автоподстановки предназначены для предварительного заполнения значения поля формы определенным значением на стороне клиента.
Если клиент умеет обрабатывать макрос, он генерирует значение
value
, которое переопределяет value
формы.Если клиент не умеет обрабатывать макрос, то он игнорируется.
Пример
JSON
{ "type": "text", "name": "Ewallet", "label": "Номер счета", "hint": "На этот счет будут зачисляться деньги", "value_autofill": "currentuser_accountkey", "pattern": "[0-9]{11,33}" }
Макросы автоподстановки:
macro_name | Описание |
---|---|
currentuser_accountkey | Подставляет номер счета пользователя ЮMoney, если он известен. |
calendar_next_month | Подставляет в поле типа month значение yyyy-mm следующего месяца за текущим календарным месяцем. |
Определение значений даты и времени
Исчисление времени основывается на стандарте ISO 8601:2004.
Определение формата полной даты: date string.
Форма указания полной даты
YYYY-MM-DD
Определение формата указания месяца и года: month string.
Формат указания месяца и года
YYYY-MM
- абсолютное значение полной даты или месяца/года;
- указание на то, что следует использовать текущую дату (now);
- вычисляемое значение на основе абсолютного значения даты и интервала.
Пример: абсолютное значение даты
2014-08-19
Пример: подставить текущую даты
now
Вычисляемое значение на основе абсолютного значения даты и интервала определено в разделе «4.4.4.2 Representations of time intervals by duration and context information» стандарта ISO 8601:2004.
Для определения интервала (duration) используется Basic Format:
PnYnMnD
Где:
P
— символ «Period»;nY
— количество лет (например3Y
);nM
— количество месяцев (например10M
);nD
— количество дней (например5D
).
Неиспользуемые символы можно опускать. Например, допустимо указывать интервал как
3Y
или 2M10D
или 5D
.Для указания даты в прошлом используется Extended-формат, определенный разделом «4.4.4.4 Representations of time interval identified by duration and end» стандарта ISO 8601:2004.
PnYnMnD/YYYY-MM-DD или PnYnMnD/now
Для указания даты в будущем используется Extended-формат, определенный разделом «4.4.4.3 Representations of time interval identified by start and duration» стандарта ISO 8601:2004.
YYYY-MM-DD/PnYnMnD или now/PnYnMnD
Пример: допустимо выбрать период оплаты не ранее, чем три года назад
JSON
{ "type": "month", "name": "period", "label": "Период оплаты", "required": true, "readonly": false, "min": "P3Y/now" }
Пример: допустимо выбрать период оплаты не позже, чем следующий месяц
JSON
{ "type": "month", "name": "period", "label": "Период оплаты", "required": true, "readonly": false, "max": "now/P1M" }
Пример: допустимо выбрать дату не ранее 01 Янв 2005 и не позднее 3.5 лет после 2 Янв 2009
JSON
{ "type": "date", "name": "document_date", "label": "Дата постановления", "required": true, "readonly": false, "min":"2005-01-01", "max": "2009-01-02/P3Y6M" }