Sending a form or step of a form to the server

Request format

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.

Note. 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.
Note. 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: Russian.

Accept-Encoding

Indicates client support for traffic compression. Supported values:

By default: file compression is not used.

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.
Note. 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 given in the HTTP Location header.
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 Location header. 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 Yandex.Money wallet, or using a bank card).

Response format with a list of parameters for payment processing
{
  "params": {
    "param1": "value1",
    "param2": "value2",
    ...
    "paramN": "valueN"
  }
}

List of errors from 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:

{  ... 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"    }  ]}

Examples

Request example
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
The data entered by the buyer was verified successfully and payment parameters were returned
HTTP/1.1 200 ОКContent-Type: application/jsonContent-Length: 197Cache-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"}}
The data entered by the buyer contains errors, and the returned document contains the reason for the error
HTTP/1.1 400 Bad RequestLocation: https://money.yandex.ru/api/showcase/validate/5506/Content-Type: application/jsonContent-Length: 733Cache-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"}]}