Sending a form or step of a form to the serve

Sending a form or step of a form to the server

Request

The address for submitting the form is in the Location header of the response to the request for the form description, or the response to sending form data for the previous step of a multistep form.

The client must always take the address for sending the form from the server response, and never store it for later use.

Data should be submitted using the POST method, Сontent-Type: application/x-www-form-urlencoded, with UTF‑8 encoding.

The request must contain the following parameters:

the content of all visible UI controls on the form;
the content of the hidden_fields section, if it exists in the form description.

If a UI control on the form is visible, optional, and the buyer left it empty, the name of the control’s field and an empty value are added to the request. Web browsers behave the same way.

The request may contain the following HTTP headers:

Header	Description
Accept-Language	The code of the language that the client wants to get the form description in, conforming to RFC-5646: Tags for Identifying Languages, IANA Language Subtag Registry. Possible values: `ru` — Russian; `en` — English. By default: `ru`
Accept-Encoding	Indicates client support for traffic compression. Supported values: `gzip` — Support for GZIP transfer encoding (RFC-1952: GZIP file format specification). By default: file compression is not used.

Request example

POST /api/showcase/validate/5551/step_INN_3038 HTTP/1.1
Host: yoomoney.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

Response

The method returns one of the following responses:

an indication that form data was verified successfully, along with payment parameters — this is the final state of the form;
an indication that form data was verified successfully, along with a description of the next step of the form;
a list of errors from checking data entered by the buyer, and a description of the current step of the form.

The response to this method must not be cached, since its contents depend on the data entered by the buyer.

Possible HTTP response codes:

HTTP response code	Description
200 OK	The information entered by the buyer was verified successfully; this is the last step of the form. The response contains a list of parameters for processing the payment.
300 Multiple Choices	The information entered by the buyer was verified successfully, and there is another step for the form. The response contains the description of the next step of the payment form. The address for sending the next step of the form is specified in the HTTP header Location.
400 Bad Request	The client specified invalid data in the form fields. The response contains a list of errors in the form data verification, along with the description of the current step of the form with pre-filled values entered by the buyer. The address for re-sending the form is given in the HTTP header Location. The client must correct the form data and re-send it.
404 Not Found	The requested payment form does not exist or is not allowed to be used. The response body is omitted.
500 Internal Server Error	The service is temporarily unavailable for technical reasons.

List of parameters for processing payment

The list of payment processing parameters is a collection of name-value pairs. This set should be passed as arguments for the payment function call from a YooMoney wallet.

Response format with a list of parameters for payment processing

JSON
{
  "params": {
    "param1": "value1",
    "param2": "value2",
    ...
    "paramN": "valueN"
  }
}

Example: The data entered by the buyer was verified successfully and payment parameters were returned

JSON
HTTP/1.1 200 OK
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"}}

Verifying data entered by the buyer

The server checks all the form field values and their logical combinations.

If errors are found, the server responds with:

a description of the current step of the form with pre-filled values entered by the buyer;
a list of errors in the error section.

Each item in the list of errors contains:

Field	Description
name	The name of the field containing an invalid value. If the error cannot be related to a specific field in the form, this parameter is omitted.
alert	The error message text.

Format of a response with a list of errors verifying data entered by the buyer

JSON
{
  ... description of the current step in the form ...
  "form": [
    ...
  ],
 "error": [
    {
      "name": "field1",
      "alert": "Error message"
    },
    ...
    {
      "name": "fieldN",
      "alert": "Error message"
    }
    ...
    {
      "alert": "Error message that isn't related to a specific field"
    }
  ]
}

Example: The data entered by the buyer contains errors, and the returned document contains the reason for the error

JSON
HTTP/1.1 400 Bad Request
Location: https://yoomoney.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":"Name","required":false,"readonly":false},{"type":"text","name":"skypename","label":"Skype login","required":true,"readonly":false},{"type":"amount","name":"netSum","value":"2","label":"Amount","required":true,"readonly":false,"min":0.01,"max":375,"currency":"EUR"}]},{"type":"submit","label":"Pay"}],"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":"Please enter the Skype login name"}]}