Создать заказ с динамическим 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": "id-1",
        "quantity": {
          "count": 1
        },
        "title": "Шариковая ручка",
        "total": "55.00",
        "description": "Шариковая ручка синяя",
        "unitPrice": "5.50"
      }
    ],
    "total": {
      "amount": "55.00"
    }
  },
  "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": "Оплата по заказу 01963e94-7457-74da-8739-fa7ea310a255",
  "metadata": "example",
  "ttl": 600
}
All of 2 types
  • Type: CreateOrder

    Example
    {
      "cart": {
        "items": [
          {
            "productId": "id-1",
            "quantity": {
              "count": 1
            },
            "title": "Шариковая ручка",
            "total": "55.00",
            "description": "Шариковая ручка синяя",
            "unitPrice": "5.50"
          }
        ],
        "total": {
          "amount": "55.00"
        }
      },
      "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": "Оплата по заказу 01963e94-7457-74da-8739-fa7ea310a255",
      "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: 10

Example
{
  "count": "10"
}

CartItem

Name

Description

productId

Type: string

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

Max length: 2048

Example: id-1

quantity

Type: ItemQuantity

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

Example
{
  "count": "10"
}

title

Type: string

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

Max length: 2048

Example: Шариковая ручка

total

Type: string<double>

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

Example: 55.00

description

Type: string

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

Max length: 2048

Example: Шариковая ручка синяя

unitPrice

Type: string<double>

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

Примеры:

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

Example: 5.50

Example
{
  "productId": "id-1",
  "quantity": {
    "count": 1
  },
  "title": "Шариковая ручка",
  "total": "55.00",
  "description": "Шариковая ручка синяя",
  "unitPrice": "5.50"
}

CartTotal

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

Name

Description

amount

Type: string<double>

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

Example: 55.00

Example
{
  "amount": "55.00"
}

Cart

Корзина.

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

Важно

В соответствии с Федеральным законом № 283‑ФЗ «О деятельности по предоставлению сервиса рассрочки» при использовании сервиса Сплит договор о предоставлении сервиса рассрочки с пользователем обязательно должен содержать сведения об объекте рассрочки — товарах, работах, услугах или результатах интеллектуальной деятельности, оплачиваемых в Сплит.

Поэтому в запросе обязательно передавайте данные всех объектов рассрочки в корзине в параметре cart.items.

Name

Description

items

Type: CartItem[]

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

Min items: 1

Example
[
  {
    "productId": "id-1",
    "quantity": {
      "count": 1
    },
    "title": "Шариковая ручка",
    "total": "55.00",
    "description": "Шариковая ручка синяя",
    "unitPrice": "5.50"
  }
]

total

Type: CartTotal

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

Example
{
  "amount": "55.00"
}
Example
{
  "items": [
    {
      "productId": "id-1",
      "quantity": {
        "count": 1
      },
      "title": "Шариковая ручка",
      "total": "55.00",
      "description": "Шариковая ручка синяя",
      "unitPrice": "5.50"
    }
  ],
  "total": {
    "amount": "55.00"
  }
}

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. Это избавит от проблем с округлением, например, при возврате.

Важно

В соответствии с Федеральным законом № 283‑ФЗ «О деятельности по предоставлению сервиса рассрочки» при использовании сервиса Сплит договор о предоставлении сервиса рассрочки с пользователем обязательно должен содержать сведения об объекте рассрочки — товарах, работах, услугах или результатах интеллектуальной деятельности, оплачиваемых в Сплит.

Поэтому в запросе обязательно передавайте данные всех объектов рассрочки в корзине в параметре cart.items.

Example
{
  "items": [
    {
      "productId": "id-1",
      "quantity": {
        "count": 1
      },
      "title": "Шариковая ручка",
      "total": "55.00",
      "description": "Шариковая ручка синяя",
      "unitPrice": "5.50"
    }
  ],
  "total": {
    "amount": "55.00"
  }
}

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

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

  • Символы латинского алфавита (A–Z и a–z) с десятичными кодами из диапазонов [065-090] и [097-122] в кодировке UTF-8;
  • Символы русского алфавита (А-Я и а-я) с десятичными кодами из диапазона [1040-1103] в кодировке UTF-8;
  • Цифры 0-9 с десятичными кодами из диапазона [048-057] в кодировке UTF-8;
  • Специальные символы с десятичными кодами из диапазонов [032-047], [058- 064], [091-096], [123-126] в кодировке UTF-8;
  • Символ «№» под номером 8470 в кодировке UTF-8

Max length: 140

Example: Оплата по заказу 01963e94-7457-74da-8739-fa7ea310a255

Example
{
  "cart": {
    "items": [
      {
        "productId": "id-1",
        "quantity": {
          "count": 1
        },
        "title": "Шариковая ручка",
        "total": "55.00",
        "description": "Шариковая ручка синяя",
        "unitPrice": "5.50"
      }
    ],
    "total": {
      "amount": "55.00"
    }
  },
  "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": "Оплата по заказу 01963e94-7457-74da-8739-fa7ea310a255",
  "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_IDproductId отсутствует в корзине заказа.
    • ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_IDproductId должен быть уникальным.
    • 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_IDproductId отсутствует в корзине заказа.
  • ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_IDproductId должен быть уникальным.
  • 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, повторите запрос.