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

Attention. Это старая версия API. Переходите на API Яндекс.Кассы.

Описание

Этот запрос позволяет магазину проверить корректность параметров перевода до того, как пользователь оплатит заказ (см. шаг 5 в общем сценарии оплаты). Он означает, что покупатель собирается заплатить, но не гарантирует, что оплата пройдет успешно, и не является окончательным условием для отгрузки товара. После успешной оплаты магазину придет другой запрос: Уведомление о переводе (paymentAviso).

Note.
  • Формирование запроса checkOrder чаще всего происходит до списания денег со счета плательщика. На этом шаге магазин может отказаться от приема перевода (например, если товара нет в наличии).
  • Если магазин резервирует товар после checkOrder, нужно учитывать, что деньги еще не списаны: плательщик может не подтвердить оплату. Можно ориентироваться на срок действия счета и после его окончания снимать резерв.
  • При оплате с банковской карты авторизация платежа производится до формирования запроса checkOrder. Если магазин после проверки отказывает в проведении платежа, деньги автоматически возвращаются на карту.
  • Если пользователь платит не из кошелька в Яндекс.Деньгах, то внешние платежные системы могут брать с него дополнительную комиссию. Тогда при отказе магазина от приема платежа деньги возвращаются плательщику за вычетом этой комиссии.

Особенности использования запроса checkOrder для различных способов оплаты более подробно описаны в разделе Описание процесса оплаты.

Имя метода

checkOrder

Адрес для получения запроса

checkURL — URL в системе магазина, фиксируется на стороне Яндекс.Кассы. Можно указать при подключении.

Входные параметры

Параметр

Тип

Описание

requestDatetime

dateTime

Момент формирования запроса в Яндекс.Кассе.

action

normalizedString, до 16 символов

Тип запроса. Значение: checkOrder

При обмене данными в формате PKCS#7 передается в качестве открывающего тега XML-документа.

md5

normalizedString, ровно 32 шестнадцатеричных символа, в верхнем регистре

MD5-хэш параметров платежной формы (правила формирования).

Отсутствует при обмене данными в формате PKCS#7.

shopId

long

Идентификатор магазина, выдается при подключении к Яндекс.Кассе.

shopArticleId

long

Идентификатор товара, выдается в Яндекс.Кассе.

invoiceId

long

Уникальный номер транзакции в Яндекс.Кассе.

orderNumber

normalizedString, до 64 символов

Номер заказа в системе магазина. Передается, только если был указан в платежной форме.

customerNumber

normalizedString, до 64 символов

Идентификатор плательщика на стороне магазина. Присылается в платежной форме.

orderCreatedDatetime

dateTime

Момент регистрации заказа в Яндекс.Кассе.

orderSumAmount

CurrencyAmount

Сумма заказа, присылается в платежной форме в параметре sum.

orderSumCurrencyPaycash

CurrencyCode

Код валюты для суммы заказа.

orderSumBankPaycash

CurrencyBank

Код процессингового центра в Яндекс.Кассе для суммы заказа.

shopSumAmount

CurrencyAmount

Сумма к выплате на расчетный счет магазина (сумма заказа минус комиссия Яндекс.Кассы).

shopSumCurrencyPaycash

CurrencyCode

Код валюты для shopSumAmount.

shopSumBankPaycash

CurrencyBank

Код процессингового центра Яндекс.Кассы для shopSumAmount.

paymentPayerCode

YMAccount

Номер кошелька в Яндекс.Деньгах, с которого производится оплата.

paymentType

normalizedString

Способ оплаты заказа. Коды способов оплаты

Обязательные параметры для B2B-платежей (paymentType=2S)
payment_purpose

string

Назначение платежа.
vatType

string

Тип НДС. Возможные значения:
  • calculated — облагается на логом:
  • untaxed — не облагается.
vatRate

string

Ставка НДС. Присутствует, если vatType=calculated.

Возможные значения:

  • 0 — ставка НДС 0%;
  • 7 — ставка 7%;
  • 10 — ставка 10%;
  • 18 — ставка 18%.
vatSumCurrencyAmountСумма НДС, которую вы передали в платежной форме. Присутствует, если vatType=calculated.

Любые названия, отличные от перечисленных выше

string

Параметры, добавленные магазином в платежную форму.

Параметр

Тип

Описание

requestDatetime

dateTime

Момент формирования запроса в Яндекс.Кассе.

action

normalizedString, до 16 символов

Тип запроса. Значение: checkOrder

При обмене данными в формате PKCS#7 передается в качестве открывающего тега XML-документа.

md5

normalizedString, ровно 32 шестнадцатеричных символа, в верхнем регистре

MD5-хэш параметров платежной формы (правила формирования).

Отсутствует при обмене данными в формате PKCS#7.

shopId

long

Идентификатор магазина, выдается при подключении к Яндекс.Кассе.

shopArticleId

long

Идентификатор товара, выдается в Яндекс.Кассе.

invoiceId

long

Уникальный номер транзакции в Яндекс.Кассе.

orderNumber

normalizedString, до 64 символов

Номер заказа в системе магазина. Передается, только если был указан в платежной форме.

customerNumber

normalizedString, до 64 символов

Идентификатор плательщика на стороне магазина. Присылается в платежной форме.

orderCreatedDatetime

dateTime

Момент регистрации заказа в Яндекс.Кассе.

orderSumAmount

CurrencyAmount

Сумма заказа, присылается в платежной форме в параметре sum.

orderSumCurrencyPaycash

CurrencyCode

Код валюты для суммы заказа.

orderSumBankPaycash

CurrencyBank

Код процессингового центра в Яндекс.Кассе для суммы заказа.

shopSumAmount

CurrencyAmount

Сумма к выплате на расчетный счет магазина (сумма заказа минус комиссия Яндекс.Кассы).

shopSumCurrencyPaycash

CurrencyCode

Код валюты для shopSumAmount.

shopSumBankPaycash

CurrencyBank

Код процессингового центра Яндекс.Кассы для shopSumAmount.

paymentPayerCode

YMAccount

Номер кошелька в Яндекс.Деньгах, с которого производится оплата.

paymentType

normalizedString

Способ оплаты заказа. Коды способов оплаты

Обязательные параметры для B2B-платежей (paymentType=2S)
payment_purpose

string

Назначение платежа.
vatType

string

Тип НДС. Возможные значения:
  • calculated — облагается на логом:
  • untaxed — не облагается.
vatRate

string

Ставка НДС. Присутствует, если vatType=calculated.

Возможные значения:

  • 0 — ставка НДС 0%;
  • 7 — ставка 7%;
  • 10 — ставка 10%;
  • 18 — ставка 18%.
vatSumCurrencyAmountСумма НДС, которую вы передали в платежной форме. Присутствует, если vatType=calculated.

Любые названия, отличные от перечисленных выше

string

Параметры, добавленные магазином в платежную форму.

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

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

Параметр

Тип

Описание

performedDatetime

dateTime

Момент обработки запроса по часам в Яндекс.Кассе.

code

int

Код результата обработки. Список допустимых значений приведен в таблице ниже.

shopId

long

Идентификатор магазина. Соответствует значению параметра shopId в запросе.

invoiceId

long

Идентификатор транзакции в Яндекс.Кассе. Соответствует значению параметра invoiceId в запросе.

orderSumAmount

CurrencyAmount

Сумма заказа в валюте, определенной параметром запроса orderSumCurrencyPaycash.

message

string, до 255 символов

Текстовое пояснение в случае отказа принять платеж.

techMessage

string, до 64 символов

Дополнительное текстовое пояснение ответа магазина.

Как правило, используется как дополнительная информация об ошибках. Необязательное поле.

Параметр

Тип

Описание

performedDatetime

dateTime

Момент обработки запроса по часам в Яндекс.Кассе.

code

int

Код результата обработки. Список допустимых значений приведен в таблице ниже.

shopId

long

Идентификатор магазина. Соответствует значению параметра shopId в запросе.

invoiceId

long

Идентификатор транзакции в Яндекс.Кассе. Соответствует значению параметра invoiceId в запросе.

orderSumAmount

CurrencyAmount

Сумма заказа в валюте, определенной параметром запроса orderSumCurrencyPaycash.

message

string, до 255 символов

Текстовое пояснение в случае отказа принять платеж.

techMessage

string, до 64 символов

Дополнительное текстовое пояснение ответа магазина.

Как правило, используется как дополнительная информация об ошибках. Необязательное поле.

Коды результата обработки запроса

Код

Значение

Описание ситуации

0

Успешно

Магазин дал согласие и готов принять перевод.

1

Ошибка авторизации

Несовпадение значения параметра md5 с результатом расчета хэш-функции. Окончательная ошибка.

100

Отказ в приеме перевода

Отказ в приеме перевода с заданными параметрами. Окончательная ошибка.

200

Ошибка разбора запроса

Магазин не в состоянии разобрать запрос. Окончательная ошибка.

Код

Значение

Описание ситуации

0

Успешно

Магазин дал согласие и готов принять перевод.

1

Ошибка авторизации

Несовпадение значения параметра md5 с результатом расчета хэш-функции. Окончательная ошибка.

100

Отказ в приеме перевода

Отказ в приеме перевода с заданными параметрами. Окончательная ошибка.

200

Ошибка разбора запроса

Магазин не в состоянии разобрать запрос. Окончательная ошибка.

Примеры

Пример запроса с использованием контрольной суммы 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

shopArticleId456

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

Добавленное магазином поле

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

requestDatetime

2011-05-04T20:38:00.000+04:00

action

checkOrder

md5

8256D2A032A35709EAF156270C9EFE2E

shopId

13

shopArticleId456

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>
Пример ответа при успехе обработки
<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="Неверный номер телефона"/>