Приём криптоплатежей через GramPay

REST API для выставления счетов в долларах и приёма оплаты в Gram (GRAM, бывший Toncoin) и USDT. Клиент выбирает удобную сеть, GramPay сам находит перевод в блокчейне и отправляет вашему серверу подписанный вебхук.

Авторизация

Зарегистрируйтесь и создайте ключ в кабинете: Разработчикам → API-ключи. Ключ показывается один раз — храните его на сервере и никогда не передавайте в браузер.

Передавайте ключ в заголовке Authorization или X-API-Key:

Authorization: Bearer gp_live_XXXXXXXXXXXXXXXXXXXXXXXX

Как проходит оплата

1. Создайте счёт через POST /invoices с суммой в USD.
2. Перенаправьте клиента на pay_url из ответа или встройте страницу в iframe.
3. Клиент платит в выбранной сети. Курс GRAM фиксируется на время жизни счёта.
4. Получите вебхук invoice.paid и выдайте товар. Статус можно также проверить через GET /invoices/{id}.

POST /invoices

Создаёт счёт. Все поля, кроме amount, необязательны.

curl -X POST https://grampay.top/api/v1/invoices \
  -H "Authorization: Bearer $GRAMPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "description": "Заказ #1042",
    "order_id": "1042",
    "callback_url": "https://shop.example/api/grampay",
    "success_url": "https://shop.example/thanks"
  }'

import os, requests

resp = requests.post(
    "https://grampay.top/api/v1/invoices",
    headers={"Authorization": f"Bearer {os.environ['GRAMPAY_KEY']}"},
    json={"amount": 25.00, "order_id": "1042",
          "callback_url": "https://shop.example/api/grampay"},
    timeout=15,
)
resp.raise_for_status()
invoice = resp.json()
redirect(invoice["pay_url"])

const resp = await fetch("https://grampay.top/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GRAMPAY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 25, order_id: "1042",
    callback_url: "https://shop.example/api/grampay" }),
});
const invoice = await resp.json();
res.redirect(invoice.pay_url);

$ch = curl_init("https://grampay.top/api/v1/invoices");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("GRAMPAY_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "amount" => 25.00, "order_id" => "1042",
    "callback_url" => "https://shop.example/api/grampay",
  ]),
]);
$invoice = json_decode(curl_exec($ch), true);
header("Location: " . $invoice["pay_url"]);

GET /invoices/{id}

Возвращает объект счёта с актуальным статусом и списком поступлений.

curl https://grampay.top/api/v1/invoices/inv_uRofqKNn1Ybc \
  -H "Authorization: Bearer $GRAMPAY_KEY"

GET /invoices

Список счетов, новые первыми. Параметры: status, limit (до 200, по умолчанию 50), offset.

{ "total": 128, "items": [ { "id": "inv_…", "status": "paid", … } ] }

POST /invoices/{id}/cancel

Отменяет счёт в статусе pending или underpaid. Если по счёту задан callback_url, придёт вебхук invoice.cancelled.

GET /balance

Баланс вашего аккаунта: оплаты в GRAM копятся в GRAM, оплаты USDT из любой сети — в USDT. Вывод — в кабинете, раздел Баланс.

{ "GRAM": 12.5, "USDT": 340.75 }

Объект счёта

{
  "id": "inv_uRofqKNn1Ybc",
  "code": "GPVXYLFF",            // код оплаты (комментарий для сетей TON)
  "status": "paid",
  "amount_usd": 25.0,
  "received_usd": 25.0,
  "description": "Заказ #1042",
  "order_id": "1042",
  "created_at": "2026-09-27T14:58:03+00:00",
  "expires_at": "2026-09-27T15:28:03+00:00",
  "paid_at": "2026-09-27T15:02:41+00:00",
  "paid_method": "usdt_ton",
  "rate_ton": 1.5886,           // курс GRAM/USD, зафиксированный в счёте
  "pay_url": "https://grampay.top/pay/inv_uRofqKNn1Ybc",
  "success_url": "https://shop.example/thanks",
  "callback_url": "https://shop.example/api/grampay",
  "metadata": null,
  "methods": [
    {
      "id": "usdt_ton", "asset": "USDT", "network": "ton", "network_label": "TON",
      "amount": "25", "amount_units": "25000000",
      "address": "UQBVJBdAXQ7dh1x…", "memo": "GPVXYLFF",
      "deeplink": "ton://transfer/UQBV…?jetton=EQCx…&amount=25000000&text=GPVXYLFF"
    }
  ],
  "payments": [
    {
      "method": "usdt_ton", "amount": 25.0, "usd_value": 25.0,
      "tx_hash": "…", "explorer": "https://tonviewer.com/transaction/…",
      "block_time": "2026-09-27T15:02:35+00:00"
    }
  ]
}

Статусы

GET /methods

Способы оплаты, которые сейчас включены в магазине.

Для сетей без комментариев к сумме добавляются доли цента (например, 25.0037 USDT), чтобы однозначно связать перевод со счётом.

GET /rates

Текущий курс — медиана котировок нескольких бирж.

{ "GRAM_USD": 1.5886, "TON_USD": 1.5886, "USDT_USD": 1.0, "updated_at": "2026-09-27T15:04:56+00:00" }

Вебхуки

При смене статуса счёта GramPay отправляет POST на callback_url. События: invoice.paid, invoice.underpaid, invoice.expired, invoice.cancelled.

POST /api/grampay HTTP/1.1
Content-Type: application/json
User-Agent: GramPay-Webhooks/1.0
X-GramPay-Event: invoice.paid
X-GramPay-Timestamp: 1790521361
X-GramPay-Signature: 5f2b0c…e91a

{
  "event": "invoice.paid",
  "invoice": { "id": "inv_…", "status": "paid", "order_id": "1042", … },
  "sent_at": "2026-09-27T15:02:41+00:00"
}

Ответьте кодом 2xx в течение 15 секунд. Иначе доставка повторится через 1, 5, 30 минут, 2 и 6 часов. Обработчик должен быть идемпотентным: одно событие может прийти несколько раз.

Проверка подписи

Подпись — HMAC-SHA256 в hex от строки {timestamp}.{сырое тело запроса}. Секрет находится в кабинете: Разработчикам → Подпись вебхуков. Отклоняйте запросы старше 5 минут.

import hashlib, hmac, time

def verify(body: bytes, headers, secret: str) -> bool:
    ts = headers["X-GramPay-Timestamp"]
    sig = headers["X-GramPay-Signature"]
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

import crypto from "node:crypto";

// rawBody — Buffer с исходным телом запроса (до JSON.parse)
export function verify(rawBody, headers, secret) {
  const ts = headers["x-grampay-timestamp"];
  const sig = headers["x-grampay-signature"] || "";
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${ts}.`).update(rawBody).digest("hex");
  return sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

$body = file_get_contents("php://input");
$ts = $_SERVER["HTTP_X_GRAMPAY_TIMESTAMP"] ?? "";
$sig = $_SERVER["HTTP_X_GRAMPAY_SIGNATURE"] ?? "";
$expected = hash_hmac("sha256", $ts . "." . $body, getenv("GRAMPAY_WEBHOOK_SECRET"));
if (abs(time() - (int)$ts) > 300 || !hash_equals($expected, $sig)) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);

Встраивание

Страницу оплаты можно открыть в новой вкладке, в Telegram WebApp или встроить на сайт:

<iframe src="https://grampay.top/pay/inv_uRofqKNn1Ybc"
        width="480" height="760" style="border:0;border-radius:24px"></iframe>

Ошибки

Ошибки возвращаются с HTTP-кодом 4xx/5xx и телом {"error": "описание"}.