Интеграция Тинькофф банк Эквайринг на сайт для приема платежей

Роман Чернышов    CMS, PHP     интеграция api, тинькофф, эквайринг Комментариев 0 Дата 18 Дек

Прием платежей на сайте, на сегодняшний день это неотъемлемая часть, без преувеличения, любого бизнеса, и услуга интернет-эквайринга от банка Тинькофф, на мой взгляд одна из самых востребованных, поэтому вопрос о технической интеграции сайта с данным сервисом весьма актуален. В этой статья я хочу сделать небольшой обзор вариантов подключения интернет-эквайринга на свой сайт, а именно их техническую часть, в данный перечень входят: использование готового решения, платежный модуль для CMS; платежный виджет, HTML код формы; прямая работа с API; использование PHP класса для быстрого подключения на стороне сервера. Также рассмотрим настройки рабочего терминала для взаимодействия с сайтом.

Материал представленный в данной статье есть в разных источниках, как на самом сайте Тинькофф банка, на Githab так и на Habr, но в некой мере разрознен, поэтому я и решил написать данный текст, чтобы объять все воедино. Также по некоторым решениям я даю комментарии, для каких случаев они больше всего подойдут — так как ряд моих клиентов, путались именно в этом, например ломали голову как настроить плагин для WordPress особым образом, когда решение было в прямой работе с API.

Содержание

• Платежный модуль для CMS
• Платежный виджет на HTML
• Прямая работа с API
• PHP класс — интеграция на стороне сервера
• Настройка рабочего терминала на сайте Тинькофф
• Заключение

Платежный модуль для CMS

На сегодняшний деть в арсенале готовых решения присутствует поддержка около сорока CMS, среди которых: 1С-Битрикс, AmoCRM, CS-Cart, JoomShoping, MODX, OpenCart, Prestashop, Tilda, VirtueMart, WordPress eCommerce и многие другие. Для того, чтобы воспользоваться одним из них, достаточно просто скачать архив со скриптом и установить готовый плагин на сайт. Кстати, в некоторых CMS данный модуль уже включен в поставку по умолчанию, также он присутствует в ряде конструкторов сайтов, типа Tilda, где его достаточно лишь активировать.

Недостатком готовых модулей является то, что они есть не для всех CMS, а также, что их функционал в основном всегда заточен под схему: клиент производит оплату, статус заказа на сайте переходит в «оплачен». А, что если необходимо реализовать другую логику работы? Например, клиент производит оплату, и на его виртуальный баланс на сайте происходит зачисление, далее он может производить различные покупки на сайте, осуществлять переводы другим пользователям внутри сайта и т.д. Допустим речь об уникальном проекте. То такой возможности в готовых модулях уже не предусмотрено. Придется менять код, что не всегда эффективно, а иногда и невозможно.

Пример установки модуля для WordPress eCommerce

Для установки и настройки модуля необходимо:

1. Скачайте zip-архив с модулем оплаты с сайте Тинькофф

2. Зайти в админпанель WordPress и перейти в раздел «Плагины» -> «Добавить новый»

Рисунок 1. Добавление нового плагина

3. Нажать кнопку «Загрузить плагин» -> «Выберите файл»

4. Выбрать скачанный zip-архив, и загрузите его на сайт

Рисунок 2. Выбор архива

5. Дождаться окончания установки модуля

6. После установки нажать кнопку АКТИВИРОВАТЬ ПЛАГИН

Рисунок 3. Активация плагина

7. Перейдите в раздел «Настройки» -> «Магазин» -> «Платежи»

Рисунок 4. Раздел «Платежи»

8. В списке способов оплат выбрать Tinkoff и нажать «Настройки»

Рисунок 5. Выбор модуля

9. Заполнить поля «Терминал», «Секретный ключ» параметрами для магазина из Личного кабинета
https://oplata.tinkoff.ru. В настройках модуля указать Терминал и Пароль магазина.

Для получения данных в личном кабинете нужно:
a) Перейти в раздел «Магазины».
b) Выбрать магазин.
c) Выбрать пункт «Терминалы» в боковом меню.

Рисунок 6. Данные терминала

Рисунок 7. Настройка модуля

10. Выбрать язык платежной формы.

Далее переходим к настройке, о чем подробнее уже можно почитать в документации к данному модулю. В частности настройка интеграции с онлайн-кассами, настройка в Личном Кабинете и т.д.

Платежный виджет на HTML

Не менее удобное решение, установка платежного виджета на сайт с помощью вставки HTML кода на страницу в нужное место, например под описанием товара. Сам же виджет может выглядеть по разному, например как просто кнопка «Купить», «Оплатить» или же в виде формы, где пользователь может заполнить поля: сумма заказа, номер заказа, описание, емаил и свой телефон. В зависимости от ваших целей и задач, виджет можно настроить по разному, например скрыть все поля оставив только кнопку «Пополнить баланс», при этом автоматически в скрытые поля подставлять параметры платежа и контакты пользователя.

К недостатком такого решения можно отнести лишь то, что параметры платежа можно изменять на стороне пользователя, даже в случае если поля будут скрыты, пользователь может изменить их значение в HTML редакторе страницы, например подставив в поле «сумма» свое значение. Поэтому требуется более грамотная настройка интернет-магазина, проверка входящих сумм платежей и их назначение, в том числе вручную менеджером.

Решение подойдет для небольшого количества транзакций в определенный период времени, там где с каждым клиентом есть дополнительное взаимодействие менеджера. Для более сложных систем, или где количество транзакций десятки, а то и сотни в день, данное решение не предпочтительно.

Установка виджета

Вставьте код на ваш сайт в место, где должна располагаться кнопка «Оплатить»:

<style>.tinkoffPayRow{display:block;margin:1%;width:160px;}</style>
<script src="https://securepay.tinkoff.ru/html/payForm/js/tinkoff_v2.js"></script>
<form name="TinkoffPayForm" onsubmit="pay(this); return false;">
  <input class="tinkoffPayRow" type="hidden" name="terminalkey" value="TinkoffBankTest">
  <input class="tinkoffPayRow" type="hidden" name="frame" value="true">
  <input class="tinkoffPayRow" type="hidden" name="language" value="ru">
    <input class="tinkoffPayRow" type="text" placeholder="Сумма заказа" name="amount" required>
    <input class="tinkoffPayRow" type="text" placeholder="Номер заказа" name="order">
    <input class="tinkoffPayRow" type="text" placeholder="Описание заказа" name="description">
    <input class="tinkoffPayRow" type="text" placeholder="ФИО плательщика" name="name">
    <input class="tinkoffPayRow" type="text" placeholder="E-mail" name="email">
    <input class="tinkoffPayRow" type="text" placeholder="Контактный телефон" name="phone">
    <input class="tinkoffPayRow" type="submit" value="Оплатить">
</form>

Настройка

Получите идентификатор магазина в разделе «Магазины» личного кабинета. Вставьте его в значение атрибута value поля terminalkey:

<input class="tinkoffPayRow" type="hidden" name="terminalkey" value="Идентификатор вашего магазина">

Для открытия платежной формы в новом окне измените значение атрибута value поля frame на false:

<input class="tinkoffPayRow" type="hidden" name="frame" value="false">

Для смены языка платежной формы на английский измените значение атрибута value поля language на en:

<input class="tinkoffPayRow" type="hidden" name="language" value="en">

Чтобы скрыть поле платежной формы, добавьте атрибут type со значением hidden:

<input class="tinkoffPayRow" type="hidden" placeholder="ФИО плательщика" name="name">

Чтобы сделать поле платежной формы обязательным для заполнения, добавьте атрибут required:

<input class="tinkoffPayRow" type="text" placeholder="E-mail" name="email" required>

Прямая работа с API

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

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

Ниже представлена схема проведения платежей:

В качестве примера работы с API, приведу список доступных методов, для приема простых платежей на сайте:

• Init — Создает платеж
• FinishAuthorize — Подтверждает платеж передачей реквизитов и списанием/блокировкой средств
• Confirm — Подтверждает платеж и списывает ранее заблокированные средства
• Cancel — Отменяет платеж
• GetState — Возвращает текущий статус платежа
• Resend — Отправляет все неотправленные нотификации
• Submit3DSAuthorization — Осуществляет проверку результатов прохождения 3-D Secure
• SendClosingReceipt — Отправляет закрывающий чек в кассу

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

PHP класс — интеграция на стороне сервера

Речь пойдет о простом PHP классе, который обладает несколькими методами, но при этом позволяет очень быстро интегрировать функцию приема платежей на сайте. Работает данный класс, через взаимодействие с API(о котором шла речь выше) и задействует всего несколько его методов, по средствам отправки запросов POST CURL с заголовком «Content-Type: Json». Также он используется свою базу данных, для хранения информации о платежах. Но, это не усложняет работу с ним, при желании можно его переписать с учетом взаимодействия с базой данных CMS, например.

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

Шаг1. Создаете файл tinkoff.params.php, желательно подключить базу через PDO.

<?php
use NeatekTinkoff\NeatekTinkoff\NeatekTinkoff;
require_once 'tinkoff.class.php';
$tinkoff = new NeatekTinkoff(
    array(
        array(
            'TerminalKey' => '', // Терминал
            'Password'    => '', // Пароль
        ),
        array(
            // Подключение к БД через PDO
            'db_name' => '',
            'db_host' => '',
            'db_user' => '',
            'db_pass' => '',
        ),
    )
);

Шаг 2. Создаете index.php для перекидывания на платёж, только уберите SetRecurrent() если не нужны рекуррентные платежи.

<?php
require_once 'tinkoff.params.php';
$tinkoff->AddMainInfo(
    array(
        'OrderId'     => 1, // Не будет работать при подключении к БД, будет автоматически ставиться свой номер заказа из базы данных, рекомендуется всегда оставлять значение = 1 при использовании PDO DB
        'Description' => 'Описание заказа до 250 символов', // Описание заказа
        'Language'    => 'ru', // Язык интерфейса Тинькофф
    )
);
$tinkoff->SetRecurrent(); // Указать что рекуррентный платёж, можно не указывать
$tinkoff->AddItem(
    array(
        'Name'     => 'Название товара 128 символов', // Максимум 128 символов
        'Price'    => 100, // В копейках
        "Quantity" => (float) 1.00, // Вес или количество
        "Tax"      => "none", // В чеке НДС
    )
);
$tinkoff->SetOrderEmail('neatek@icloud.com'); // Обязательно указать емайл
//$tinkoff->SetOrderMobile('+79999999999'); // Установить мобильный телефон
$tinkoff->SetTaxation('usn_income'); // Тип налогообложения 
//$tinkoff->DeleteItem(0); // Можно удалить товар по индексу
$tinkoff->Init(); // Инициализация заказа, и запись в БД если прописаны настройки
$tinkoff->doRedirect(); // Переадресация на оплату заказа

Далее пользователь оплачивает заказ, и после чего идёт от банка уведомление на наш скрипт, который ниже об успешном платеже.

Шаг 3. Обработка нотификаций (уведомлений)

<?php
require_once 'tinkoff.params.php';
$tinkoff->getResultResponse(); // Ответ на нотификации

Шаг 4. Рекуррентные платежи, можете указать что угодно здесь.

<?php 
require_once 'tinkoff.params.php';
$recurrents = $tinkoff->getLatestForRecurrent();
if (!empty($recurrents)) {
    foreach ($recurrents as $column => $client) {
        /**
         * Params for Init *
         */
        $params = array(
            // Сумма всех Items.Amount 
             'Amount'      => (string)$client['Amount'],
            // Номер заказа берется из DB
             'OrderId'     => (string)$client['order_id'],
            // из DB
             'Description' => $client['Description'],
        );
        $params['DATA'] = (object) array(
            'Email' => $client['Email'],
        );
        $params['Receipt'] = (object) array(
            // Береться из DB
             'Email'    => $client['Email'],
            // Налогообложение
             'Taxation' => 'usn_income',
            // С предметами в чеке, можно добавить что вам нужно
             'Items'    => array(
                (object) array(
                    'Name'     => 'Описание товара 128 символов',
                    'Price'    => $client['Amount'],
                    "Quantity" => 1.00,
                    // Amount = Price * Quantity
                    "Amount"   => $client['Amount'],
                    "Tax"      => "none",
                ),
            ),
        );
 
        /**
         * Charge - повторый платёж *
         */
        $tinkoff->Charge($tinkoff->Init($params, '[Automatic]'), $client);
    }
}

Настройка рабочего терминала на сайте Тинькофф

После интеграции приема платежей на сайте, необходимо настроить рабочий терминал в личном кабинете Тинькофф Банка. А именно, нас интересует настройка нотификации(уведомлений) при приме оплаты, которые будут отправлены сайту — чтобы тот в свою очередь изменил статус заказа, либо зачислил деньги на виртуальный баланс пользователя и т.д. То есть, сайт таким образом получает информацию о статусе платежей и может дальше взаимодействовать с пользователем.

Переходим к настройке:

1. В личном кабинете выберите рабочий терминал и нажмите «Настроить».
«Интернет-эквайринг» → «Магазины» → выберите нужный магазин → «Терминалы»:

2. Выберите способ подключения, который использовали для настройки и проверки тестового терминала.

3. Настройте терминал. Оставьте настройки по умолчанию или используйте свои. Нажмите «Сохранить»:

4. Укажите в настройках вашего сайта или мобильного приложения ID и пароль рабочего терминала. Они указаны на странице настройки рабочего терминала:

Все готово. Теперь можно принимать платежи.

Заключение

Мне довелось поработать со всеми описанными вариантами интеграции интернет-эквайринга от Тинькофф, каждый из них хорош по своему, выбирать подход стоит исходя из поставленных задач. Например в последнем проекте CMS Совместные покупки, наилучшим решением оказался PHP класс, его удалось достаточно быстро адаптировать под наши нужды и встроить на сайт. Но самым распространенным решением все же является HTML виджет, именно из-за своей простоты установки, в том числе даже на сайты без поддержки PHP(к которым относится множество конструкторов сайтов, лендингов и т.д.).

Если вам нужна помощь в интеграции, обращайтесь, буду рад помочь!