Этот запрос позволяет магазину проверить корректность параметров перевода до того, как пользователь оплатит заказ (см. шаг 5 в общем сценарии оплаты). Он означает, что покупатель собирается заплатить, но не гарантирует, что оплата пройдет успешно, и не является окончательным условием для отгрузки товара. После успешной оплаты магазину придет другой запрос: Уведомление о переводе (paymentAviso).
Формирование запроса
checkOrder
чаще всего происходит до списания денег со счета плательщика. На этом шаге магазин может отказаться от приема перевода (например, если товара нет в наличии).Если магазин резервирует товар после
checkOrder
, нужно учитывать, что деньги еще не списаны: плательщик может не подтвердить оплату. Можно ориентироваться на срок действия счета и после его окончания снимать резерв.При оплате с банковской карты или через Mir Pay авторизация платежа производится до формирования запроса
checkOrder
. Если магазин после проверки отказывает в проведении платежа, деньги автоматически возвращаются на карту.Если пользователь платит не из кошелька ЮMoney, то внешние платежные системы могут брать с него дополнительную комиссию. Тогда при отказе магазина от приема платежа деньги возвращаются плательщику за вычетом этой комиссии.
Особенности использования запроса
checkOrder
для различных способов оплаты более подробно описаны в разделе Описание процесса оплаты.Имя метода:
checkOrder
checkURL
— URL в системе магазина, фиксируется на стороне ЮKassa. Можно указать при подключении.
Параметр | Тип | Описание |
---|---|---|
requestDatetime | dateTime | Момент формирования запроса в ЮKassa. |
action | normalizedString, до 16 символов | Тип запроса. Значение: checkOrder При обмене данными в формате PKCS#7 передается в качестве открывающего тега XML-документа. |
md5 | normalizedString, ровно 32 шестнадцатеричных символа, в верхнем регистре | MD5-хэш параметров платежной формы (правила формирования). Отсутствует при обмене данными в формате PKCS#7. |
shopId | long | Идентификатор магазина, выдается при подключении к ЮKassa. |
shopArticleId | long | Идентификатор товара, выдается в ЮKassa. |
invoiceId | long | Уникальный номер транзакции в ЮKassa. |
orderNumber | normalizedString, до 64 символов | Номер заказа в системе магазина. Передается, только если был указан в платежной форме. |
customerNumber | normalizedString, до 64 символов | Идентификатор плательщика на стороне магазина. Присылается в платежной форме. |
orderCreatedDatetime | dateTime | Момент регистрации заказа в ЮKassa. |
orderSumAmount | CurrencyAmount | Сумма заказа, присылается в платежной форме в параметре sum . |
orderSumCurrencyPaycash | CurrencyCode | Код валюты для суммы заказа. |
orderSumBankPaycash | CurrencyBank | Код процессингового центра в ЮKassa для суммы заказа. |
shopSumAmount | CurrencyAmount | Сумма к выплате на расчетный счет магазина (сумма заказа минус комиссия ЮKassa). |
shopSumCurrencyPaycash | CurrencyCode | Код валюты для shopSumAmount . |
shopSumBankPaycash | CurrencyBank | Код процессингового центра ЮKassa для shopSumAmount . |
paymentPayerCode | YMAccount | Номер кошелька ЮMoney, с которого производится оплата. |
paymentType | normalizedString | Способ оплаты заказа. Коды способов оплаты |
Обязательные параметры для B2B-платежей (paymentType=2S) | ||
payment_purpose | string | Назначение платежа. |
vatType | string | Тип НДС. Возможные значения:
|
vatRate | string | Ставка НДС. Обязательно, если vatType=calculated .Возможные значения:
|
vatSum | CurrencyAmount | Сумма НДС, которую вы передали в платежной форме. Присутствует, если vatType=calculated или vatType=mixed . |
Любые названия, отличные от перечисленных выше | string | Параметры, добавленные магазином в платежную форму. |
Пример запроса с использованием контрольной суммы MD5
POST /path_to_checkOrder HTTP/1.1 Host: someshop.ru Content-Type: application/x-www-form-urlencoded
Параметры запроса (пример):
requestDatetime
:2011-05-04T20:38:00.000+04:00
action
:checkOrder
md5
:8256D2A032A35709EAF156270C9EFE2E
shopId
:13
shopArticleId
:456
invoiceId
:1234567
customerNumber
:8123294469
orderCreatedDatetime
:2011-05-04T20:38:00.000+04:00
orderSumAmount
:87.10
orderSumCurrencyPaycash
:643
orderSumBankPaycash
:1001
shopSumAmount
:86.23
shopSumCurrencyPaycash
:643
shopSumBankPaycash
:1001
paymentPayerCode
:42007148320
paymentType
:AC
MyField
: Добавленное магазином поле
Пример запроса в формате PKCS#7
POST /path_to_checkOrder HTTP/1.1 Host: someshop.ru Content-Type: application/pkcs7-mime <checkOrderRequest requestDatetime="2011-05-04T20:38:00.000+04:00" invoiceId="1234567" shopId="13" shopArticleId="456" customerNumber="8123294469" orderCreatedDatetime="2011-05-04T20:38:00.000+04:00" paymentPayerCode="42007148320" orderSumAmount="87.10" orderSumCurrencyPaycash="643" orderSumBankPaycash="1001" shopSumAmount="86.23" shopSumCurrencyPaycash="643" shopSumBankPaycash="1001" paymentType="AC"> <param key="MyField" val="Поле, добавленное магазином"/> </checkOrderRequest>
Параметр | Тип | Описание |
---|---|---|
performedDatetime | dateTime | Момент обработки запроса по часам в ЮKassa. |
code | int | Код результата обработки. Список допустимых значений приведен в таблице ниже. |
shopId | long | Идентификатор магазина. Соответствует значению параметра shopId в запросе. |
invoiceId | long | Идентификатор транзакции в ЮKassa. Соответствует значению параметра invoiceId в запросе. |
orderSumAmount | CurrencyAmount | Сумма заказа в валюте, определенной параметром запроса orderSumCurrencyPaycash . |
message | string, до 255 символов | Текстовое пояснение в случае отказа принять платеж. |
techMessage | string, до 64 символов | Дополнительное текстовое пояснение ответа магазина. Как правило, используется как дополнительная информация об ошибках. Необязательное поле. |
Код | Значение | Описание ситуации |
---|---|---|
0 | Успешно | Магазин дал согласие и готов принять перевод. |
1 | Ошибка авторизации | Несовпадение значения параметра md5 с результатом расчета хэш-функции. Окончательная ошибка. |
100 | Отказ в приеме перевода | Отказ в приеме перевода с заданными параметрами. Окончательная ошибка. |
200 | Ошибка разбора запроса | Магазин не в состоянии разобрать запрос. Окончательная ошибка. |
<checkOrderResponse performedDatetime="2011-05-04T20:38:01.000+04:00" code="0" invoiceId="1234567" shopId="13" />
Магазин отказался от приема перевода на этапе проверки корректности заказа:
<checkOrderResponse performedDatetime="2011-05-04T20:38:01.000+04:00" code="100" invoiceId="1234567" shopId="13" message="Указанный номер телефона не существует" techMessage="Неверный номер телефона" />