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

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

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

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

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

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

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

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

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

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

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

• облачная онлайн-касса — подойдет, если готовы платить раз в месяц за аренду или подключение онлайн-кассы; Какую облачную онлайн-кассу выбрать
• Чеки от Тинькофф Кассы — подойдут, если готовы отдавать комиссию после каждой покупки. Подключить Чеки от Тинькофф Кассы

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

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

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

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

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

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

Передайте их вашим разработчикам — они добавят параметры в метод 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:

Обязательные параметры для любых магазинов — с доставкой и без
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
Обязательные параметры для магазинов, которые пользуются службами доставки
metashipShopId	ID магазина Metaship — можно узнать в личном кабинете Metaship. Как это сделать
metashipWarehouseId	ID склада 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‑элемента, на месте которого должна появиться кнопка.

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

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

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

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

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

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

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

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

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. Что делать, если у заказа этот статус

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

Обработчик нотификаций должен возвращать ответ 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

У заказа статус 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
Сообщение об ошибке от службы доставки