API ЮKassa
Помощь
Подключить ЮKassa
Проверка заказа (checkOrder)
Этот запрос позволяет магазину проверить корректность параметров перевода до того, как пользователь оплатит заказ (см. шаг 5 в общем сценарии оплаты). Он означает, что покупатель собирается заплатить, но не гарантирует, что оплата пройдет успешно, и не является окончательным условием для отгрузки товара. После успешной оплаты магазину придет другой запрос: Уведомление о переводе (paymentAviso).
Особенности
Формирование запроса checkOrder чаще всего происходит до списания денег со счета плательщика. На этом шаге магазин может отказаться от приема перевода (например, если товара нет в наличии).
Если магазин резервирует товар после checkOrder, нужно учитывать, что деньги еще не списаны: плательщик может не подтвердить оплату. Можно ориентироваться на срок действия счета и после его окончания снимать резерв.
При оплате с банковской карты или через Mir Pay авторизация платежа производится до формирования запроса checkOrder. Если магазин после проверки отказывает в проведении платежа, деньги автоматически возвращаются на карту.
Если пользователь платит не из кошелька ЮMoney, то внешние платежные системы могут брать с него дополнительную комиссию. Тогда при отказе магазина от приема платежа деньги возвращаются плательщику за вычетом этой комиссии.
Особенности использования запроса checkOrder для различных способов оплаты более подробно описаны в разделе Описание процесса оплаты.
Запрос
Имя метода: checkOrder
Адрес для получения запроса
checkURL
 — URL в системе магазина, фиксируется на стороне ЮKassa. Можно указать при подключении.
Входные параметры
ПараметрТипОписание
requestDatetimedateTimeМомент формирования запроса в ЮKassa.
actionnormalizedString,
до 16 символов
Тип запроса. Значение: checkOrder
При обмене данными в формате PKCS#7 передается в качестве открывающего тега XML-документа.
md5normalizedString,
ровно 32 шестнадцатеричных символа, в верхнем регистре
MD5-хэш параметров платежной формы (правила формирования).
Отсутствует при обмене данными в формате PKCS#7.
shopIdlongИдентификатор магазина, выдается при подключении к ЮKassa.
shopArticleIdlongИдентификатор товара, выдается в ЮKassa.
invoiceIdlongУникальный номер транзакции в ЮKassa.
orderNumbernormalizedString,
до 64 символов
Номер заказа в системе магазина. Передается, только если был указан в платежной форме.
customerNumbernormalizedString,
до 64 символов
Идентификатор плательщика на стороне магазина. Присылается в платежной форме.
orderCreatedDatetimedateTimeМомент регистрации заказа в ЮKassa.
orderSumAmountCurrencyAmountСумма заказа, присылается в платежной форме в параметре sum.
orderSumCurrencyPaycashCurrencyCodeКод валюты для суммы заказа.
orderSumBankPaycashCurrencyBankКод процессингового центра в ЮKassa для суммы заказа.
shopSumAmountCurrencyAmountСумма к выплате на расчетный счет магазина (сумма заказа минус комиссия ЮKassa).
shopSumCurrencyPaycashCurrencyCodeКод валюты для shopSumAmount.
shopSumBankPaycashCurrencyBankКод процессингового центра ЮKassa для shopSumAmount.
paymentPayerCodeYMAccountНомер кошелька ЮMoney, с которого производится оплата.
paymentTypenormalizedStringСпособ оплаты заказа. Коды способов оплаты
Обязательные параметры для B2B-платежей (paymentType=2S)
payment_purposestringНазначение платежа.
vatTypestring
Тип НДС. Возможные значения:
  • calculated — облагается налогом, у всех товаров одинаковая ставка;
  • untaxed — не облагается;
  • mixed — товары в платеже облагаются налогом по-разному.
vatRatestring
Ставка НДС. Обязательно, если vatType=calculated.
Возможные значения:
  • 0 — ставка НДС 0%;
  • 7 — ставка 7%;
  • 10 — ставка 10%;
  • 18 — ставка 18%;
  • 20 — ставка 20%.
vatSumCurrencyAmountСумма НДС, которую вы передали в платежной форме. Присутствует, если 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>
Ответ
Параметры ответа
ПараметрТипОписание
performedDatetimedateTimeМомент обработки запроса по часам в ЮKassa.
codeintКод результата обработки. Список допустимых значений приведен в таблице ниже.
shopIdlongИдентификатор магазина. Соответствует значению параметра shopId в запросе.
invoiceIdlongИдентификатор транзакции в ЮKassa. Соответствует значению параметра invoiceId в запросе.
orderSumAmountCurrencyAmountСумма заказа в валюте, определенной параметром запроса orderSumCurrencyPaycash.
messagestring,
до 255 символов
Текстовое пояснение в случае отказа принять платеж.
techMessagestring,
до 64 символов
Дополнительное текстовое пояснение ответа магазина.
Как правило, используется как дополнительная информация об ошибках. Необязательное поле.
Коды результата обработки запроса
КодЗначениеОписание ситуации
0УспешноМагазин дал согласие и готов принять перевод.
1Ошибка авторизацииНесовпадение значения параметра md5 с результатом расчета хэш-функции. Окончательная ошибка.
100Отказ в приеме переводаОтказ в приеме перевода с заданными параметрами. Окончательная ошибка.
200Ошибка разбора запросаМагазин не в состоянии разобрать запрос. Окончательная ошибка.
Примеры ответа
Пример ответа при успехе обработки
XML
<checkOrderResponse
  performedDatetime="2011-05-04T20:38:01.000+04:00"
  code="0"
  invoiceId="1234567"
  shopId="13"
/>
Пример ответа при ошибке
Магазин отказался от приема перевода на этапе проверки корректности заказа:
XML
<checkOrderResponse
  performedDatetime="2011-05-04T20:38:01.000+04:00"
  code="100"
  invoiceId="1234567"
  shopId="13"
  message="Указанный номер телефона не существует"
  techMessage="Неверный номер телефона"
/>