Paylane
ДокументацияСтатус
ВойтиСоздать аккаунт

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

  • Обзор
  • Адреса и окружения
  • Авторизация
  • Формат ответа
  • Ошибки
  • Идемпотентность
  • Лимиты

Методы API

  • Методы
  • GET/me
  • GET/currencies
  • POST/invoices
  • GET

Справочник

  • Инвойсы: статусы и жизненный цикл
  • Выводы: статусы
  • Вебхуки
  • Проверка подписи
  • Публичный API страницы оплаты
  • Testnet, mainnet и Simnet

Документы

  • Оферта для мерчантов
  • Политика конфиденциальности
  • AML/KYC-политика
Разделы: Проверка подписи

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

  • Обзор
  • Адреса и окружения
  • Авторизация
  • Формат ответа
  • Ошибки

Paylane

Paylane: приём платежей в стейблкоинах

Продукт

ДокументацияСтатусВойтиСоздать аккаунт

Документы

ОфертаКонфиденциальностьAML-политика
/invoices
  • GET/invoices/{id}
  • DELETE/invoices/{id}
  • GET/balance
  • POST/withdrawals
  • GET/withdrawals/{id}
  • GET/stats
  • POST/webhooks/test
  • POST/webhooks/{update_id}/resend
  • POST/sandbox/invoices/{id}/pay
  • POST/sandbox/events
  • Sandbox и тестовые сценарии
    Идемпотентность
  • Лимиты
  • Методы API

    • Методы
    • GET/me
    • GET/currencies
    • POST/invoices
    • GET/invoices
    • GET/invoices/{id}
    • DELETE/invoices/{id}
    • GET/balance
    • POST/withdrawals
    • GET/withdrawals/{id}
    • GET/stats
    • POST/webhooks/test
    • POST/webhooks/{update_id}/resend
    • POST/sandbox/invoices/{id}/pay
    • POST/sandbox/events

    Справочник

    • Инвойсы: статусы и жизненный цикл
    • Выводы: статусы
    • Вебхуки
    • Проверка подписи
    • Публичный API страницы оплаты
    • Testnet, mainnet и Simnet
    • Sandbox и тестовые сценарии

    Документы

    • Оферта для мерчантов
    • Политика конфиденциальности
    • AML/KYC-политика

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

    Пример
    signature = hex( HMAC-SHA256( key = SHA256(webhook_secret), message = сырое тело запроса ) )
    • webhook_secret это секрет приложения из настроек кабинета (64 hex-символа). API-токен для подписи не используется.
    • Подпись считается от байтов, которые пришли. Не сериализуйте JSON заново перед проверкой: порядок ключей и пробелы изменятся.
    • Сравнивайте за постоянное время.
    • Секрет меняется в настройках приложения кнопкой ротации. Новый секрет действует сразу, переходного периода нет (запланирован к 1.0.0). На время смены принимайте подпись от любого из двух секретов.
    Тестовый вектор (для самопроверки)
    webhook_secret = "aaaa…a" (64 символа "a")
    body           = {"payload":{"amount":"100.00","currency":"USDT","description":"Заказ №5512","fee":"1.00","invoice_id":10452,"network":"tron","paid_amount":"100.00","paid_at":"2026-11-04T18:41:55Z","payload":"order_5512","status":"paid","txid":"7f3a9c"},"request_date":"2026-11-04T18:42:10Z","update_id":7,"update_type":"invoice_paid"}
    signature      = a72ffff8fad1f9d64a8bac41d4ce91cc10a0f4a8c45770df323c2738d15f8cda

    Тело в UTF-8, без перевода строки в конце.

    python
    import hashlib
    import hmac
    
    def verify_paylane(raw_body: bytes, signature: str, webhook_secret: str) -> bool:
        key = hashlib.sha256(webhook_secret.encode()).digest()
        expected = hmac.new(key, raw_body, hashlib.sha256).hexdigest()
        return hmac.compare_digest(expected, signature.strip().lower())
    
    # FastAPI
    @app.post("/paylane/webhook")
    async def webhook(request: Request):
        body = await request.body()
        signature = request.headers.get("Paylane-Signature", "")
        if not verify_paylane(body, signature, WEBHOOK_SECRET):
            return Response(status_code=401)
        update = json.loads(body)
        ...
        return {"ok": True}

    С SDK: paylane.parse_webhook(body, signature, WEBHOOK_SECRET).

    js
    import { createHash, createHmac, timingSafeEqual } from "node:crypto";
    
    export function verifyPaylane(rawBody, signature, webhookSecret) {
      const key = createHash("sha256").update(webhookSecret, "utf8").digest();
      const expected = Buffer.from(createHmac("sha256", key).update(rawBody).digest("hex"));
      const given = Buffer.from(String(signature || "").trim().toLowerCase());
      return expected.length === given.length && timingSafeEqual(expected, given);
    }
    
    // Express: тело нужно сырым, поэтому express.raw, а не express.json
    app.post("/paylane/webhook", express.raw({ type: "application/json" }), (req, res) => {
      const signature = req.get("Paylane-Signature");
      if (!verifyPaylane(req.body, signature, process.env.PAYLANE_WEBHOOK_SECRET)) return res.sendStatus(401);
      const update = JSON.parse(req.body.toString("utf8"));
      res.sendStatus(200);
    });

    С SDK: parseWebhook(body, signatureFromHeaders(req.headers), secret).

    php
    <?php
    function paylane_verify(string $rawBody, string $signature, string $webhookSecret): bool {
        $key = hash('sha256', $webhookSecret, true);        // двоичный SHA-256 секрета
        $expected = hash_hmac('sha256', $rawBody, $key);     // hex
        return hash_equals($expected, strtolower(trim($signature)));
    }
    
    $body = file_get_contents('php://input');
    $signature = $_SERVER['HTTP_PAYLANE_SIGNATURE'] ?? $_SERVER['HTTP_CRYPTO_PAY_API_SIGNATURE'] ?? '';
    if (!paylane_verify($body, $signature, getenv('PAYLANE_WEBHOOK_SECRET'))) {
        http_response_code(401);
        exit;
    }
    $update = json_decode($body, true);
    http_response_code(200);
    go
    import (
    	"crypto/hmac"
    	"crypto/sha256"
    	"encoding/hex"
    	"io"
    	"net/http"
    	"strings"
    )
    
    func VerifyPaylane(rawBody []byte, signature, webhookSecret string) bool {
    	key := sha256.Sum256([]byte(webhookSecret))
    	mac := hmac.New(sha256.New, key[:])
    	mac.Write(rawBody)
    	given, err := hex.DecodeString(strings.TrimSpace(signature))
    	return err == nil && hmac.Equal(mac.Sum(nil), given)
    }
    
    func webhook(w http.ResponseWriter, r *http.Request) {
    	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
    	if err != nil {
    		w.WriteHeader(http.StatusBadRequest)
    		return
    	}
    	sig := r.Header.Get("Paylane-Signature")
    	if !VerifyPaylane(body, sig, secret) {
    		w.WriteHeader(http.StatusUnauthorized)
    		return
    	}
    	// json.Unmarshal(body, &update) ...
    	w.WriteHeader(http.StatusOK)
    }
    rust
    // Cargo.toml: hmac = "0.12", sha2 = "0.10", hex = "0.4"
    use hmac::{Hmac, Mac};
    use sha2::{Digest, Sha256};
    
    pub fn verify_paylane(raw_body: &[u8], signature: &str, webhook_secret: &str) -> bool {
        let key = Sha256::digest(webhook_secret.as_bytes());
        let Ok(given) = hex::decode(signature.trim()) else { return false };
        let mut mac = Hmac::<Sha256>::new_from_slice(&key).expect("HMAC takes a key of any length");
        mac.update(raw_body);
        mac.verify_slice(&given).is_ok() // сравнение за постоянное время
    }
    
    // axum: тело берём как Bytes, не как Json, иначе байты для подписи потеряются
    async fn webhook(headers: axum::http::HeaderMap, body: axum::body::Bytes) -> axum::http::StatusCode {
        let signature = headers.get("Paylane-Signature").and_then(|v| v.to_str().ok()).unwrap_or("");
        if !verify_paylane(&body, signature, &std::env::var("PAYLANE_WEBHOOK_SECRET").unwrap_or_default()) {
            return axum::http::StatusCode::UNAUTHORIZED;
        }
        // let update: serde_json::Value = serde_json::from_slice(&body)?;
        axum::http::StatusCode::OK
    }

    Все пять сниппетов проверены на тестовом векторе выше.

    НазадВебхукиДальше Публичный API страницы оплаты