Form description

The description of the payment form is a JSON document in UTF‑8 encoding.

Form examples

Title fields on the form

The title section

The name of the product being purchased. Field type: string.

Example

JSON
"title": "RusTel Northwest"

The hidden_fields section

Service fields for the form. Field type: object, a key-value set.

The client should transparently transmit the set of fields when the form data is sent to the server.

Example

JSON
"hidden_fields": {
    "targetcurrency": "643",
    "ShopArticleID": "35241"
}

The money_source section

List of available payment methods. Field type: array.

Payment method	Description
wallet	Payment from a YooMoney wallet.
cards	Payment using bank cards that are linked to the account.
payment-card	Payment using a bank card.
cash	Payment in cash.

Example

JSON
"money_source": [
  "wallet",
  "cards",
  "payment-card",
  "cash"
]

The form section

The description of the form that should be shown to the buyer.

The form element is the root container of the form containing a list(group) of UI controls and containers.

The client should render the elements inside form vertically, top to bottom.

Example

JSON
"form": [
   ... UI controls and containers ...
]

UI controls

A UI control is a field on the form designed for the user to enter something.

By default, all the control values must be filled in by the buyer, unless a form is explicitly declared to be optional (required=false).

The type of field data and rules for checking the values on the client side are determined by the control’s type and attributes.

All the control attributes listed below always exist in a description, unless explicitly specified otherwise.

General attributes of controls

Attribute	Type	Description
type	string	Type of UI control. Required attribute.
name	string	Name of the form field, or parameter name for the form data submission request. Required attribute.
value	string	Pre-set value of a control (other than `checkbox`). Optional attribute, omitted by default.
value_autofill	string	Autofill macro for pre-setting field values by the client. Optional attribute, omitted by default. If the client handles macros, their values determine the `value` attribute.
hint	string	Hint for the buyer about the purpose and format of data in the field. Optional attribute, omitted by default.
label	string	Title of the field to display to the buyer as a label on the control. Optional attribute, omitted by default.
alert	string	Error text to show to the buyer when there is an error verifying the information entered in this field. Optional attribute, omitted by default. The text is for displaying when there is an error checking data on the client side.
required	boolean	Indicates whether the field must be filled in by the buyer. By default, `true`.
readonly	boolean	Indicates that changing the value of the form field is prohibited. By default, `false`.

text — Text box

Single line for entering text. Details

Control-specific attributes:

Attribute	Type	Description
type	string	Constant value: `text`.
minlength	int	Minimum allowed length of the string. Optional parameter, not defined by default.
maxlength	int	Maximum allowed length of the string. Optional parameter, not restricted by default.
pattern	string	Regular expression for checking values entered by the buyer. Regular expression format: ECMA-262 RegExp (JavaScript RegExp). Optional parameter, not defined by default.
keyboard_suggest	enum	Recommended type of on-screen keyboard for mobile devices. Possible values: `number` — display a digital keyboard for the field. By default, the attribute is not defined, and a text keyboard is displayed.

Example

JSON
{
  "type": "text",
  "name": "surname",
  "label": "Last Name",
  "required": true,
  "readonly": false
}

Example for a field with a set of decimal digits

JSON
{
  "type": "text",
  "name": "kbk",
  "label": "KBK",
  "pattern": "[0-9]{20}",
  "required": true,
  "readonly": false,
  "keyboard_suggest": "number"
}

number — Number entry field

Example for a field with a set of decimal digits. Details

Control-specific attributes:

Attribute	Type	Description
type	string	Constant value: `number`.
min	decimal number	Minimum value. Optional attribute, not defined by default (any value).
max	decimal number	Maximum value. Optional attribute, not defined by default (any value).
step	decimal number	Minimum number gradation (“step scale factor”). Optional attribute, default value is `1`. Examples of possible values: `1` — allows only integers; `0.01` — minimum allowed step of a decimal number; `10` — allows only integers that are multiples of 10.

Example

JSON
{
  "type": "number",
  "name": "qty",
  "label": "Amount, units",
  "step": 1,
  "required": true,
  "readonly": false
}

Example

JSON
{
  "type": "number",
  "name": "coins",
  "label": "Amount in game currency",
  "step": 0.01,
  "required": true,
  "readonly": false
}

amount — Box for entering amount

Single-line amount input field that extends the number type.

Control-specific attributes:

Attribute	Type	Description
type	string	Constant value: `amount`.
min	decimal number	Minimum value. By default, `0.01`.
max	decimal number	Maximum value. Optional attribute, not defined by default (any value).
step	decimal number	Multiplication factor of the amount. By default, `0.01`.
currency	string, [A-Z]{3}	Three-letter currency code conforming to the ISO-4217 standard. By default, `RUB`.
fee	object	Information about the commission charged to the buyer. If this section is included, it means that the buyer is charged a fee. By default, there is no fee charged to the buyer.

Attributes of the fee section:

Attribute	Type	Description
type	enum	Type of fee charged to the buyer. Can have the values: `std` — the fee is based on a standard formula; `custom` — fee with a complex formula or fee calculation on the side of the store, the fee is calculated when paying. It is necessary to notify the buyer of the fact of the fee. By default, `std`.
a	decimal number	A coefficient of the amount to transfer to the merchant (`netAmount`). By default, `0`.
b	decimal number	A fixed fee per transaction, in currency units. By default, `0`.
c	decimal number	The minimum fee per transaction, in currency units. By default, `0`.
d	decimal number	The maximum fee per transaction, in currency units. By default, `0`.
amount_type	enum	The type of amount on the payment form. Possible values: `amount` — the amount to deduct from the buyer’s account; `netAmount` — the amount to transfer to the merchant (to be received). By default, `amount`.

Example: 2% fee over the amount to transfer to the merchant

JSON
{
  "type": "amount",
  "name": "sum",
  "label": "sum",
  "min": 0.01,
  "step": 0.01,
  "currency": "RUB",
  "fee": {
    "a": 0.02,
    "amount_type": "netAmount"
  },
  "required": true,
  "readonly": false
}

Example: A fee is calculated on the partner side during payment

JSON
{
  "type": "amount",
  "name": "sum",
  "label": "sum",
  "min": 0.01,
  "step": 0.01,
  "currency": "RUB",
  "fee": {
    "type": "custom"
  },
  "required": true,
  "readonly": false
}

Information about comissions

The payment form can have a commission fee set to charge the buyer.

The fee is defined by the formula:

amount = netAmount + fee

Where:

amount — the amount to deduct from the buyer’s account;
netAmount — the amount to transfer to the merchant (to be received);
fee — the size of the fee charged to the buyer.

Standard formula for calculating the commission fee:

fee = min(max(a * netAmount + b, c), d)

Calculating amount from netAmount:

amount = netAmount + min(max(a * netAmount + b, c), d)

Calculating netAmount from amount

netAmount = amount - min(max(max(amount * (a / (1 + a)) + b / (1 + a), b), c), d)

Minimum commission fee rule

If there is a commission fee charged to the user, regardless of the rates in the formula, the commission must not be less than 0.01 of the currency unit for the account (1 kopek).

If calculating the fee results in an amount less than 0.01, it is always rounded up to 0.01.

Minimum amount rule

When calculating netAmount from amount, you can only specify an amount for which netAmount will be greater than or equal to 0.01 units of the account currency (1 kopek).

If a smaller amount is specified, this leads to an error — the payment is not possible.

Standard types of commissions

Type	Coefficients
Without commission	`a=0, b=0, c=0, d=<undefined>`. The `fee` block is omitted
Percent of amount	`a=<coefficient>, b=0, c=0, d=<undefined>`
Fixed commission fee per transaction	`a=0, b=<amount, RUB>, с=0, d=<undefined>`
Percent of amount AND fixed commission fee per transaction	`a=<coefficient>, b=<amount>, c=0, d=<undefined>`
Percent of amount OR minimum commission fee per transaction	`a=<coefficient>, b=0, c=<amount>, d=<undefined>`

email — Email input field

Box for entering an email address. Details

Control-specific attributes:

Attribute	Type	Description
type	string	Constant value: `email`.

Example

JSON
{
  "type": "email",
  "name": "email",
  "label": "Email",
  "required": true,
  "readonly": false
}

tel — Phone number input field

Box for entering a phone number. Details

The format of the phone number value sent to the server is ITU-T T.164, the complete phone number without a + sign, for example: 79999999999.

The client can display the control as necessary, and choose the format for user input.

Control-specific attributes:

Attribute	Type	Description
type	string	Constant value: `tel`.

Example

JSON
{
  "type": "tel",
  "name": "phone",
  "value": "79210000000",
  "hint": "International format",
  "label": "Phone number",
  "alert": "The phone number can only contain numbers",
  "required": true,
  "readonly": false
}

checkbox — Checkbox option

A checkbox is a control that implements a true or false flag. Details

The behavior of the control is defined in the HTML5 specification:

the value attribute defines the value that will be sent to the server if the option is selected; it can have any string value;
the state of the control is defined by the checked attribute — whether the option is selected or deselected;
only those fields that have the option selected (checked=true) are sent to the server.

Control-specific attributes:

Attribute	Type	Description
type	string	Constant value: `checkbox`.
value	string	The value that will be sent to the server if the flag is set.
checked	boolean	Starting state of the control: `true` — flag is set (checked); `false` — flag is cleared (unchecked). Optional attribute, by default, `false`.
required	boolean	Possible values: `true` — the form can be sent to the server only if the user selected the option; `false` — the form can be sent to the server regardless of the state of the option (selected or unselected).

Example

JSON
{
  "type": "checkbox",
  "name": "notify_me",
  "value": "agreed",
  "checked" : true,
  "label": "Notify me of deposits",
  "readonly": false,
  "required": false
}

date — Date selection (day/month/year)

A calendar for selecting the full date. Details

Control-specific attributes:

Attribute	Type	Description
type	string	Constant value: `date`.
min	date string or period	Minimum date allowed. Optional attribute, by default, any date.
max	date string or period	Maximum date allowed. Optional attribute, by default, any date.

When sending form data to the server, the field value must be in date string format, such as 2015-02-12.

Example

JSON
{
  "type": "date",
  "name": "receipt_date",
  "label": "Resolution date",
  "required": true,
  "readonly": false
}

month — Selection of month and year

A calendar for selecting only the month and year. Details

Control-specific attributes:

Attribute	Type	Description
type	string	Constant value: `month`.
min	month string or period	Minimum allowed month and year. Optional attribute, by default, any date.
max	month string or period	Maximum allowed month and year. Optional attribute, by default, any date.

When sending form data to the server, the field value must be in month string format, such as 2015-02.

Example

JSON
{
  "type": "month",
  "name": "period",
  "label": "Payment period",
  "required": true,
  "readonly": false
}

select — Selection of list item

A control for selecting one of the values from a list. Only represents the data model; the visual display of the control is up to the client’s discretion (ComboBox, Select, RadioGroup, Spinner, and so on). Details

The control can change the visual state of the form by switching the form viewstates.

Control-specific attributes:

Attribute	Type	Description
type	string	Constant value: `select`.
value	string	The selected default value, optional field. If this attribute is omitted or set to a null value, it means “nothing was selected”.
options	array of object	List of values to select from.
style	enum	Control display recommended to the client. Control display recommended to the client, optional attribute; by default, the client decides how to display this control. Possible values: `RadioGroup` — RadioButton/RadioGroup; `Spinner` — Drop-down menus (ComboBox, DropDownList, Select).

Attributes of list items:

Attribute	Type	Description
value	string	The selected value that will be sent to the server as the value for this form field. Required attribute, its value must not be empty.
label	string	The text shown to the buyer in the list of values.
group	array of object	A list (group) of UI controls and/or containers that become visible if this value is selected. May contain other nested `select` parameters. Optional attribute; by default, not defined (the form’s visual state does not change).

Example

JSON
{
  "type": "select",
  "name": "country",
  "value": "gb",
  "label": "Country for calls",
  "options": [
    {
      "value": "gb",
      "label": "Great Britain"
    },
    {
      "value": "de",
      "label": "Germany"
    },
    {
      "value": "es",
      "label": "Spain"
    },
    {
      "value": "it",
      "label": "Italy"
    }
  ],
  "required": true,
  "readonly": false
}

Example: Selection changes the form’s visible state

JSON
{
  "type": "select",
  "name": "DeliveryType",
  "value": "ym_msk",
  "label": "Where to get the reader",
  "options": [
    {
      "value": "ym_msk",
      "label": "at the YooMoney office in Moscow"
    },
    {
      "value": "russianPost",
      "label": "at a Russian Post branch office (after delivery)",
      "group": [
          // a group of UI controls and/or containers that becomes active if
          // this value is selected (a list of fields for entering the mailing address)
      ]
    }
  ],
  "required": true,
  "readonly": false
}

textarea — Multi-line text box

A field for entering any text, which may consist of multiple lines. Details

Control-specific attributes:

Attribute	Type	Description
type	string	Constant value: `textarea`.
maxlength	int	Maximum allowed length of text, in characters. Optional attribute, not restricted by default.
minlength	int	Minimum allowed length of text, in characters. Optional attribute, not defined by default.

Example

JSON
{
  "type": "textarea",
  "name": "comment",
  "label": "Comments on the transfer",
  "hint": "You can enter a message for the recipient here",
  "maxlength": 150,
  "required": false,
  "readonly": false
}

submit — Form submission button

Button on the form that initiates sending it to the server. Details

Control-specific attributes:

Attribute	Type	Description
type	string	Constant value: `submit`.

Example

JSON
{
  "type": "submit",
  "label": "Pay",
  "required": true,
  "readonly": false
}

UI containers

A container is a group of UI controls or static data to display to the buyer.

General attributes of containers

Attribute	Type	Description
type	string	Type of container. Required attribute.

group — Group of controls or containers

A group containing a list of UI controls and/or nested containers

All attributes are required, unless explicitly specified otherwise.

Container-specific attributes:

Attribute	Type	Description
type	string	Constant value: `group`.
items	array	List of controls and/or nested containers.
label	string	Group title (label on the group). Optional attribute, omitted by default.
layout	enum	Recommended layout of items inside the group. Possible values: `VBox` — vertically, top to bottom; `HBox` — horizontally, left to right. Optional attribute, by default: `VBox`.

Example

JSON
{
  "type": "group",
  "label": "Transfer recipient",
  "layout": "VBox",
  "items": [
    {
      "type": "text",
      "name": "surname",
      "label": "Last name",
      "required": true,
      "readonly": false,
      "maxlength": 50,
      "alert": "Please enter the recipient's last name"
    },
    {
      "type": "text",
      "name": "name",
      "label": "Name",
      "required": true,
      "readonly": false,
      "maxlength": 50,
      "alert": "Please enter the recipient's first name"
    },
    {
      "type": "text",
      "name": "patronymic",
      "label": "Patronymic",
      "required": true,
      "readonly": false,
      "maxlength": 50,
      "alert": "Please enter the recipient's patronymic"
    }
  ]
}

p — Text paragraph

A section of static text that may contain hyperlinks. Details

Container-specific attributes:

Attribute	Type	Description
type	string	Constant value: `p`.
items	Array	List of paragraph elements.
label	string	Paragraph title (label over the text section). Optional attribute.

Paragraph elements can be:

text string (string type).
hyperlinks (object type).

Hyperlink attributes:

Attribute	Type	Description
type	string	Constant value: `a`.
href	URL	HTTP (S) hyperlink.
label	string	Hyperlink text displayed to the buyer.

Example

JSON
{
  "type": "p",
  "items": [
    "By clicking \"Pay\", you accept",
    {
      "type": "a",
      "href": "http://example.com/doc/12345567890",
      "label": "the terms of purchase of"
    },
    "an iTunes PIN code."
  ]
}

ViewState — Changeable form states

You can change the set of visible form elements, depending on the values selected for specific controls with the select type.

Rules for working with forms with changeable states:

a form can be either single-step, or a step in a multistep form;
the description of a form or step of a form contains a complete list of UI controls and containers;
each UI control or container has a visibility state: whether it is displayed on the form, or not;
viewState (the form state) is a list of controls or containers displayed on the form in the current state;
one of the UI controls on the form switches the states.

The state switch logic works like the switch-case operator in popular programming languages:

select {
  option X =>
     elements visible in state X
  option Y =>
     elements visible in state Y
  option Z =>
     ....
}

The UI controls and containers that are located inside a particular select option become visible only when the value for this option is selected.

When submitting form data to the server, only the values of the UI controls that are visible in this state are added to the request.

Example: Payment form for purchasing an mPOS reader

JSON
{
  "title": "Reader for mobile point of sale (mPOS)",
  "hidden_fields": {
    "rnd": "77122820",
    "scid": "6953",
    "shn": "Reader for mobile point of sale (mPOS)",
    "targetcurrency": "643",
    "SuccessTemplate": "ym2xmlsuccess",
    "ErrorTemplate": "ym2xmlerror",
    "ShowCaseID": "7",
    "isViaWeb": "true",
    "try-payment": "true",
    "FormComment": "Reader for mobile point of sale (mPOS)"
  },
  "form": [
    {
      "type": "text",
      "name": "Ewallet",
      "label": "Account number",
      "hint": "Money will be credited to this account",
      "value_aurofill": "currentuser_accountkey",
      "pattern": "[0-9]{11,33}",
      "required": true,
      "readonly": false
    },
    {
      "type": "tel",
      "name": "contactPhoneNumber",
      "label": "Phone number",
      "required": true,
      "readonly": false
    },
    {
      "type": "text",
      "name": "LastName",
      "label": "Last name",
      "maxlength": 150,
      "required": true,
      "readonly": false
    },
    {
      "type": "text",
      "name": "FirstName",
      "label": "Name",
      "maxlength": 150,
      "required": true,
      "readonly": false
    },
    {
      "type": "text",
      "name": "MiddleName",
      "label": "Middle name",
      "maxlength": 150,
      "required": true,
      "readonly": false
    },
    {
      "type": "select",
      "name": "DeliveryType",
      "value": "ym_msk",
      "label": "Where to get the reader",
      "options": [
        {
          "value": "ym_msk",
          "label": "at YooMoney office.Money in Moscow"
        },
        {
          "value": "ym_spb",
          "label": "at YooMoney office.Money in St. Petersburg"
        },
        {
          "value": "russianPost",
          "label": "in the Russian Post office (after delivery)",
          "group": [
            {
              "type": "select",
              "name": "country",
              "value": "Russia",
              "label": "Country",
              "options": [
                {
                  "value": "Russia",
                  "label": "Russia"
                },
                {
                  "value": "Belarus",
                  "label": "Belarus"
                },
                {
                  "value": "Ukraine",
                  "label": "Ukraine"
                },
                {
                  "value": "Moldova",
                  "label": "Moldova"
                },
                {
                  "value": "Armenia",
                  "label": "Armenia"
                },
                {
                  "value": "Azerbaijan",
                  "label": "Azerbaijan"
                },
                {
                  "value": "Kyrgyzstan",
                  "label": "Kyrgyzstan"
                },
                {
                  "value": "Kazakhstan",
                  "label": "Kazakhstan"
                },
                {
                  "value": "Tajikistan",
                  "label": "Tajikistan"
                },
                {
                  "value": "Turkmenistan",
                  "label": "Turkmenistan"
                },
                {
                  "value": "Uzbekistan",
                  "label": "Uzbekistan"
                }
              ]
            },
            {
              "type": "text",
              "name": "index_address",
              "label": "Index",
              "pattern": "[0-9]{6,8}",
              "required": true,
              "readonly": false
            },
            {
              "type": "text",
              "name": "deliveryRegion",
              "label": "Region",
              "maxlength": 44,
              "required": true,
              "readonly": false
            },
            {
              "type": "text",
              "name": "address_1",
              "label": "Locality",
              "maxlength": 150,
              "required": true,
              "readonly": false
            },
            {
              "type": "text",
              "name": "deliveryStreet",
              "label": "Street",
              "maxlength": 44,
              "required": true,
              "readonly": false
            },
            {
              "type": "text",
              "name": "deliveryHouse",
              "label": "house number",
              "maxlength": 9,
              "required": true,
              "readonly": false
            },
            {
              "type": "text",
              "name": "deliveryCorpus",
              "label": "building unit",
              "maxlength": 9,
              "required": true,
              "readonly": false
            },
            {
              "type": "text",
              "name": "deliveryBuilding",
              "label": "building",
              "maxlength": 9,
              "required": true,
              "readonly": false
            },
            {
              "type": "text",
              "name": "deliveryFlat",
              "label": "apartment",
              "maxlength": 9,
              "required": true,
              "readonly": false
            }
          ],
          "required": true,
          "readonly": false
        }
      ]
    },
    {
      "type": "p",
      "items": [
        "By clicking this button, I accept",
        {
          "type": "a",
          "href": "http://example.com/doc.xml?id=526489",
          "label": "terms of use of the mobile terminal"
        },
        "."
      ]
    },
    {
      "type": "submit",
      "label": "Continue",
      "required": true,
      "readonly": false
    }
  ]
}

Autofill macros

Autofill macros are for pre-filling form fields with specific values on the client side.

If the client processes macros, it generates value, which overrides value on the form.

If the client does not process macros, it is ignored.

Example

JSON
{
      "type": "text",
      "name": "Ewallet",
      "label": "Account number",
      "hint": "Money will be credited to this account",
      "value_autofill": "currentuser_accountkey",
      "pattern": "[0-9]{11,33}"
}

Autofill macros:

macro_name	Description
currentuser_accountkey	Substitutes the account number of the YooMoney user, if known.
calendar_next_month	Substitutes a `yyyy-mm` value in a month type field, for the next month after the current calendar month.

Defining dates and times

Time calculations are based on the ISO 8601:2004 standard.

Defining the complete date format: date string.

Format for specifying the complete date

YYYY-MM-DD

Defining the month and year format: month string.

Format for specifying the month and year

YYYY-MM

In the attributes of the date and month UI controls, you can specify:

the absolute value of the full date or the month and year;
to use the current date (now);
a value calculated from the absolute date value and an interval.

Example: Absolute date value

2014-08-19

Example: Substitute the current date

now

A value calculated from the absolute date value and an interval is defined in the section “4.4.4.2 Representations of time intervals by duration and context information” of the ISO 8601:2004 specification.

Use Basic Format to define the interval (duration):

PnYnMnD

Where:

P — a period (dot);
nY — the number of years (for example, 3Y);
nM — the number of months (for example, 10M);
nD — the number of days (for example, 5D).

Unused symbols can be omitted. For example, you can specify an interval as 3Y or 2M10D or 5D.

To specify a date in the past, use the extended format defined in the section “4.4.4.4 Representations of time interval identified by duration and end” of the ISO 8601:2004 specification:

PnYnMnD/YYYY-MM-DD
or
PnYnMnD/now

To specify a date in the future, use the extended format defined in the section “4.4.4.3 Representations of time interval identified by start and duration” of the ISO 8601:2004 specification:

YYYY-MM-DD/PnYnMnD
or
now/PnYnMnD

Example: The selected payment period must be no earlier than three years ago

JSON
{
  "type": "month",
  "name": "period",
  "label": "Payment period",
  "required": true,
  "readonly": false,
  "min": "P3Y/now"
}

Example: The selected payment period must be no later than next month

JSON
{
  "type": "month",
  "name": "period",
  "label": "Payment period",
  "required": true,
  "readonly": false,
  "max": "now/P1M"
}

Example: The selected date must be no earlier than 1 January 2005, and no later than 3.5 years after 2 January 2009

JSON
{
  "type": "date",
  "name": "document_date",
  "label": "Resolution date",
  "required": true,
  "readonly": false,
  "min":"2005-01-01",
  "max": "2009-01-02/P3Y6M"
}