Создание адреса для платежного шлюза

Общие сведения

Для того, чтобы отправить пользователя на совершение оплаты через платежный шлюз ресурса invcoin24.net требуется иметь подтвержденный (верифицированный) аккаунт на ресурсе payment.invcoin24.net. Наличие данного аккаунта также подразумевает наличие PUBLIC_API и SECRET_API ключа.

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

Как именно отправить пользователя на страницу платежного шлюза для оплаты решает конечный ресурс партнера, который и будет генерировать зашифрованные данные и отправлять пользователя на оплату через платежный шлюз. Это может быть как новая вкладка браузера, popup окно, модальное окно с iframe, в целом практически любым доступным образом.

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

Генерация адреса платежного шлюза

Результирующим адресом для отправки является адрес вида: Адресом, на который требуется отправлять пользователя, является домен, по которому расположен платежный шлюз: http://invcoin24.net/paygate. Также, в GET запросе необходимо передавать параметры PUBLIC_KEY и JWT_TOKEN.

Результирующим будет адрес вида:

http://invcoin24.net/paygate?pub=PUBLIC_KEY&jwt=JWT_TOKEN

Рассмотрим параметры, которые требуются, их предназначение и то, откуда эти параметры взять:

  • PUBLIC_KEY - - публичный ключ аккаунта партнера из раздела payment.invcoin24.net. Выдается он после введенния данных в качестве PUBLIC_API и активируется только после успешного прохождения полной верификации.
  • JWT_TOKEN - это также строка, которая представляет собой зашифрованный JSON обьект. Подробнее можно ознакомиться тут.
{"ticker":{"base":"BTC","target":"USD"," price":"443.7807865468","vol ume":"31720.1493969300","change":"0.3766203596"},"timestamp":1399490941,"success":true,"error":""}

Назначение PUBLIC_KEY

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

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

Назначение JWT_TOKEN

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

Генерация JWT_TOKEN

Для генерации jwt токена можно использовать любую библиотеку для требуемого языка программирования. Например, для PHP есть firebase/php-jwt. Шифрование данных в JWT токен должно происходить по алгоритму HS256. В качестве ключа для шифрования данных должен использоваться SECRET_API, который состоит из 64 символов и выдается вместе с PUBLIC_API. Наличие ключа для шифрования такой длинны позволяет обеспечить высокий уровень безопасности и атакоустойчивости.

Данные в JWT_TOKEN

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

Имя поля Обязательное Описание
product_name ДА название (номер) корзины. varchar255.
price ДА Цена за заказ. float. В валюте, указанной в договоре [usd, eur, rur, btc, eth, zec, xem, dsh, ltc].
user_identity НЕТ Идентификатор пользователя на стороннем ресурсе, с помощью которого будет удобнее идентифицировать пользователя который совершил оплату. varchar255. Это может быть как внутренний идентификатор пользователя, так его емейл, и т.д. Нигде в форме не отображается.
product_identity НЕТ Идентификатор корзины на стороннем ресурсе, с помощью которого будет удобнее идентифицировать заказ за который совершена оплата. varchar255.
return_url НЕТ Ссылка для возврата пользователя. После совершения оплаты через платежный шлюз пользователь увидит страницу с сообщением об успешной оплате, и кнопку “Перейти в кошелек”. Если данный параметр будет передан, то на странице успешной оплаты появиться кнопка “Перейти в магазин”.
language НЕТ Язык на котором изначально будет запущен платежный шлюз и его страницы  - string[en, ru]

Сгенерированный с помощью параметров PUBLIC_KEY и JWT_TOKEN адрес является точкой входа для пользователя, с которой он уже будет направлен далее на процесс оплаты.

Пути движения пользователя по страницам шлюза

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

Возможные ошибки

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

То-же самое происходит если ссылка была сгенерирована корректно и все данные верны, но пользователь переходит с НЕПОДТВЕРЖДЕННОГО в белом списке ресурса. Т.е. его HTTP_REFERER  не был обнаружен в списке “активных сайтов белого списка”.

Получение информации по операциям в платежном шлюзе

Базовые понятия

Контроллеры для выполнения действий через API располагаются по адресу: https://invcoin24.net/paygate/api/v1/

Для доступа к ЛЮБОМУ из контроллеров требуется обязательная передача в хедерах параметров “X-Public-Key” и “X-Signature”, благодаря которым сервис API может определить является ли отправитель валидным, а токен действующим.

Все входящие данные следует передавать в POST параметрах.

X-Public-Key

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

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

X-Signature

Этот параметр представляет собой шифр (подпись) которая позволяет понять является ли запрос верифицированным, т.е. поступает ли от данного партнера и может ли быть выполнен. Формирование данной подписи происходит с помощью алгоритма SHA256. Для формирования данного ключа необходимо рассчитать HMAC посредством зашифровки, ранее выданных при регистрации, публичного и секретного ключа с помощью алгоритма SHA256. Длина публичного ключа - 32 символа. Длина секретного ключа - 64 символа. Такой способ создания подписи позволяет быть уверенным в устойчивости данной подписи.

Пример создания подписи на языке PHP:

hash_hmac('SHA256', $this->public_api, $this->secret_api);

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

На данный момент существует в сервисе два варианта ответа от API: успешный и ошибка.

Успешный вариант может выглядеть таким образом:

{ "success": 1, "data": { "usd": 10 } }

Где success равняется 1, если ответ является успешным, а в объекте data будет содержаться сам результат отработки обращения. Содержание объекта data может меняться в зависимости от метода.

Ответ с ошибкой выглядит таким образом:

{ "success": 0, "message": "Token is required." }

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

Базовые ошибки

Ошибка Разъяснение
X-Public-Key required Не удалось обнаружить в полученных хедерах наличие токена “X-Public-Key”.
X-Signature required Не удалось обнаружить в полученных хедерах наличие токена “X-Signature”.
Public key not found Переданный в хедерах публичный ключ доступа не был найден среди активных партнеров зарегистрированных в платежном шлюзе. Проверьте, был ли он передан корректно, и является ли Ваш аккаунт верифицированным.
Incorrect X-Signature Переданная в хедерах подпись не прошла проверку (не является валидной).

Получение баланса (контроллер баланса)

Получение баланса происходит по следующему адресу: http://invcoin24.net/paygate/api/v1/balance

Обязательные параметры:

Нет.

Необязательные параметры

Параметр Разъяснение
currency Указатель на интересующую валюту. varchar255. Разрешенные валюты: "usd", "eur","rur",  "btc", "eth", "zec", "xem", "dsh", "ltc".

Если передается необязательный параметр currency, то массив с данными ответа содержит представление баланса в переданной валюте. Если данный параметр не был передан, то возвращается массив всех балансов, где ключ - указатель валюты, а значение является балансом.

Пример успешного ответа

{ "success": 1, "data": { "usd": "1.1", "eur": 0, "rur": 0, "btc": "0.6", "eth": 0, "zec": 0, "xem": 0, "dsh": 0, "ltc": 0 } }

Возможные ошибки

Ошибка Разъяснение
Not allowed currency. Allowed only …. Переданная в необязательном параметре currency валюта не находится в списке разрешенных.

Пример ответа с ошибкой

{ "success": 0, "message": "Not allowed currency. Allowed only usd, eur, rur, btc, eth, zec, xem, dsh, ltc" }

Получение списка проведенных оплат (контроллер списка проведенных оплат)

Данный путь позволяет получить список проведенных оплат через платежный шлюз. http://invcoin24.net/paygate/api/v1/payments

Обязательные параметры:

Нет.

Необязательные параметры

Параметр Разъяснение
timestampFrom Метка времени unixtimestamp, указывающая на то, начиная с какого времени будут возвращены проведенные оплаты.
timestampTo Метка времени unixtimestamp, указывающая на то, заканчивая каким временем будут возвращены проведенные оплаты
currencyFilter Фильтрация проведенных операций по результирующей валюте, в которой была совершена оплата. Указатель на интересующую валюту. varchar255. Разрешенные валюты: "usd", "eur","rur",  "btc", "eth", "zec", "xem", "dsh", "ltc".
userIdentityFilter Фильтрация по строковому идентификатору, который передавался в платежный шлюз как “внешний идентификатор пользователя”, позволяет найти все оплаты по пользователю с помощью идентификатора внешнего ресурса (если он передавался в плат. шлюз), работает по принципу %like%. varchar255.
productIdentityFilter Фильтрация по строковому идентификатору, который передавался в платежный шлюз как “внешний идентификатор корзины”, позволяет найти все оплаты по корзине с помощью идентификатора внешнего ресурса (если он передавался в плат. шлюз), работает по принципу %like%. varchar255.
sort Используемый в возвращаемых данных метод сортировки. Подерживаются значения asc, desc. По умолчанию используется DESC. Сортировка применяется ко времени проведения оплаты.
page Возвращаемые данные поддерживают классическую постраничную навигацию. Данный указатель указывает на то, какая именно страница с данными интересует Вас. По умолчанию берется страница 0.
limit Количество платежей, которые будут возвращены в рамках одной страницы. По умолчанию 100. Допустимые параметры 1-1000.

Пример успешного ответа

{ "success": 1, "data": { "page": 0, "pageSize": 1, "totalPages": 11, "totalCount": 11, "payments": [  { "id": 11, "site": "http://localhost", "time": 1527609755, "email": "*****.******@gmail.com", "product_name": "Какой-то заказ", "product_count": 1, "product_price": "0.1000000000", "payed_sum": "0.1000000000", "income_sum": "0.0999000000", "commission": "0.0001000000", "currency": "usd", "user_identity": "[email protected]", "product_identity": "[email protected]" } ], } }

Где:

Возможные ошибки

Ошибка Разъяснение
timestampFrom can by only integer Переданный параметр timestampFrom не является целочисленным.
timestampTo can by only integer Переданный параметр timestampTo не является целочисленным.
Incorrect currency Переданная в параметре currency валюта не находится в списке разрешенных.
Incorrect limit value. Can be [1;1000] Переданный параметр limit не является целочисленным или находится не в предалах от 1 до 1000 включительно.
Incorrect sort direction. Allowed asc, desc Переданный параметр sort некорректен. Поддерживаются только значения asc, desc.

Пример ответа с ошибкой

{ "success": 0, "message": "Incorrect limit value. Can be [1;1000]" }