API для переадресации платежей является инструментом, позволяющим организовать прием платежей криптовалют методом пересылки платежа. Данное API является низкоуровневым инструментом, позволяющим интегрировать прием криптовалют (BTC, BCH, ETH, LTC) для различного вида приложений, таких как веб сайты, мобильные и десктопные приложения.
Прием платежей от пользователей представляет собой перечисление платежей в пользу продавца и сопоставление поступившего платежа с номером заказа либо учетной записью пользователя.
Криптовалюты являются децентрализованными системами, в которых только владелец кошелька имеет возможность инициировать платеж. В связи с этой особенностью оплата каждый раз подразумевает ожидание платежа от пользователя, так как автоматическое списание средств невозможно. Идентифицировать платеж по адресу отправителя так же нет возможности, так как адрес отправителя может не принадлежать пользователю в случае оплаты через биржу либо централизованный сервис кошельков.
Для решения задачи идентификации и сопоставления платежей используется метод, когда для каждого ожидаемого платежа генерируется уникальный адрес в соответствующей криптовалюте. В случае платежа, связанного с товарами или услугами, сгенерированный адрес ассоциируется с инвойсом/номером заказа. Для случая пополнения баланса пользователя сгенерированный адрес ассоциируется с учетной записью пользователя.
Образуемое множество сгенерированных адресов мониторится на предмет поступления платежей. Полученные платежи в дальнейшем консолидируются и пересылаются на главный кошелек продавца.
API пересылки платежей представляет собой готовое решение по генерации временных адресов с заданными правилами по пересылке платежей на единый адрес продавца и системой уведомлений о платежах. Пересылка осуществляется по достижению подтверждения платежей в блокчейне. Уведомление о платежах отправляется на сервер продавца и имеет защиту от сбоя. Адреса могут быть использованы неограниченное количество раз, что позволяет ассоциировать сгенерированный адрес с учетной записью пользователя и получать платежи в его пользу.
При пересылке платежа взимается фиксированный сервисный сбор, который включает в себя комиссию майнеров для оплаты транзакции пересылки платежа. Размер сервисного сбора подробно описан в разделе Service fee.
Подробнее о системе уведомления о платежах в разделе Обработчик уведомлений платежа.
Для всех поддерживаемых криптовалют API доступны для Mainnet, Testnet и сети Tor. Для тестнет сетей доступны раздачи тестовых монет, а так же экcплореры.
Mainnet URL: https://api.bitaps.com/{currency}/v1/Для API действуют ограничения запросов по IP адресам. Стандартный лимит 60 запросов в течении 5 секунд для одного IP адреса. Если вам требуется большее число запросов, то вам необходимо приобрести API токен. По вопросам получения API токена обращайтесь support@bitaps.com. В случае превышения лимита в ответ на запрос отдается страница со статусом 429 to many requests. При получении ошибки следует дождаться восстановления временного лимита, в противном случае IP адрес будет заблокирован на 3 минуты. Текущее состояние по лимитам можно посмотреть в заголовках ответа Ratelimit-Remaining и Ratelimit-Reset.
Сервис удреживает фиксированную комиссию с каждого обрабатываемого платежа. Комиссия майнеров оплачиваемая при пересылке платежа включенна в сервисный сбор.
Размеры комиссий:
Currency | Service fee | Min. TX Value |
---|---|---|
Bitcoin | 0.0002 BTC | > 0.00000546 BTC + Service fee |
Bitcoin cash | 0.0004 BCH | > 0.00000546 BCH + Service fee |
Ethereum | 0.006 ETH | > 0.001 ETH + Service fee |
Litecoin | 0.0004 LTC | > 0.00000546 LTC + Service fee |
Созданные адреса для пересылки не имеют ограничений по количеству обрабатываемых платежей, а так же ограничений по времени действия. В блокчейнах c архитектурой UTXO (btc, bch, ltc) в качестве уникального идентификатора платежа считается хеш транзакции и номер выхода в транзакции. Для блокчейнов с архитектурой Acсount based (eth) уникальным идентификатором платежа считается хеш транзакции. При пересылке платежи для одинаковых адресов могут быть консолидированы в одну транзакцию, но уведомления поступят по отдельности для каждого платежа. Транзакцией выплаты является пара хеш транзакции + номер выхода (для ethereum только хеш транзакции). Для каждого сгенерированного адреса предусмотрена возможность запроса текущего состояния и статистики, а так же списка всех транзакций, полученных адресом. Доступ к статистике разделяется на публичный и закрытый. Доступ к закрытой части информации осуществляется с помощью авторизации через заголовок запроса Payment code либо Access-Token домена обработчика уведомлений. По указанному линку для уведомлений о платеже накапливается общая статистика для домена. Доступ к статистике для домена осуществляется через Access-Token.
Для создания платежного адреса необходимо: указать адрес для пересылки платежа, ссылку на обработчик уведомлений о платежах (опционально) и количество подтверждений, необходимых для зачисления платежа и получения уведомлений о подтверждениях (если не указанно будет использовано значение по умолчанию). Информация о поступлении платежа и выплате будет отправляться на указанный обработчик уведомлений. Для Bitcoin Cash и Litecoin в ответе на запрос так же присутствует адрес в legacy формате (устаревший формат адресов). Оба формата адресов могут быть использованы для получения платежей и обрабатываются платформой корректно.
Запрос состояния и статистики платежного адреса. Запрос без авторизации возвращает только публичную информацию, при наличии заголовка Payment-Code или Access-Token доступна полная информация.
Запрос списка транзакций платежного адреса. Запрос без авторизации возвращает только публичную информацию, при наличии заголовка Payment-Code или Access-Token доступна информация полная информация.
Пример обработчика уведомлений платежа с описанием входящих POST параметров. Уведомления о платеже поступают при наступлении следующих событий:
К примеру, если создан платежный адрес с 2 подтверждениями, то он получит следующие уведомления: unconfirmed, pending [1/2], confirmed, payout sent, payout confirmed. Уведомления с событиями payout sent,payout confirmed, могут приходить до наступления события confirmed, в данных уведомлениях поле confirmations следует игнорировать.
Логика обработки уведомлений о платеже должна соответствовать следующей схеме. Каждому платежному адресу соответствует подтвержденный и неподтвержденный баланс. N - количество необходимых подтверждений.
Обработка поступающих уведомлений:
Платежные уведомления имеют логику защиты от сбоя. В качестве подтверждения того, что уведомление получено, сервис ожидает получить ответ в виде кода invoice в теле ответа на каждый http запрос.
В случае отсутствия корректного ответа, уведомления будут поступать повторно с каждым новом блоком в течении 24 часов. IP адреса, с которых поступают уведомления, доступны через dns запрос к доменному имени callback.bitaps.com. При не успешном ответе повторные попытки осуществляются с разных IP адресов. Для прекращения отсылки уведомлений достаточно корректного ответа на любое уведомление с количеством подтверждений платежа больше либо равным заданному значению при генерации платежного адреса.
TorПоддерживаются уведомления в сети Tor
При отправке уведомления о поступлении нового платежа или изменению состояния платежа ведется логирование получаемого ответа. Лог содержит IP адрес, с которого производилось уведомление, HTTP статус ответа и 256 символов полученного тела ответа. Для получения логов необходима авторизация по платежному коду Payment Code либо токену доступа домена Access-Token.
Логи ответов обработчика уведомлений о платежах для платежного адреса. Для получения данных необходима авторизация через заголовок Payment-Code или Access-Token.
Логи ответов обработчика уведомлений о платежах по хешу транзакции и номеру выхода платежа. Для получения данных необходима авторизация через заголовок Payment-Code или Access-Token.
Для доступа к статистике о платежах и созданных адресах для домена необходимо создание access token. Для создания токена необходимо авторизовать запрос, используя ссылку на обработчик уведомлений о платежах. Первый этап генерация кода авторизации для указаной ссылки.
Для полученя access token необходимо добавить в обработчик уведомлений платежей вывод кода авторизации в качестве plain/text при GET запросе по данной ссылке.