Создать заказ с динамическим QR-кодом

Генерирует и активирует динамический QR-код. Выведите QR-код на экран или распечатайте, после этого покупатель отсканирует его и оплатит заказ.

Если в ответе статус 5XX, повторите запрос.

Совет

Пошаговые инструкции см. в разделе Самостоятельная интеграция.

Скачайте OpenAPI-спецификацию в разделе Specification.

Аутентификация запросов

В каждом запросе передавайте в HTTP-заголовки:

YandexPayApiKey

Заголовок: Authorization: Api-Key <ключ>.

Выпустите его личном кабинете по инструкции.

SoftwareAuthorization

Заголовок: Software-Authorization: <ключ>.

Токен кассового ПО. Получите его у менеджера интеграции.

Если в запросе отсутствуют или переданы недействительные токены, сервер вернет статус 401 Unauthorized.

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

curl https://pay.yandex.ru/api/merchant/cash-register/v1/accounts \
  --header 'Authorization: Api-Key <YandexPayApiKey>' \
  --header 'Software-Authorization: <SoftwareAuthorization>' \

Request

POST

https://sandbox.pay.yandex.ru/api/merchant/cash-register/v1/orders/dynamic

Sandbox

POST

https://pay.yandex.ru/api/merchant/cash-register/v1/orders/dynamic

Production

Body

application/json
{
  "cart": {
    "items": [
      {
        "productId": "1234567890",
        "quantity": {},
        "title": "Хлеб",
        "total": "123.45",
        "description": "example",
        "unitPrice": "123.45"
      }
    ],
    "total": {
      "amount": "123.45"
    }
  },
  "currencyCode": "RUB",
  "orderId": "01963e94-7457-74da-8739-fa7ea310a255",
  "availablePaymentMethods": [
    "CARD"
  ],
  "billingPhone": "+79999999999",
  "extensions": {
    "billingReport": {
      "branchId": "01967cb8-f2c4-7293-9027-2976830c9485",
      "managerId": "01967cb9-67b9-7942-99c2-bf95331d137d"
    }
  },
  "orderSource": "WEBSITE",
  "purpose": "Оплата по заказу 12345",
  "metadata": "example",
  "ttl": 600
}
All of 2 types

  • Type: CreateOrder

    Example
    {
  "cart": {
    "items": [
      {
        "productId": "1234567890",
        "quantity": {
          "count": "123.45"
        },
        "title": "Хлеб",
        "total": "123.45",
        "description": "example",
        "unitPrice": "123.45"
      }
    ],
    "total": {
      "amount": "123.45"
    }
  },
  "currencyCode": "RUB",
  "orderId": "01963e94-7457-74da-8739-fa7ea310a255",
  "availablePaymentMethods": [
    "CARD"
  ],
  "billingPhone": "+79999999999",
  "extensions": {
    "billingReport": {
      "branchId": "01967cb8-f2c4-7293-9027-2976830c9485",
      "managerId": "01967cb9-67b9-7942-99c2-bf95331d137d"
    }
  },
  "orderSource": "WEBSITE",
  "purpose": "Оплата по заказу 12345",
  "metadata": "example"
}
  • Type: object

    ttl

    Type: integer

    Время жизни QR-кода в секундах.

    Default: 600

    Min value: 180

    Max value: 43200
    Example
    {
  "ttl": 600
}

ItemQuantity

Количество единиц товара в позиции.

Name

Description

count

Type: string<double>

Количество единиц товара в позиции.

Example: 123.45
Example
{
  "count": "123.45"
}

CartItem

Name

Description

productId

Type: string

Идентификатор товара в системе продавца. В заказе все productId должны быть уникальными.

Max length: 2048

Example: 1234567890

quantity

Type: ItemQuantity

Количество единиц товара в позиции.

Example
{
  "count": "123.45"
}

title

Type: string

Наименование товара.

Max length: 2048

Example: Хлеб

total

Type: string<double>

Сумма позиции с учетом скидок.

Example: 123.45

description

Type: string

Описание товара.

Max length: 2048

Example: example

unitPrice

Type: string<double>

Цена за единицу товара. Используется в расширенной логике возвратов.

Примеры:

  • 5.50 — 5 рублей 50 копеек за 1 ручку;
  • 800 — 800 рублей за килограмм мяса.

Example: 123.45
Example
{
  "productId": "1234567890",
  "quantity": {
    "count": "123.45"
  },
  "title": "Хлеб",
  "total": "123.45",
  "description": "example",
  "unitPrice": "123.45"
}

CartTotal

Итоговая информация о стоимости заказа.

Name

Description

amount

Type: string<double>

Сумма корзины с учетом всех скидок. Должна быть больше или равна 1.

Example: 123.45
Example
{
  "amount": "123.45"
}

Cart

Корзина.

Если в корзине есть позиции с нецелыми ценами (3 ручки за 10 рублей) или весовые товары (500 г. говядины), для всех позиций в корзине добавьте цену за единицу товара unitPrice. Это избавит от проблем с округлением, например, при возврате.

Name

Description

items

Type: CartItem[]

Список позиций в заказе.

Min items: 1

Example
[
  {
    "productId": "1234567890",
    "quantity": {
      "count": "123.45"
    },
    "title": "Хлеб",
    "total": "123.45",
    "description": "example",
    "unitPrice": "123.45"
  }
]

total

Type: CartTotal

Итоговая информация о стоимости заказа.

Example
{
  "amount": "123.45"
}
Example
{
  "items": [
    {
      "productId": "1234567890",
      "quantity": {
        "count": "123.45"
      },
      "title": "Хлеб",
      "total": "123.45",
      "description": "example",
      "unitPrice": "123.45"
    }
  ],
  "total": {
    "amount": "123.45"
  }
}

Currency

Трехбуквенный код валюты (ISO 4217).

Type: string

Default: RUB

Const: RUB

Example: RUB

AvailablePaymentMethod

Методы оплаты, которые будут доступны покупателю в платежной форме Яндекс Пэй.

Не передавайте это поле, если нет необходимости отключать методы оплаты.

Возможные варианты:

  • поле не передано — доступны все методы;
  • ["CARD", "SPLIT"] — доступны все методы;
  • ["SPLIT"] — доступны все методы;
  • ["CARD"] — доступны все методы, кроме Сплита.

Если Сплит отключен в личном кабинете, он не будет доступен для оплаты, даже если указан в availablePaymentMethods.

Type: string

Enum: CARD, SPLIT

OrderSource

Поверхность, на которой инициализировали создание заказа. Необходимо для последующей аналитики.

  • WEBSITE — Кнопка размещена на сайте. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя на сайте.

  • APP — Кнопка размещена в мобильном приложении. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя в приложении.

  • CRM — Ссылка на оплату сформирована менеджером в CRM или другой админке.

  • CASH_REGISTER — Ссылка на оплату сформирована для отображения на оффлайн-кассе.

  • CMS_PLUGIN — Ссылка на оплату сформирована в плагине для CMS.

Type: string

Enum: WEBSITE, APP, CRM, CASH_REGISTER, CMS_PLUGIN

CreateOrder

Name

Description

cart

Type: Cart

Корзина.

Если в корзине есть позиции с нецелыми ценами (3 ручки за 10 рублей) или весовые товары (500 г. говядины), для всех позиций в корзине добавьте цену за единицу товара unitPrice. Это избавит от проблем с округлением, например, при возврате.

Example
{
  "items": [
    {
      "productId": "1234567890",
      "quantity": {
        "count": "123.45"
      },
      "title": "Хлеб",
      "total": "123.45",
      "description": "example",
      "unitPrice": "123.45"
    }
  ],
  "total": {
    "amount": "123.45"
  }
}

currencyCode

Type: Currency

Трехбуквенный код валюты (ISO 4217).

Default: RUB

Enum: RUB

orderId

Type: string

Идентификатор заказа в системе продавца.

Max length: 45

Example: 01963e94-7457-74da-8739-fa7ea310a255

availablePaymentMethods

Type: AvailablePaymentMethod[]

Min items: 1

Example
[
  "CARD"
]

billingPhone

Type: string

Номер телефона клиента.

Используется для упрощения авторизации, а также может увеличить вероятность одобрения по Сплиту.

Номер телефона должен начинаться с +7, далее 10 цифр.

Min length: 12

Max length: 12

Pattern: ^\+7\d{10}$

Example: +79999999999

extensions
Type: object

billingReport
Type: object

branchId

Type: string

Идентификатор точки продаж в системе продавца.

Max length: 2048

Example: 01967cb8-f2c4-7293-9027-2976830c9485

managerId

Type: string

Идентификатор кассира в системе продавца.

Max length: 2048

Example: 01967cb9-67b9-7942-99c2-bf95331d137d

Информация о месте и авторе оформления заказа.

Example
{
  "branchId": "01967cb8-f2c4-7293-9027-2976830c9485",
  "managerId": "01967cb9-67b9-7942-99c2-bf95331d137d"
}

Дополнительные параметры для оформления заказа:

  • billingReport — информация о месте и авторе оформления заказа;
  • branchId — идентификатор точки продаж в системе продавца;
  • managerId — идентификатор кассира в системе продавца.
{
  "extensions": {
    "billingReport": {
        "branchId": "01967cb8-f2c4-7293-9027-2976830c9485",
        "managerId": "01967cb9-67b9-7942-99c2-bf95331d137d"
    }
  }
}
Example
{
  "billingReport": {
    "branchId": "01967cb8-f2c4-7293-9027-2976830c9485",
    "managerId": "01967cb9-67b9-7942-99c2-bf95331d137d"
  }
}

metadata

Type: string

Произвольные данные по заказу для внутреннего использования.

Max length: 2048

Example: example

orderSource

Type: OrderSource

Поверхность, на которой инициализировали создание заказа. Необходимо для последующей аналитики.

  • WEBSITE — Кнопка размещена на сайте. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя на сайте.

  • APP — Кнопка размещена в мобильном приложении. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя в приложении.

  • CRM — Ссылка на оплату сформирована менеджером в CRM или другой админке.

  • CASH_REGISTER — Ссылка на оплату сформирована для отображения на оффлайн-кассе.

  • CMS_PLUGIN — Ссылка на оплату сформирована в плагине для CMS.

Enum: WEBSITE, APP, CRM, CASH_REGISTER, CMS_PLUGIN

purpose

Type: string

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

Max length: 140

Example: Оплата по заказу 12345
Example
{
  "cart": {
    "items": [
      {
        "productId": "1234567890",
        "quantity": {
          "count": "123.45"
        },
        "title": "Хлеб",
        "total": "123.45",
        "description": "example",
        "unitPrice": "123.45"
      }
    ],
    "total": {
      "amount": "123.45"
    }
  },
  "currencyCode": "RUB",
  "orderId": "01963e94-7457-74da-8739-fa7ea310a255",
  "availablePaymentMethods": [
    "CARD"
  ],
  "billingPhone": "+79999999999",
  "extensions": {
    "billingReport": {
      "branchId": "01967cb8-f2c4-7293-9027-2976830c9485",
      "managerId": "01967cb9-67b9-7942-99c2-bf95331d137d"
    }
  },
  "orderSource": "WEBSITE",
  "purpose": "Оплата по заказу 12345",
  "metadata": "example"
}

Responses

200 OK

Заказ создан.

Body

application/json
{
  "data": {
    "paymentUrl": "https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3"
  },
  "code": 200,
  "status": "success"
}

Name

Description

data
Type: object

paymentUrl

Type: string

Ссылка на оплату заказа.

Max length: 2048

Example: https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3

paymentUrl — ссылка на оплату заказа.

{
  "data": {
    "paymentUrl": "https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3"
  }
}
Example
{
  "paymentUrl": "https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3"
}

code

Type: integer

Default: 200

status

Type: string

Default: success

400 Bad Request

Ошибка валидации или бизнес-логики.

Body

application/json
{
  "status": "fail",
  "reason": "Invalid cart item parameter: total = 200.5004",
  "reasonCode": "VALIDATION_ERROR"
}
All of 2 types

  • Type: Error

    Example
    {
  "status": "fail",
  "reason": "example"
}
  • Type: object

    reasonCode

    Type: BadRequestErrorReasonCode

    Код ошибки:

    • VALIDATION_ERROR — Ошибка валидации. Тело или параметры запроса не соответствуют спецификации.
    • QRC_ID_NOT_FOUND — QR-код не найден, QR-табличка не привязана к продавцу.
    • ORDER_COLLISION — Заказ с таким идентификатором уже существует, при этом его параметры отличаются от указанных в запросе.
    • ORDER_NOT_FOUND — Заказ не найден.
    • ORDER_ALREADY_CAPTURED — Заказ уже оплачен.
    • ORDER_NOT_CAPTURED — Заказ не оплачен.
    • ORDER_REFUND_COLLISION — Операция возврата заказа уже существует, при этом ее параметры отличаются от указанных в запросе.
    • ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND — Запрос на частичный возврат без указания корзины. Для проведения частичного возврата заполните поле refundCart.
    • ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID — productId отсутствует в корзине заказа.
    • ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID — productId должен быть уникальным.
    • ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY — Некорректная комбинация цены и количества единиц товара для возврата.
    • ORDERUPDATE_INVALID_ITEM_PRICE_RANGE — Неверно задана цена за единицу товара для возврата.
    • ORDERUPDATE_INVALID_ITEM_QUANTITY — Неверно задано количество единиц товара для возврата.
    • ANOTHER_REFUND_IN_PROGRESS — Другой возврат уже в процессе, дождитесь его завершения.

    Список кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.

    Enum: VALIDATION_ERROR, QRC_ID_NOT_FOUND, ORDER_COLLISION, ORDER_NOT_FOUND, ORDER_ALREADY_CAPTURED, ORDER_NOT_CAPTURED, ORDER_REFUND_COLLISION, ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND, ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID, ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID, ORDERUPDATE_INVALID_ITEM_PRICE_RANGE, ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY, ORDERUPDATE_INVALID_ITEM_QUANTITY, ANOTHER_REFUND_IN_PROGRESS

    reason

    Type: string

    Example: Invalid cart item parameter: total = 200.5004
    Example
    {
  "reasonCode": "VALIDATION_ERROR",
  "reason": "Invalid cart item parameter: total = 200.5004"
}

Error

Name

Description

reason

Type: string

Описание ошибки.

Example: example

status

Type: string

Default: fail

Const: fail
Example
{
  "status": "fail",
  "reason": "example"
}

BadRequestErrorReasonCode

Код ошибки:

  • VALIDATION_ERROR — Ошибка валидации. Тело или параметры запроса не соответствуют спецификации.
  • QRC_ID_NOT_FOUND — QR-код не найден, QR-табличка не привязана к продавцу.
  • ORDER_COLLISION — Заказ с таким идентификатором уже существует, при этом его параметры отличаются от указанных в запросе.
  • ORDER_NOT_FOUND — Заказ не найден.
  • ORDER_ALREADY_CAPTURED — Заказ уже оплачен.
  • ORDER_NOT_CAPTURED — Заказ не оплачен.
  • ORDER_REFUND_COLLISION — Операция возврата заказа уже существует, при этом ее параметры отличаются от указанных в запросе.
  • ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND — Запрос на частичный возврат без указания корзины. Для проведения частичного возврата заполните поле refundCart.
  • ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID — productId отсутствует в корзине заказа.
  • ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID — productId должен быть уникальным.
  • ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY — Некорректная комбинация цены и количества единиц товара для возврата.
  • ORDERUPDATE_INVALID_ITEM_PRICE_RANGE — Неверно задана цена за единицу товара для возврата.
  • ORDERUPDATE_INVALID_ITEM_QUANTITY — Неверно задано количество единиц товара для возврата.
  • ANOTHER_REFUND_IN_PROGRESS — Другой возврат уже в процессе, дождитесь его завершения.

Список кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.

Type: string

Enum: VALIDATION_ERROR, QRC_ID_NOT_FOUND, ORDER_COLLISION, ORDER_NOT_FOUND, ORDER_ALREADY_CAPTURED, ORDER_NOT_CAPTURED, ORDER_REFUND_COLLISION, ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND, ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID, ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID, ORDERUPDATE_INVALID_ITEM_PRICE_RANGE, ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY, ORDERUPDATE_INVALID_ITEM_QUANTITY, ANOTHER_REFUND_IN_PROGRESS

401 Unauthorized

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

Body

application/json
{
  "status": "fail",
  "reason": "Authorization header is missing",
  "reasonCode": "AUTHENTICATION_ERROR"
}
All of 2 types

  • Type: Error

    Example
    {
  "status": "fail",
  "reason": "example"
}
  • Type: object

    reasonCode

    Type: UnauthorizedErrorReasonCode

    Код ошибки:

    • AUTHENTICATION_ERROR — Ошибка авторизации. Повторно получите API-ключ.

    Список кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.

    Enum: AUTHENTICATION_ERROR

    reason

    Type: string

    Example: Authorization header is missing
    Example
    {
  "reasonCode": "AUTHENTICATION_ERROR",
  "reason": "Authorization header is missing"
}

UnauthorizedErrorReasonCode

Код ошибки:

  • AUTHENTICATION_ERROR — Ошибка авторизации. Повторно получите API-ключ.

Список кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.

Type: string

Const: AUTHENTICATION_ERROR

Example: AUTHENTICATION_ERROR

429 Too Many Requests

Слишком много запросов, повторите запрос позже.

Если ошибка сохраняется при разумном использовании API, обратитесь в поддержку.

500 Internal Server Error

Внутренняя ошибка сервера. Тело ответа может отсутствовать или иметь произвольный формат.

При получении статуса 5XX, повторите запрос.

No longer supported, please use an alternative and newer version.

Предыдущая
Создать заказ со статическим QR-кодом
Следующая
Получить информацию о заказе