Корзина — как подключить и использовать сервис

Что нужно сделать перед интеграцией

Что нужно сделать перед тем, как привлечь разработчиков для интеграции с Корзиной?

Чтобы интегрировать Корзину, сначала подключите интернет-эквайринг Т‑Кассы.

Как подключить интернет-эквайринг — пошаговая инструкция
  1. Подайте заявку на странице Т‑Кассы.
  2. Заполните анкету о компании или ИП в личном кабинете Т‑Бизнеса и отправьте ее на проверку.

    Как заполнить анкету для компании

    Как заполнить анкету для ИП

  3. Мы проверим заявку и пришлем уведомление на эл. почту. Если нам не хватит информации о вашем бизнесе, попросим прислать дополнительные документы. Где можно увидеть статус проверки компании

Если у вас уже подключен интернет-эквайринг, сразу следуйте инструкции:

  1. Перейдите в созданный магазин → «Терминалы». Вы увидите два терминала — тестовый и рабочий, у тестового будет статус «Протестируйте платежи», у рабочего — «Выключен». Игнорируйте статус тестового терминала — сразу перейдите к настройке рабочего.
  2. Нажмите «Настроить» на плашке рабочего терминала и в поле «Подключение» выберите «Мобильное приложение» → «Сохранить».
  3. Выпустите токен в личном кабинете Т‑Бизнеса — для этого перейдите в «Счета и платежи» → «Интеграции» → «Выпуск токена».

    При выпуске токена предоставьте «Корзина. Работа с заказом» доступ через API

    Как выпустить токен — пошаговая инструкция

  4. Выпустите сертификат Mutual TLS в личном кабинете Т‑Бизнеса — для этого перейдите в «Счета и платежи» → «Интеграции» → «Выпуск сертификата (Beta)».

    Выпустить сертификат Mutual TLS может только директор. Для выпуска сертификата понадобится КЭП. Выпустить КЭП через Т-Банк

    Инструкция по выпуску сертификата Mutual TLS

    Как выпустить сертификат Mutual TLS — видеоинструкция

    После того как у вас сделают первую покупку на сайте, токен и сертификат свяжутся.

    Сертификат привязан к IP‑адресу сайта, с которого будут отправляться запросы в Корзину. Если сайт переедет и у него изменится адрес сервера, перевыпустите сертификат и токен — следуйте шагам 4 и 5 этой инструкции.

  5. Напишите нашему специалисту по интеграции на почту checkout_integation@tinkoff.ru и отправьте ему такую информацию о своем магазине:

    • URL‑адрес для получения нотификаций по заказу;
    • URL‑адрес главной страницы вашего магазина, куда должна вести кнопка возврата в магазин;
    • логотип — будет отображаться на форме оформления заказа;
    • контактное лицо — укажите того, с кем будет общаться наш менеджер по интеграции в ходе подключения Корзины;
    • тип магазина — без доставки, с доставкой со сбором и передачей адреса, с доставкой и интеграцией со службами доставки.

    Специалист по интеграции отправит вам универсальный идентификатор магазина — shop ID. Он будет нужен вашим разработчикам, чтобы встроить кнопку Корзины на сайт.

  6. Если у вас магазин, который пользуется услугами служб доставки, зарегистрируйтесь в сервисе-агрегаторе служб доставки Metaship и получите в личном кабинете Metaship идентификатор вашего виртуального магазина и склада. Как это сделать

Готово! Вы настроили все необходимое для интеграции Корзины на ваш сайт. Ознакомьте ваших разработчиков с инструкциями ниже:

Как настроить передачу данных заказа через метод POST

Как поставить кнопку Корзины на сайт магазина

Как получить дополнительные данные о заказе или покупателе

После того как интегрировали Корзину на сайт, подключите облачную онлайн-кассу или сервис «Чеки от Т‑Кассы». Это нужно делать обязательно, чтобы отправлять чеки в налоговую и покупателям: так налоговая будет узнавать о доходах бизнеса и понимать, какой налог с вас удержать. Есть закон, который запрещает торговать без онлайн-кассы всем, кроме ИП на НПД — еще их называют ИП‑самозанятыми. Закон № 54-ФЗ «О применении контрольно-кассовой техники»

Какой из двух сервисов выбрать:

При подключении следуйте этой инструкции.

Перед подключением нужно пройти тесты № 7 и 8 — так вы проверите передачу данных чека. Для этого нам надо переключить вас с рабочего терминала на тестовый — напишите на эл. почту checkout_integation@tinkoff.ru, наш специалист переключит терминал. После интеграции облачной онлайн-кассы или Чеков с магазином мы сами переключим терминал на рабочий, повторно писать специалисту не нужно.

Как настроить интеграцию

Как настроить интеграцию Корзины со службами доставки?

Чтобы Корзина передавала данные о заказах в службы доставки и получала от них трек‑номер доставки, зарегистрируйтесь в агрегаторе служб доставки Metaship, создайте в личном кабинете Metaship виртуальный магазин и подключите службы доставки, с которыми работаете. Пошаговая инструкция

В разделе «Настройки» личного кабинета Metaship в подразделе «Мои магазины» появится идентификатор вашего магазина, а в подразделе «Мои склады» — идентификатор вашего виртуального склада.

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

Передайте их вашим разработчикам — они добавят параметры в метод POST api/v1/checkout/order.

Чтобы настроить для покупателей возможность самовывоза из пунктов выдачи заказов и постаматов, нужно создать виджет в личном кабинете Metaship. Следуйте инструкции:

  1. Зайдите в «Настройки» → «Виджеты» → «Создать виджет».
  2. В выпадающем списке выберите ваш магазин с Корзиной и нажмите «Создать виджет».
  3. Виджет сразу появится в личном кабинете Metaship. В плашке будет значение токена — скопируйте его и передайте нашему специалисту по интеграции на эл. почту checkout_integation@tinkoff.ru.
    Нажмите на иконку копирования рядом с токеном, чтобы скопировать его

В течение рабочего дня специалист настроит этот тип доставки на сайте, где вы подключили Корзину, и ваши покупатели смогут оформлять заказы с самовывозом из пунктов выдачи и постаматов.

Как настроить передачу данных заказа через метод POST api/v1/checkout/order?

При нажатии на кнопку Корзины должен вызываться метод вашего API, который в свою очередь вызывает метод API Корзины. Для этого реализуйте вызов метода POST api/v1/checkout/order. Инструкция для разработчиков

Для магазинов с доставкой нужно включить в метод POST api/v1/checkout/order дополнительные параметры — набор параметров будет зависеть от того, своя у вашего магазина доставка или он работает с сервисами доставки.

Что нужно передать в методе POST api/v1/checkout/order:

    Обязательные параметры для любых магазинов — с доставкой и без
    shopIdУникальный идентификатор магазина, который персональный менеджер прислал директору, см. п. 6 инструкции «Как встроить Корзину в мой магазин?»
    itemsAmountnumberСумма заказа в копейках без учета доставки
    orderIdИдентификатор заказа в системе магазина
    taxation

    Тип налогообложения:

    • osn — ОСН;
    • usn_income — УСН «Доходы»;
    • usn_income_outcome — УСН «Доходы минус расходы»;
    • patent — патент;
    • envd — ЕНВД;
    • esn — ЕСХН;
    • self — ИП на НПД
    shopId
    Уникальный идентификатор магазина, который персональный менеджер прислал директору, см. п. 6 инструкции «Как встроить Корзину в мой магазин?»
    itemsAmountnumber
    Сумма заказа в копейках без учета доставки
    orderId
    Идентификатор заказа в системе магазина
    taxation

    Тип налогообложения:

    • osn — ОСН;
    • usn_income — УСН «Доходы»;
    • usn_income_outcome — УСН «Доходы минус расходы»;
    • patent — патент;
    • envd — ЕНВД;
    • esn — ЕСХН;
    • self — ИП на НПД
    Дополнительные параметры для магазинов с собственной доставкой
    deliveryCondition

    Условия доставки.

    price — стоимость доставки,

    tax — ставка НДС:

    • none — без НДС;
    • vat0 — НДС по ставке 0%;
    • vat10 — НДС чека по ставке 10%;
    • vat20 — НДС чека по ставке 20%;
    • vat110 — НДС чека по расчетной ставке 10/110;
    • vat120 — НДС чека по расчетной ставке 20/120
    deliveryCondition

    Условия доставки.

    price — стоимость доставки,

    tax — ставка НДС:

    • none — без НДС;
    • vat0 — НДС по ставке 0%;
    • vat10 — НДС чека по ставке 10%;
    • vat20 — НДС чека по ставке 20%;
    • vat110 — НДС чека по расчетной ставке 10/110;
    • vat120 — НДС чека по расчетной ставке 20/120
    Обязательные параметры для магазинов, которые пользуются службами доставки
    metashipShopIdID магазина Metaship — можно узнать в личном кабинете Metaship. Как это сделать
    metashipWarehouseIdID склада Metaship — можно узнать в личном кабинете Metaship. Как это сделать
    orderItemsИнформация о товарных позициях
    types

    Тип доставки:

    Courier — курьерская доставка;

    PostOffice — почтовое отправление;

    DeliveryPoint — самовывоз из пункта выдачи заказов или постамата

    weightВес, кг
    heightВысота, см
    widthШирина, см
    lengthДлина, см
    declaredValueОбъявленная стоимость, коп.
    metashipShopId
    ID магазина Metaship — можно узнать в личном кабинете Metaship. Как это сделать
    metashipWarehouseId
    ID склада Metaship — можно узнать в личном кабинете Metaship. Как это сделать
    orderItems
    Информация о товарных позициях
    types

    Тип доставки:

    Courier — курьерская доставка;

    PostOffice — почтовое отправление;

    DeliveryPoint — самовывоз из пункта выдачи заказов или постамата

    weight
    Вес, кг
    height
    Высота, см
    width
    Ширина, см
    length
    Длина, см
    declaredValue
    Объявленная стоимость, коп.

Метод POST возвращает ссылку на заказ в сервис «Корзина». Кнопка «Купить быстро» Корзины перенаправляет покупателя по этой ссылке для дальнейшего оформления заказа. Как поставить кнопку на сайт магазина

Оформление заказа в Корзине

Как поставить кнопку Корзины на сайт магазина?

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

Так будет выглядеть кнопка Корзины рядом с кнопкой оформления заказа

В обоих случаях сгенерируйте скрипт кнопки Корзины с помощью виджета ниже.

В объекте createOrder вместо выделенного желтым маркером кода встройте метод POST api/v1/checkout/order. Как настроить метод POST

В параметре document.querySelector вместо выделенного желтым маркером кода поставьте селектор HTML‑элемента, на месте которого должна появиться кнопка.

Как подключить прием оплаты через СБП?

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

  1. Выберите свой магазин → «Способы оплаты» → «СБП» → «Своя платежная форма» → «Включить».
  2. Напишите на эл. почту checkout_integation@tinkoff.ru, что хотите добавить на форму Корзины кнопку оплаты через СБП, — наш специалист завершит настройку в течение одного рабочего дня.

Как работать с Корзиной

Какие данные отдаст магазину Корзина после оформления заказа?

После оформления заказа Корзина отправит такие данные на указанный при заведении магазина URL‑адрес для нотификаций:

checkoutOrderIdНомер заказа в Корзине
orderIdНомер заказа в системе мерчанта
timestampДата создания заказа
statusСтатус заказа. Какие есть статусы и что они означают
messageСообщение-расшифровка статуса

payment": {

"amount": 2 000,

"paymentId"

Если платеж совершен — сумма заказа и ID платежа

"delivery": {

"deliveryId": "167b8034-99b3-4851-bfbd-34eab62e7dc3" "trackingNumber": "119037732223"

Если создан заказ на доставку — id доставки в системе Metaship

Если заказ уже передан в службу доставки — трек‑номер заказа

checkoutOrderId
Номер заказа в Корзине
orderId
Номер заказа в системе мерчанта
timestamp
Дата создания заказа
message
Сообщение-расшифровка статуса

payment": {

"amount": 2 000,

"paymentId"

Если платеж совершен — сумма заказа и ID платежа

"delivery": {

"deliveryId": "167b8034-99b3-4851-bfbd-34eab62e7dc3" "trackingNumber": "119037732223"

Если создан заказ на доставку — id доставки в системе Metaship

Если заказ уже передан в службу доставки — трек‑номер заказа

Схема вебхука и примеры статусов у заказов

Какие есть статусы платежа и доставки? Что они означают?

Вот какие статусы заказа может отправить магазину сервис после того, как покупатель воспользуется кнопкой Корзины на сайте.

NEW_ORDER — покупатель нажал на кнопку Корзины.

ORDER_PROCESSING — покупатель заполнил все поля и начал оформление заказа — нажал кнопку «Оплатить».

PAYMENT_AWAITING — оплата ожидает подтверждения. Увидите этот статус, если при подключении интернет-эквайринга включили холдирование платежа. Если не включали холдирование, статус быстро сменится.

Что такое холдирование

Как подключить холдирование

PAYMENT_SUCCESS — покупатель оплатил заказ, оплата прошла.

PAYMENT_FAILURE — не удалось списать деньги за заказ. Этот статус может возникнуть, если покупатель неправильно ввел данные карты или на его счете не хватает денег.

Так выглядит процесс оплаты, если не подключали доставку от Корзины. Если подключили доставку, смотрите статусы и схему ниже

DELIVERY_EXT_PROCESSING — в Metaship создана заявка на доставку. Заявке присвоен номер (deliveryID). Статус появляется, только если магазин интегрирован с Metaship.

DELIVERY_EXT_PROCESSING_NOT_STARTED — заявка на доставку в Metaship не создалась, сервис вернул ошибку. Что делать, если у заказа этот статус

DELIVERY_EXT_PROCESSING_SUCCESS — Metaship создал доставку в службе доставки, у доставки появился трек‑номер. Можно отправлять заказ на склад службы доставки. Статус появляется, только если магазин интегрирован с Metaship.

DELIVERY_EXT_PROCESSING_FAILURE — в процессе обработки заявки на доставку в Metaship возникли ошибки. Перейдите в личный кабинет Metaship, чтобы исправить ошибки, или пересоздайте заказ вручную. Может понадобиться дополнительная информация от покупателя. Статус появляется, только если магазин интегрирован с Metaship. Что делать, если у заказа этот статус

Так выглядит процесс заведения заказа в доставке, если вы подключили ее в Корзине. Эти статусы появляются после успешной оплаты заказа — статуса PAYMENT_SUCCESS

Как обрабатывается нотификация о статусе заказа?

Обработчик нотификаций должен возвращать ответ 200 OK с пустым телом, когда статус платежа успешно меняется.

Если будет возвращен любой ответ, кроме 200 OK, нотификация повторится через случайный промежуток времени. После определенного числа неудачных попыток ответ перестанет возвращаться.

Пример, как это работает:

  1. Корзина посылает нотификацию о статусе ORDER_PROCESSING. Какие есть статусы и что они означают
  2. В обработчике нотификаций на стороне магазина произошла ошибка, и он вернул 500 Internal Server Error, а не 200 OK.
  3. Через случайное время снова отправляется нотификация о статусе ORDER_PROCESSING.
  4. Обработчик возвращает ответ 200 OK.
  5. Отправка нотификации прекращается. Она успешно доставлена.

Как найти заказ в личном кабинете Metaship?

Перейдите в личный кабинет Metaship и по идентификатору deliveryID найдите нужный заказ.

Или просто скопируйте идентификатор deliveryID в URL‑адрес заказа. URL‑адрес заказа в Metaship всегда имеет такой вид: https://cabinet.metaship.ru/orders/deliveryID

В интерфейсе личного кабинета Metaship идентификатор deliveryID называется CuID Metaship

У заказа статус DELIVERY_EXT_PROCESSING_FAILURE. Что делать?

Перейдите в личный кабинет Metaship → «Заказы» → «Ошибки». Вы увидите таблицу ошибок в ваших заказах. В таблице будет описание каждой ошибки.

Ошибка «Отправление нельзя доставить, так как его нет в общем списке мест вручения» означает, что служба доставки не доставляет по указанному адресу, а ошибка «Расчетный вес заказа выходит за рамки весового ограничения» — что вес заказа больше максимального по условиям службы доставки.

Нажмите на значок карандаша в строке ошибки, чтобы отредактировать заказ. В некоторых случаях для этого нужно будет связаться с покупателем и уточнить информацию.

У заказа статус DELIVERY_EXT_PROCESSING_NOT_STARTED. Что делать?

Это значит, что заказ на доставку не попал в систему Metaship. В таком случае нужно вручную создать заказ на доставку в личном кабинете вашей службы доставки или в личном кабинете Metaship. Данные по заказу получите, если вызовете метод GET api/v2/checkout/order/:shopId/by/:orderId.

Как получить дополнительные данные о заказе или покупателе?

Для этого нужно вызвать метод GET api/v2/checkout/order/:shopId/by/:orderId. Инструкция для разработчика

Вот какие дополнительные данные можно получить с помощью метода GET api/v2/checkout/order/:shopId/by/:orderId:

    Statuses – подробный статус заказа
    NEW_ORDERЗаказ создан
    ORDER_PROCESSING

    Покупатель начал оформлять заказ — заполнил персональные данные и нажал на кнопку заказа.

    Начиная с этого статуса можете получать данные о покупателе, потому что он принял оферту. Для этого надо вызвать метод GET

    PAYMENT_AWAITINGОжидает подтверждения оплаты
    PAYMENT_SUCCESS Успешная оплата
    PAYMENT_FAILUREНеуспешная оплата
    DELIVERY_EXT_PROCESSINGДоставка создана в Metaship
    DELIVERY_EXT_PROCESSING_NOT_STARTEDДоставка не создана в Metaship
    DELIVERY_EXT_PROCESSING_SUCCESSДоставка создана в службе доставки. Получен трек‑номер
    DELIVERY_EXT_PROCESSING_FAILUREЗаказ обработан в системе Metaship. В процессе обработки получены ошибки
    timestampДата и время статуса
    NEW_ORDER
    Заказ создан
    ORDER_PROCESSING

    Покупатель начал оформлять заказ — заполнил персональные данные и нажал на кнопку заказа.

    Начиная с этого статуса можете получать данные о покупателе, потому что он принял оферту. Для этого надо вызвать метод GET

    PAYMENT_AWAITING
    Ожидает подтверждения оплаты
    PAYMENT_SUCCESS
    Успешная оплата
    PAYMENT_FAILURE
    Неуспешная оплата
    DELIVERY_EXT_PROCESSING
    Доставка создана в Metaship
    DELIVERY_EXT_PROCESSING_NOT_STARTED
    Доставка не создана в Metaship
    DELIVERY_EXT_PROCESSING_SUCCESS
    Доставка создана в службе доставки. Получен трек‑номер
    DELIVERY_EXT_PROCESSING_FAILURE
    Заказ обработан в системе Metaship. В процессе обработки получены ошибки
    timestamp
    Дата и время статуса
    Recipient – информация о получателе заказа
    firstNameИмя
    lastNameФамилия
    phoneТелефон
    emailЭл.почта — передается в кассовый сервис, если подключена онлайн-касса. На этот адрес покупатель получит квитанцию
    firstName
    Имя
    lastName
    Фамилия
    phone
    Телефон
    email
    Эл.почта — передается в кассовый сервис, если подключена онлайн-касса. На этот адрес покупатель получит квитанцию
    User — информация о покупателе

    Обязательно отдаем номер телефона — остальное в зависимости от того, вводил ли покупатель когда‑либо такие данные.

    firstNameИмя
    lastNameФамилия
    phoneТелефон (который был введен на авторизации)
    emailПочта
    firstName
    Имя
    lastName
    Фамилия
    phone
    Телефон (который был введен на авторизации)
    email
    Почта
    Информация о доставке, если магазин интегрирован с Metaship
    addressАдрес доставки
    flatКвартира
    flatCodeКод домофона
    floorЭтаж
    entranceПодъезд
    deliveryIdКод заявки в системе доставки
    trackingNumberТрек‑номер от службы доставки
    deliveryType

    Выбранный тип доставки, в поле будет одно из этих значений:

    • Courier — курьерская доставка;
    • PostOffice — почтовое отправление;
    • DeliveryPoint — пункт выдачи заказов
    deliveryService

    Код выбранной службы доставки, в поле будет одно из этих значений:

    • RussianPost — Почта России;
    • FivePost — 5Post;
    • Boxberry — Boxberry;
    • cdek — СДЭК;
    • Dpd — DPD logistic;
    • другое значение, если покупатель выбрал другую службу доставки
    errorMessageСообщение об ошибке от службы доставки
    address
    Адрес доставки
    flat
    Квартира
    flatCode
    Код домофона
    floor
    Этаж
    entrance
    Подъезд
    deliveryId
    Код заявки в системе доставки
    trackingNumber
    Трек‑номер от службы доставки
    deliveryType

    Выбранный тип доставки, в поле будет одно из этих значений:

    • Courier — курьерская доставка;
    • PostOffice — почтовое отправление;
    • DeliveryPoint — пункт выдачи заказов
    deliveryService

    Код выбранной службы доставки, в поле будет одно из этих значений:

    • RussianPost — Почта России;
    • FivePost — 5Post;
    • Boxberry — Boxberry;
    • cdek — СДЭК;
    • Dpd — DPD logistic;
    • другое значение, если покупатель выбрал другую службу доставки
    errorMessage
    Сообщение об ошибке от службы доставки