Как интегрировать API интернет-эквайринга
API банка включает в себя методы интернет-эквайринга, с помощью которых вы можете:
- Принимать оплаты заказов с помощью платёжных ссылок, в том числе с двухэтапной оплатой
- Возвращать такие платежи
- Принимать оплаты подписок
- Получать данные, нужные для отчётности
Подключение интернет-эквайринга
Сначала подключите интернет-эквайринг — чтобы были доступны методы для работы с платёжными ссылками. Это может сделать пользователь интернет-банка с правом на подпись — обычно руководитель компании или бухгалтер.
Чтобы подключить интернет-эквайринг, перейдите в интернет-банке в «Сервисы» → «Интернет-эквайринг» и следуйте инструкциям на экране для подачи заявки.
Мы рассмотрим заявку в течение 10 минут и свяжемся с вами в чате интернет-банка. Само подключение интернет-эквайринга обычно занимает до 2 рабочих дней.
Также вам нужно выбрать сервис для фискализации оплат и возвратов — отправки информации о них оператору фискальных данных (ОФД). Вы можете подключить решение от наших партнёров или выбрать другой сервис.
Разработка
Знакомство с API
Изучить API-методы, их тела и ответы можно в нашей песочнице. Как с ней работать, смотрите на странице «Песочница».
Для удобства используйте нашу коллекцию запросов для Postman. В ней есть все нужные методы, а настройка окружения займёт пару минут.
Базовый URL для отправки запросов на продакшене: https://enter.tochka.com/uapi.
Авторизация запросов
Сначала выберите способ авторизации запросов, который вы будете использовать:
- По JWT-токену — если интеграцией с Точка Банком будете пользоваться только вы. Например, если у вас интернет-магазин, и его пользователи рассчитываются только с вами. Узнать, как создать и использовать токен, вы можете на странице «Авторизация по JWT-токену».
- По OAuth 2.0 — если пользователи вашей платформы будут рассчитываться друг с другом, и им нужна интеграция вашего сервиса с Точка Банком. Смотрите подробнее на странице «Авторизация по OAuth 2.0».
Если вы подключаете интеграцию для себя, и вам не нужно предоставлять её вашим пользователям, выбирайте авторизацию по JWT. Этот способ проще, быстрее и лучше подходит для таких случаев.
После выбора способа авторизации вы можете приступать к интеграции API-методов в ваше приложение.
Интеграция API-запросов
В таблице ниже вы найдёте методы, которые понадобятся вам для работы с интернет-эквайрингом. Работа с ними подробно описана в документации — переходите по ссылкам, чтобы изучить детали.
| Методы, ссылка на техническую документацию | Назначение методов | Ссылка на описание работы |
|---|---|---|
| Get Customers List | Для выполнения некоторых запросов нужно указать ваш customerCode. Вы можете получить его с помощью этого метода — customerCode будет в ответе в объекте с "customerType": "Business". | Клиенты |
| Get Retailers | Если у вас несколько торговых точек, вам нужно будет указывать идентификатор нужной точки при выполнении всех запросов. Его можно узнать с помощью этого метода — идентификатор будет в поле merchantId в объекте со статусом REG и "isActive": true.Если у вас одна торговая точка, но вы планируете масштабировать бизнес, merchantId лучше сразу передавать в запросах. Так вы сможете избежать доработок кода в будущем. | Получение списка торговых точек |
| Методы для работы с платёжными ссылками | Чтобы принимать оплату: вы создаёте ссылку, покупатель переходит по ней и оплачивает покупку нужным способом. Обратите внимание на фискализацию оплат — она необходима по закону. | Платёжные ссылки |
| Методы для работы с подписками | Для автоматических оплат: когда после первой покупки деньги автоматически списываются с карты покупателя. Оплатить подписку можно только картой. | Подписки (рекуррентные платежи) |
| Refund Payment Operation | Метод нужен, чтобы вернуть платёж, поступивший через платёжную ссылку. Статус платежа должен быть APPROVED. Платежи, поступившие через подписки, можно вернуть только в интернет-банке. | Возврат платежа, поступившего через платёжную ссылку |
| Вебхуки | Чтобы автоматически получать информацию об оплатах в свой сервис: статус платежа, идентификатор торговой точки, сумму платежа и прочее. Вебхуки приходят в формате JWT — их нужно расшифровать на своей стороне. Используйте событие acquiringInternetPayment, чтобы получать данные об оплатах по платёжным ссылкам.Информацию о возвратах вы можете получить из ответа метода Refund Payment Operation. | Вебхуки |
| Get Payment Operation Info | Получить информацию о транзакции, если вы не используете вебхуки или оплата не прошла. В теле запроса укажите идентификатор платёжной ссылки в поле operationId. | Получение списка операций по платёжным ссылкам |
| Get Payment Registry | Получить реестр платежей по платёжным ссылкам. Удобно, когда нужно посчитать сумму всех платежей и комиссию за эквайринг за день. В реестре отображаются оплаты, принятые через платёжные ссылки. Списания в рамках подписок в реестр не попадают. | Получение реестра платежей по платёжным ссылкам |
Обычно не нужно реализовывать все методы из каждого раздела и настраивать все вебхуки, особенно чтобы начать использовать интернет-эквайринг. Поэтому рекомендуем опираться на функционал, который необходим в вашем случае.
Тестирование интеграции
После интеграции методов проверьте их работу на продакшене. Для этого проведите оплату:
- На 1 рубль — для платёжных ссылок
- На 2 рубля — для оплаты подписки
Затем отмените проведённую оплату, проверьте другие методы и получение вебхуков, если вы их создавали.
Зачисление денег на ваш расчётный счёт
Если у вас есть открытый расчётный счёт в Точка Банке, все платежи, полученные через интернет-эквайринг, зачисляются на него.
| Тип платежа | Срок зачисления | Комментарий |
|---|---|---|
| Банковская карта | Следующий календарный день | Зачисляется общей суммой за вычетом комиссии |
| Система быстрых платежей (СБП) | Моментально | Каждая операция зачисляется отдельно, комиссия списывается отдельным платежом сразу после зачисления |
| Т-Pay | На следующий рабочий день | Зачисляется общей суммой за вычетом комиссии |
| Долями | 1–2 рабочих дня | Зачисляется общей суммой за вычетом комиссии |