Пошаговый план базовой интеграции

1. Зарегистрируйте аккаунт в CryptoScan.

2. Добавьте новый Мерчант.

   1. Название — название сайта. Это название будут видеть в платежном виджете.
   2. URL Мерчанта — ссылка на сайт.
   3. Логотип — будет отображен в платежном виджите.

   4. Кто платит комиссию сервиса — кто будет оплачивать комиссию CryptoScan: покупатель или Вы.

      ⚠️ Комиссия все ещё будет списываться с Вашего баланса, но сумма комиссии будет добавлена к сумме, которую пользователь должен заплатить, чтобы её Вам компенсировать.

   5. Максимальный разряд дроби — ограничивает максимальный размер дробной части числа.

      Пример чисел для значения 3: 1.234, 0.789, 2.345.

      Пример чисел для значения 5: 1.23456, 0.98765, 2.34567.

      ❔

      Для чего данная опция?

      В TRON сети мы не можем добавить комментарий к платежу, что создаёт проблему идентификации платежей. Чтобы решить эту проблему, мы добавляем уникальный идентификатор к сумме платежа.

      Пример: два плательщика (А и Б) делают платеж на $100 каждый. Чтобы различить, кто из них оплатил, мы добавляем идентификатор 0.003 к сумме платежа плательщика Б. Теперь его сумма составляет $100.003. Если на баланс поступает $100, это платеж от А, а если $100.003 — это платеж от Б.

      Мы не рекомендуем делать большой разряд суммы, например 6, поскольку пользователям неудобно вводить суммы: $100.0000025. Однако слишком маленький разряд, например 1, также не рекомендуем — иначе сумма идентификатора может быть слишком большой для пользователя, например: $100.1.

   6. Кошелёк USDT TRC20 — можете воспользоваться для его создания TronLink, TrustWallet или другой счёт.

      ⚠️ Если на Вашем кошельке USDT TRC20 большой поток входящих транзакций — рекомендуем завести отдельный кошелёк под наш сервис. Это поможет избежать ошибок при обнаружении транзакций: CryptoScan может неправильно интерпретировать сторонние транзакции как оплату своих счетов.

   7. Ссылка на WebHook — URL на Ваш обработчик, куда будут поступить сообщения об успешной или просроченной оплате.

      После создания Мерчанта — Вам будут доступны ключи для работы с API.

3. Выберите тип аутентификации: по приватном ключу или по подписи.

4. Напишите функционал создания платежа в своём приложении. Можете воспользоваться нашим решением для взаимодействия с API. Для создания платежа с нашим виджетом — воспользуйтесь методом API «Создание виджета для Инвойса». Если Вы хотите сделать виджет собственный виджет оплаты — воспользуйтесь «Создание Инвойса».
5. Напишите функционал обработчика для WebHook-сообщений.

• CryptoScan PHP Client
• Плагин для XenForo — инструкции в README_*.MD

Термины

1. Пользователь — лицо, которое использует действующую систему для выполнения конкретной функции.
2. Мерчант — сайт Пользователя, добавленный в разделе Мерчанты.
3. Инвойс — созданный Пользователем запрос на отслеживание платежа в сети TRON в рамках конкретного Мерчанта.
4. Пользователь API — лицо, которое использует API действующей системы для выполнения конкретной функции.
5. Плательщик — лицо, которое должно оплатить созданный для него Инвойс.

Запрос

Базовый URL: https://cryptoscan.one/api/v1

Тело ответа:

• success - флаг, в зависимости от успешности запроса - содержит true/false
• data - содержит результат выполнения запроса. При неудачном запросе - возвращает информацию об ошибке

Успешный запрос:

{
    "success": true,
    "data": {
        "property": "value",
        "second_property": "second_value"
    }
}

Запросы с ошибкой:

{
    "success": false,
    "data": {
        "name": "Unauthorized",
        "message" : "Your request was made with invalid credentials",
        "code": 0,
        "status": 401
    }
}

Данный ответ включает перечень ошибок в свойстве errors:

{
    "success": false,
    "data": {
        "message": "Invalid request data",
        "errors": {
            "amount": [
                "Amount cannot be blank."
            ],
            "client_reference_id": [
                "Client Reference Id cannot be blank."
            ]
        }
    }
}

Есть два вида аутентификации — по приватному ключу или через подпись запроса. Метод аутентификации переключается в настройках.

Для любого типа аутентификации необходимо передавать публичный ключ Мерчанта в заголовке: public-key.

Аутентификация по приватному ключу

Передайте приватный ключ Мерчанта в HTTP-заголовке private-key.

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

Аутентификация по подписи

1. Сгенерируйте подпись на основе тела запроса и приватного ключа Мерчанта
2. Передайте подпись через HTTP-заголовок signature

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

Подпись используется для аутентификации сообщений WebHook и запросов API при аутентификации по подписи. Для этого используется SHA-256 хеширование.

Для создании подписи необходимо, произвести следующие действия над параметрами запроса:

1. Отсортировать по индексу в порядке возрастания
2. Закодировать в URL-кодировке
3. Хэшировать используя алгоритм SHA-256 HMAC, в качестве секретного ключа — использовать приватный ключ Мерчанта

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

$requestBody['api_key'] = $publicKey;
ksort($requestBody);

$signature = hash_hmac('sha256', http_build_query($requestBody), $privateKey);

Чтобы передать подпись в запрос, добавьте её в HTTP-заголовок запроса signature.

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

Доступные форматы: JSON, XML. Формат определяется в зависимости от содержимого свойства Accept в заголовке запроса.

Формат для JSON:

Accept: application/json

Формат для XML:

Accept: application/xml

Определить ответ вне зависимости от заголовка можно с помощью GET-параметр _format.
Пример: _format=json

Webhook - процедура отправки уведомления на Ваш сервер при наступлении определенного события с Инвойсом.
После просроченной или успешной оплаты система отправит уведомление на данный URL.

Webhook считается успешно доставленным, если Ваш сервер вернул HTTP-код = 200.
В случае неуспешной доставки, системой предусмотрены повторные отправки WebHook, которые отправляются со следующими интервалами:

• Запрос №1: сразу после оплаты
• Запрос №2: 30 секунд
• Запрос №3: 2 минуты
• Запрос №4: 10 минут
• Запрос №5: 60 минут
• Запрос №6: 2 часа
• Запрос №7: 4 часа
• Запрос №8: 6 часов
• Запрос №9: 12 часов
• Запрос №10: 24 часа

После 10-го запроса — новые больше не отправляются. Также после успешной доставки — последующие уведомления не отправляются.

Каждый ответ Вашего сервера на Webhook-сообщение сохраняется, и может быть просмотрен в разделе инвойсов. Указан заголовок ответа и его содержимое обрезанное до 5000 символов.

Основная информация

Типы сообщений на WebHook:

Успешная оплата

• event_type — paid
• retry_count — количество попыток повторной отправки сообщения на WebHook
• data
  • id — ID платежа
  • wallet — кошелёк, куда нужно произвести оплату
  • payer_wallet — кошелёк, с которого произведена оплата
  • transaction_id — ID транзакции в сети TRON
  • source_currency — Валюта, указанная Пользователем (если была передана валюта не USD)
  • source_amount — Сумма в валюте пользователя (если была передана валюта не USD)
  • final_amount — итоговая сумма к оплате (включая "хвост" и комиссию, если её оплачивает покупатель)
  • requested_amount — сумма к оплате запрошенная пользователем
  • status — статус платежа
  • client_reference_id — номер платежа в системе Пользователя API. Должен быть уникальным для каждого Инвойса в рамках Мерчанта
  • metadata — произвольная строка, указываемая пользователем при создании платежа
  • created_at — время создания платежа в unixtime
  • paid_at — дата обнаружения оплаты в unixtime
  • expire_at — время, когда счёт станет просрочен (помните, мы проверяем платеж только 30 минут после создания)

Истек срок оплаты

• event_type — expired
• retry_count — количество попыток повторной отправки сообщения на WebHook
• data
  • id — ID платежа
  • wallet — кошелёк, куда нужно произвести оплату
  • final_amount — итоговая сумма к оплате (включая "хвост" и комиссию, если её оплачивает покупатель)
  • requested_amount — сумма к оплате запрошенная пользователем
  • status — статус платежа
  • client_reference_id — номер платежа в системе Пользователя API. Должен быть уникальным для каждого Инвойса в рамках Мерчанта
  • metadata — произвольная строка, указываемая пользователем при создании платежа
  • created_at — время создания платежа в unixtime
  • expire_at — время, когда счёт станет просрочен (помните, мы проверяем платеж только 30 минут после создания)

Оплата подтверждена вручную

• event_type — paid_manually - возникает при ручном подтверждении инвойса
• retry_count — количество попыток повторной отправки сообщения на WebHook
• data
  • id — ID платежа
  • wallet — кошелёк, куда нужно произвести оплату
  • final_amount — итоговая сумма к оплате (включая "хвост" и комиссию, если её оплачивает покупатель)
  • requested_amount — сумма к оплате запрошенная пользователем
  • status — статус платежа
  • client_reference_id — номер платежа в системе Пользователя API. Должен быть уникальным для каждого Инвойса в рамках Мерчанта
  • metadata — произвольная строка, указываемая пользователем при создании платежа
  • created_at — время создания платежа в unixtime
  • expire_at — время, когда счёт станет просрочен (помните, мы проверяем платеж только 30 минут после создания)

Ручное проведение платежа доступно в лично кабинете пользователя. Для этого:

• перейдите по ссылке
• в списке инвойсов найдите нужный платеж
• нажмите на кнопку "Ручное проведение платежа"

Создаёт запрос на отслеживание транзакции в сети TRON.

(!) Используя этот метод API, Пользователю API необходимо самостоятельно вывести данные для Плательщика: реквизиты, сумму, срок оплаты. Если Вы не хотите делать собственный платежный виджет — воспользуйтесь нашим.

Основная информация

Параметры запроса

Параметры ответа:

Пример ответа:

{
    "success": true,
    "data": {
        "id": "12589",
        "final_amount": "125.69",
        "wallet": "TNVq3iEcaGWbbsR34MTdg1JMTxvYFU8Qir",
        "expire_at": "1677422490",
    }
}

Кроме создание инвойса на оплату, данный запрос создает страницу с виджетом и возвращает URL на неё. Перейдя на эту страницу, Плательщик сможет произвести оплату.

Пример виджета можно посмотреть на странице

Основная информация

Параметры запроса

Параметры ответа:

Пример ответа:

{
    "success": true,
    "data": {
        "id": "523654",
        "final_amount": "133.23",
        "wallet": "TNVq3iEcaGWbbsR34MTdg1JMTxvYFU8Qir",
        "expire_at": "1677422490",
        "widget_url": "https://cryptoscan.one/payment/69908b3b-ac70-4652-9ca2-877e348a2dbe"
    }
}

Основная информация

Параметры запроса

Параметры ответа:

Пример ответа:

{
    "success": true,
    "data": {
        "id": 32,
        "wallet": "TBjkHCYgMb1ohJq77aovAyw4kCMtBEtMGN",
        "payer_wallet": null,
        "transaction_id": null,
        "final_amount": 10.54,
        "requested_amount": "10.54",
        "status": "completed",
        "client_reference_id": "287",
        "metadata": null,
        "created_at": 1678991717,
        "paid_at": null,
        "expire_at": 1678993517
    }
}

Основная информация

Параметры запроса

Параметры ответа:

Пример ответа:

{
  "success": true,
  "data": {
    [
        {
            "id": 36,
            "wallet": "TNVq3iEcaGWbbsR34MTdg1JMTxvYFU8Qir",
            "payer_wallet": "TNVq3iEcaGWbbsR34MTdg1JMTxvYFU8Qir",
            "transaction_id": "1234567890",
            "final_amount": 6.5,
            "requested_amount": "6.50000000",
            "status": "new",
            "client_reference_id": "539",
            "metadata": null,
            "created_at": 1679584937,
            "paid_at": 1679585937,
            "expire_at": 1679586737
        }
    ]
  }
}

Информация

Параметры ответа:

Пример ответа:

{
    "success": true,
    "data": {
        "id": 2,
        "status": "Active",
        "balance": 85.00,
        "currency": "USD"
    }
}

Информация

Параметры ответа:

    {
        "success": true,
        "data": [
            {
                "currency": "BYN",
                "rate": 2.52334,
                "status": "enabled"
            },
            {
                "currency": "EUR",
                "rate": 0.93574,
                "status": "enabled"
            },
            {
                "currency": "GBP",
                "rate": 0.80534,
                "status": "disabled"
            }
        ]
    }
    

Информация

Параметры запроса

Параметры ответа:

Пример ответа:

{
    "success": true,
    "data": {
        "status": "enabled",
        "rate": 0.93574
    }
}