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:
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 ОК 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"}]}