Документация

Навигация по разделам

• Начало работы
• Форма вывода средств
• Форма мерчанта
• Payment_URL (POST)
• Cancel_URL (GET)
• Тестирование
• Поддержка

Начало работы

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

Концептуально интеграция мерчанта предполагает создание в вашем проекте формы вывода средств и реализацию функции оплаты по URL.

Форма вывода средств

Создайте в своём приложении форму вывода средств с полями согласно списка ниже. Если вы используете кастомные монеты, вам необходимо проводить пересчёт объема выводимых средств в BIP.
Список полей формы вывода средств:

• сумма вывода в BIP   amount (обязательно)
• актив, который получит пользователь   exchange_to
• реквизиты для вывода   credentials
• email пользователя (для информирования о ходе вывода)   email

Среди всего перечисленного обязательным является только сумма вывода, остальные поля могут быть реализованы для повышения удобства использования формы, но не являются обязательными.

Валюта вывода
Вы можете прямо в своей форме дать возможность пользователю выбрать в какой банк, платежную систему или криптовалюту вывести средства. Получить список всех вариантов обмена можно по URL https://coins.black/api/directions/bip. В ответ будет возвращен массив с доступными в настоящий момент вариантами обмена, для каждого варианта будет передано имя актива, иконка, тикер, минимальная и максимальная сумма обмена в отдаваемой вами валюте (BIP, XRP, TRX, EOS или ATOM).

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

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

Форма мерчанта

После заполнения пользователем формы вывода средств у вас есть все данные для получения URL-адреса формы мерчанта. Для этого необходимо закодировать JSON-объект с данными в кодировку base64_urlsafe.

Рассмотрим пример, после заполнения пользователем формы на вывод средств в вашем приложении → получаем JSON-объект с данными:

Кодируем данный JSON-объект в base64_urlsafe (например, с помощью сервиса base64encode.net) и получаем строку:
eyJlbWFpbCI6InVzZXJAZW1haWwuY29tIiwNCiJleGNoYW5nZV90byI6IkJUQyIsDQoicGF5bWVudF91cmwiOiJodHRwczovL215c2l0ZS5jb20vcGF5L3gwU3BUUjEiLA0KImNhbmNlbF91cmwiOiJodHRwczovL215c2l0ZS5jb20vcGF5L3gwU3BUUjEvY2FuY2VsIiwNCiJhcHBuYW1lIjoi0JzQvtC5INC/0YDQvtC10LrRgiIsDQoiaWNvbl91cmwiOiJodHRwczovL215c2l0ZS5jb20vZmF2aWNvbnMvMzJ4MzIucG5nIiwNCiJ1c2VybmFtZSI6InVzZXJuYW1lIiwNCiJhbW91bnQiOjE1MCwNCiJjdXJyZW5jeSI6IkJJUCIsDQoiY3JlZGVudGlhbHMiOiIifQ==
Подставив результат в URL https://coins.black/merchant/base64_string_here мы получаем ссылку для открытия формы мерчанта:
https://coins.black/merchant/eyJlbWFpbCI6InVzZXJAZW1haWwuY29tIiwNCiJleGNoYW5nZV90byI6IkJUQyIsDQoicGF5bWVudF91cmwiOiJodHRwczovL215c2l0ZS5jb20vcGF5L3gwU3BUUjEiLA0KImNhbmNlbF91cmwiOiJodHRwczovL215c2l0ZS5jb20vcGF5L3gwU3BUUjEvY2FuY2VsIiwNCiJhcHBuYW1lIjoi0JzQvtC5INC/0YDQvtC10LrRgiIsDQoiaWNvbl91cmwiOiJodHRwczovL215c2l0ZS5jb20vZmF2aWNvbnMvMzJ4MzIucG5nIiwNCiJ1c2VybmFtZSI6InVzZXJuYW1lIiwNCiJhbW91bnQiOjE1MCwNCiJjdXJyZW5jeSI6IkJJUCIsDQoiY3JlZGVudGlhbHMiOiIifQ==
Перейдите по данной ссылке, чтобы посмотреть, как выглядит форма мерчанта
После получения URL-адреса формы → перенаправляем пользователя на неё.

Payment_URL (POST)

Для оплаты заявок на обмен (вывод) средств используется концепция платежных URL. Её суть заключается в том, что при заказе вывода средств пользователем, ваше приложение генерирует Payment_URL для оплаты заявки, при вызове нами Payment_URL (метод POST) ваше приложение отправляет транзакцию в блокчейн на перевод средств в объеме amount (оплата заявки).
Payment_URL должен представлять из себя случайное значение, например: https://mysite.com/pay/x0SpTR1. При вызове он принимает JSON-параметр address, в котором передаётся адрес для оплаты заявки. Перевод должен быть осуществлен ровно на сумму amount, в монете, переданной в параметре currency, учитывайте этот факт при расчёте комиссии за перевод средств.
curl -X POST -k -i 'https://mysite.com/pay/x0SpTR1' --data '{ "address": "Mx885e4baeb81262351de3517b5908f9df9fc" }'
В ответ на вызов Payment_URL сервер должен отправить JSON-объект с параметром hash, в котором указан хэш проведенной транзакции:
{ "hash": "Mt20842d0af66d885e4baeb81262351de3517b5908f9df9fc7410361e28d3c24dd" }
Мы проверим переданный хеш на соответствие данным, указанным в заявке, если всё верно → мерчант отметит заявку как Оплачена и передаст оператору команду на оплату. Если в процессе оплаты возникнет ошибка, мерчант сообщит об этом в максимально доступной форме, чтобы вы поняли в чём дело и смогли устранить неточности.
Для обеспечения безопасности платежей ограничьте возможность вызова Payment_URL только с домена https://coins.black.
HTTP-код ответа сервера при успешном выполнении Payment_URL должен быть 200 (OK).
Рекомендации
Для управления запросами на вывод средств в вашем приложении должна быть таблица Payment_URLs с полями:

• user_id — идентификатор пользователя
• payment_id — идентификатор платежа (в нашем примере это x0SpTR1)
• amount — объем выводимых средств в BIP, XRP, TRX, ATOM или EOS
• status — статус запроса на вывод (awaiting, payed, cancelled, error)

При вызове Payment_URL необходимо убедиться в том, что он ещё не был оплачен (статус awaiting), во избежание проведения двойного списания средств.

Cancel_URL (GET)

Данный URL используется для отмены заявки на вывод средств (когда пользователь нажимает кнопку Отменить вывод в форме мерчанта). При его вызове Payment_URL помечается как отмененный (cancelled), вывод средств по данному Payment_URL будет невозможен (реализуется в вашем приложении).
При отправке ответа на вызов Cancel_URL от вашего приложения включите HTTP-заголовок 'Access-Control-Allow-Origin: https://coins.black' в ответ, иначе любой современный браузер заблокирует данный запрос за несоответствие политике CORS.

Тестирование

Для проведения тестирования при интеграции мерчанта вам необходимо передавать параметр test: true в объекте данных JSON.
Все средства, перечисляемые на наш адрес в рамках заявок с параметром test: true будут возвращены на адрес отправителя автоматически, а создаваемые заявки не будут обработаны оператором, и, по прошествии 30 минут с момента создания будут удалены.
Не забудьте удалить параметр test: true из данных формы по завершению интеграции.

Поддержка

За технической поддержкой 24/7 по интеграции и настройке работы мерчанта обращайтесь в Telegram-чат наших техноангелов FLAT.DIGITAL — @flatdigital_chat.
При возникновении проблем с обработкой заявок, любым финансовым или общим вопросам сразу пишите нашему оператору в чат или на электронную почту [email protected], мы оперативно решим любой ваш вопрос, проконсультируем по проблеме и предоставим пути её решения.