Проверка заказа (checkOrder) — [Архив] Протокол приема платежей через ЮKassa

Проверка заказа (checkOrder)

Это старая версия API. Переходите на API ЮKassa.

Этот запрос позволяет магазину проверить корректность параметров перевода до того, как пользователь оплатит заказ (см. шаг 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	Тип НДС. Возможные значения: `calculated` — облагается налогом, у всех товаров одинаковая ставка; `untaxed` — не облагается; `mixed` — товары в платеже облагаются налогом по-разному.
vatRate	string	Ставка НДС. Обязательно, если `vatType=calculated`. Возможные значения: `0` — ставка НДС 0%; `7` — ставка 7%; `10` — ставка 10%; `18` — ставка 18%; `20` — ставка 20%.
vatSum	CurrencyAmount	Сумма НДС, которую вы передали в платежной форме. Присутствует, если `vatType=calculated` или `vatType=mixed`.
Любые названия, отличные от перечисленных выше	string	Параметры, добавленные магазином в платежную форму.

Запросы могут содержать параметры, не описанные в этом документе. Магазину следует их игнорировать.
Запрос может содержать не все параметры. Обязательно присутствуют только параметры, которые нужны для расчета контрольной суммы MD5 (action, orderSumAmount, orderSumCurrencyPaycash, orderSumBankPaycash, shopId, invoiceId, customerNumber).

Примеры запроса

Пример запроса с использованием контрольной суммы 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	Ошибка разбора запроса	Магазин не в состоянии разобрать запрос. Окончательная ошибка.

Примеры ответа

Пример ответа при успехе обработки

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="Неверный номер телефона"
/>