Как интегрировать API интернет-эквайринга
API банка включает в себя методы интернет-эквайринга, с помощью которых вы можете:
- Принимать оплаты заказов с помощью платёжных ссылок, в том числе с двухэтапной оплатой
- Возвращать такие платежи
- Принимать оплаты подписок
- Получать данные, нужные для отчётности
Подключение интернет-эквайринга
Сначала подключите интернет-эквайринг — чтобы были доступны методы для работы с платёжными ссылками. Это может сделать пользователь интернет-банка с правом на подпись — обычно руководитель компании или бухгалтер.
Чтобы подключить интернет-эквайринг, перейдите в интернет-банке в «Сервисы» → «Интернет-эквайринг» и следуйте инструкциям на экране для подачи заявки.
Мы рассмотрим заявку в течение 10 минут и свяжемся с вами в чате интернет-банка. Само подключение интернет-эквайринга обычно занимает до 2 рабочих дней.
Также вам нужно выбрать сервис для фискализации оплат и возвратов — отправки информации о них оператору фискальных данных (ОФД). Вы можете подключить решение от наших партнёров или выбрать другой сервис.
Разработка
Знакомство с API
Изучить API-методы, их тела и ответы можно в нашей песочнице. Как с ней работать, смотрите на странице «Песочница».
Для удобства используйте нашу коллекцию запросов для Postman. В ней есть все нужные методы, а настройка окружения займёт пару минут.
Авторизация запросов
Сначала выберите способ авторизации запросов, который вы будете использовать:
- По JWT-токену — если интеграцией с Точка Банком будете пользоваться только вы. Например, если у вас интернет-магазин, и его пользователи рассчитываются только с вами. Узнать, как создать и использовать токен, вы можете на странице «Авторизация по JWT-токену».
- По OAuth 2.0 — если пользователи вашей платформы будут рассчитываться друг с другом, и им нужна интеграция вашего сервиса с Точка Банком. Смотрите подробнее на странице «Авторизация по OAuth 2.0».
Если вы подключаете интеграцию для себя, и вам не нужно предоставлять её вашим пользователям, выбирайте авторизацию по JWT. Этот способ проще, быстрее и лучше подходит для таких случаев.
После выбора способа авторизации вы можете приступать к интеграции API-методов в ваше приложение.
Интеграция API-запросов
В таблице ниже вы найдёте методы, которые понадобятся вам для работы с интернет-эквайрингом. Работа с ними подробно описана в документации — переходите по ссылкам, чтобы изучить детали.
Базовый URL для отправки запросов на продакшене: https://enter.tochka.com/uapi.
| Методы, ссылка на техническую документацию | Назначение методов | Ссылка на описание работы |
|---|---|---|
| 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 рабочих дня | Зачисляется общей суммой за вычетом комиссии |
Вопросы и ответы
Ошибка с данными "errorCode": "Something going wrong", "message": "Forbidden by consent"
Убедитесь, что используете верный customerCode, токен авторизации и API-метод. Также проверьте, выданы ли нужные разрешения.
Как принимать оплаты только по СБП
Укажите этот способ оплаты при создании платёжной ссылки:
"paymentMode": [
"sbp"
]
Как сделать первую сумму оплаты подписки меньше, чем следующие
Создайте подписку без графика:
- В поле
recurringукажитеtrue - Не передавайте объект
Options
Чтобы списать деньги по такой подписке, используйте метод Charge Subscription. Передайте в нём operationId, полученный при создании подписки, и сумму платежа.
Можно ли получить логи запросов
Нет, логи со своей стороны мы не предоставляем.
Как сохранить данные карты покупателя, чтобы предложить её при следующих оплатах
При создании платёжной ссылки или подписки укажите "saveCard": true.
Если при создании платёжной ссылки указать "saveCard": true, то не получится передать "preAuthorization": true, то есть использовать двухэтапную оплату.
Карта сохранится, если покупатель поставит галочку «Сохранить карту». В таком случае вы получите consumerId и сможете использовать его в запросах для этого покупателя.