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

Полное руководство по интеграции GranumCash API для приема платежей на вашем сайте

Содержание

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

Базовый URL

https://granumpay.cc/api

Получение API ключа

  1. Зарегистрируйтесь в системе
  2. Войдите в личный кабинет
  3. Перейдите в раздел "Настройки"
  4. Скопируйте ваш API ключ

Важно

Никогда не размещайте API ключ в публично доступном коде. Используйте его только на серверной стороне.

Аутентификация

Все запросы к API должны содержать заголовок авторизации с вашим API ключом:

Authorization: Bearer YOUR_API_KEY

Возможные ошибки аутентификации:

401 Unauthorized Неверный или отсутствующий API ключ
403 Forbidden Аккаунт заблокирован

Лимиты запросов

60
запросов в минуту
1000
запросов в час

При превышении лимитов:

429 Too Many Requests - Слишком много запросов, повторите позже

Методы API

POST /create-payment

Создание нового платежа

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

Параметр Тип Обязательный Описание
amount number Да Сумма платежа в USD (мин. 5.00)
description string Нет Описание платежа (макс. 500 символов)
webhook_url string Нет URL для уведомлений о смене статуса

Пример запроса:

curl -X POST https://granumpay.cc/api/create-payment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "description": "Оплата заказа #123",
    "webhook_url": "https://your-site.com/webhook"
  }'

Успешный ответ (200 OK):

{
  "success": true,
  "payment_id": "abc123def456...",
  "payment_url": "https://granumpay.cc/payment/abc123def456...",
  "amount_usd": "100.00",
  "expires_at": "2025-07-01 15:30:00"
}

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

400 Bad Request
{
  "success": false,
  "errors": {
    "amount": "Field amount is required"
  }
}
GET /payment/{id}

Получение детальной информации о платеже

Пример запроса:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://granumpay.cc/api/payment/abc123def456...

Успешный ответ (200 OK):

{
  "success": true,
  "payment": {
    "id": "abc123def456...",
    "amount_usd": "100.00",
    "received_amount_usd": "103.00",
    "currency": "USDT",
    "network": "TRC20",
    "payment_method": "crypto",
    "status": "confirmed",
    "description": "Оплата заказа #123",
    "commission_usd": "3.00",
    "created_at": "2025-07-01 14:30:00",
    "confirmed_at": "2025-07-01 14:35:00",
    "expires_at": "2025-07-01 15:30:00"
  }
}

Статусы платежей:

pending
Ожидает оплаты
confirmed
Подтвержден
expired
Истек срок
failed
Не удался
GET /balance

Получение текущего баланса аккаунта

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

{
  "success": true,
  "balance_usd": "1234.567890"
}
GET /payments

Получение истории платежей с фильтрацией

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

Параметр Тип Описание
page number Номер страницы (по умолчанию: 1)
limit number Количество записей на странице (макс: 100)
status string Фильтр по статусу (pending, confirmed, expired, failed)
currency string Фильтр по валюте (USDT, UAH)
payment_method string Фильтр по методу (crypto, fiat)
date_from string Дата начала (YYYY-MM-DD)
date_to string Дата окончания (YYYY-MM-DD)

Пример запроса:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://granumpay.cc/api/payments?page=1&limit=10&status=confirmed"

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

{
  "success": true,
  "payments": [
    {
      "id": "abc123...",
      "amount_usd": "100.00",
      "received_amount_usd": "103.00",
      "currency": "USDT",
      "network": "TRC20",
      "payment_method": "crypto",
      "status": "confirmed",
      "commission_usd": "3.00",
      "created_at": "2025-07-01 14:30:00",
      "confirmed_at": "2025-07-01 14:35:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 47,
    "per_page": 10
  }
}
POST /create-withdrawal

Создание заявки на вывод средств

Ограничение

Вывод доступен только в USDT через сеть TRC20

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

Параметр Тип Обязательный Описание
amount number Да Сумма вывода в USD (мин. 10.00)
currency string Да Валюта (только USDT)
network string Да Сеть (только TRC20)
address string Да Адрес кошелька для вывода

Пример запроса:

curl -X POST https://granumpay.cc/api/create-withdrawal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "USDT",
    "network": "TRC20",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

Успешный ответ (200 OK):

{
  "success": true,
  "withdrawal_id": 123
}
GET /withdrawals

Получение истории выводов

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

Параметры page и limit работают аналогично методу /payments

Статусы выводов:

pending
На рассмотрении
approved
Одобрен к выводу
completed
Завершен
rejected
Отклонен

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

{
  "success": true,
  "withdrawals": [
    {
      "id": 123,
      "amount_usd": "100.00",
      "amount_after_commission": "97.00",
      "currency": "USDT",
      "network": "TRC20",
      "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
      "status": "completed",
      "commission_usd": "3.00",
      "tx_hash": "1a2b3c4d5e...",
      "rejection_reason": null,
      "created_at": "2025-07-01 14:30:00",
      "processed_at": "2025-07-01 15:45:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_count": 25,
    "per_page": 10
  }
}
GET /currencies PUBLIC

Получение списка поддерживаемых валют и методов оплаты

Примечание: Этот метод не требует авторизации

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

{
  "success": true,
  "currencies": [
    {
      "type": "crypto",
      "currency": "USDT",
      "name": "Tether USD",
      "networks": [
        {
          "network": "TRC20",
          "name": "TRON (TRC20)",
          "commission_percent": 3,
          "min_amount_usd": 5
        }
      ]
    },
    {
      "type": "fiat",
      "currency": "UAH",
      "name": "Украинская гривна",
      "methods": [
        {
          "method": "card",
          "name": "Банковская карта"
        }
      ],
      "commission_percent": 13,
      "min_amount_usd": 10
    }
  ]
}
GET /rates PUBLIC

Получение актуальных курсов валют

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

{
  "success": true,
  "rates": {
    "USD": 1,
    "USDT": 1.00,
    "UAH": 41.50
  },
  "base_currency": "USD",
  "updated_at": "2025-07-01 14:30:00"
}

Коды ошибок

HTTP Код Описание Причины Решение
400 Bad Request Неверные параметры запроса Проверьте правильность данных
401 Unauthorized Неверный или отсутствующий API ключ Проверьте заголовок Authorization
403 Forbidden Аккаунт заблокирован Обратитесь в поддержку
404 Not Found Ресурс не найден Проверьте правильность URL и ID
429 Too Many Requests Превышен лимит запросов Уменьшите частоту запросов
500 Internal Server Error Ошибка сервера Повторите запрос позже

Формат ошибок

Все ошибки возвращаются в JSON формате:

{
  "success": false,
  "error": "Описание ошибки"
}

Для ошибок валидации (400 Bad Request):

{
  "success": false,
  "errors": {
    "amount": "Field amount is required",
    "address": "Invalid address format"
  }
}

Webhook уведомления

Система автоматически отправляет уведомления о смене статуса платежа на указанный webhook URL.

Настройка webhook

Webhook URL можно указать при создании платежа или настроить в профиле как URL по умолчанию.

Структура уведомления

{
  "payment_id": "abc123def456...",
  "status": "confirmed",
  "payment_method": "crypto",
  "amount_usd": "100.00",
  "received_amount_usd": "103.00",
  "currency": "USDT",
  "commission_usd": "3.00",
  "description": "Оплата заказа #123",
  "confirmed_at": "2025-07-01 14:35:00"
}

Подписание запросов

Все webhook запросы содержат заголовок X-Webhook-Signature с HMAC-SHA256 подписью.

Проверка подписи (PHP):

$receivedSignature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$payload = file_get_contents('php://input');
$expectedSignature = hash_hmac('sha256', $payload, $secretKey);

if (hash_equals($expectedSignature, $receivedSignature)) {
    // Подпись верна, обрабатываем уведомление
    $data = json_decode($payload, true);
}

Важно: Всегда проверяйте подпись для обеспечения безопасности. В качестве секретного ключа используйте ваш API ключ.

Примеры cURL

# Создание платежа
curl -X POST https://granumpay.cc/api/create-payment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "description": "Оплата заказа #123",
    "webhook_url": "https://your-site.com/webhook"
  }'

# Проверка статуса платежа
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://granumpay.cc/api/payment/abc123def456...

# Получение баланса
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://granumpay.cc/api/balance

# Список платежей с фильтрацией
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://granumpay.cc/api/payments?status=confirmed&limit=10"

# Создание заявки на вывод
curl -X POST https://granumpay.cc/api/create-withdrawal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "currency": "USDT",
    "network": "TRC20",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

# Курсы валют (без авторизации)
curl https://granumpay.cc/api/rates

# Список валют (без авторизации)
curl https://granumpay.cc/api/currencies