API
EnglishВебхуки
Когда платёж приходит в итоговый статус, мы отправляем подписанный POST-запрос на ваш сервер. Проверьте подпись — и обновляйте заказ.
Куда приходят уведомления
- На адрес по умолчанию из настроек ключа.
- Или на webhook_url, переданный при создании платежа, — для этого платежа он главнее.
- Адрес должен быть публичным. Внутренние и частные адреса отклоняются, повторов по ним нет.
Когда отправляем
При итоговых статусах платежа: paid, expired, canceled, failed и manual_confirmation.
Что отправляем
{
"event": "invoice.status_changed",
"payment_id": "pay_3f9a1c2b7d4e5f60",
"bill_uid": "3f9a1c2b-7d4e-5f60-…",
"order_id": "order_123",
"status": "paid",
"amount": 100.0,
"currency": "USDT",
"customer_email": "",
"customer_name": "",
"timestamp": 1763380800
}При статусе paid в теле есть и разбивка комиссии: commission, commission_rate, commission_fixed, net_amount и net_currency.
| Заголовок | Значение |
|---|---|
| X-Webhook-Signature | sha256=<hex>: подпись тела, см. ниже |
| X-Webhook-Event | acquiring.invoice_status_changed |
| X-Webhook-Id | Номер уведомления. Одинаковый при каждом повторе — по нему отбрасывайте дубли |
| X-Webhook-Timestamp | Время события, секунды Unix. Подписью не защищён |
| User-Agent | TeleportExchange-Webhook/1.0 |
Как проверить подпись
- Подпись — HMAC-SHA256 от сырого тела запроса, в шестнадцатеричном виде строчными буквами, в формате sha256=<hex>.
- Ключ — ваш секрет вебхуков ровно в том виде, в каком его показывают настройки ключа: строка целиком, вместе с префиксом whsec_.
- Считайте подпись по байтам тела в том виде, в каком они пришли, до разбора JSON: повторная сериализация меняет байты и ломает подпись.
- Сравнивайте за постоянное время. Отклоняйте запрос, если заголовка нет или он не совпал.
- Чтобы отсекать слишком старые уведомления, используйте поле timestamp внутри тела — оно подписано.
import hashlib, hmac
def is_valid(raw_body: bytes, header: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header or "")import crypto from "node:crypto"
function isValid(rawBody, header, secret) {
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex")
const a = Buffer.from(expected)
const b = Buffer.from(header || "")
return a.length === b.length && crypto.timingSafeEqual(a, b)
}Каким ключом подписано
Секретом того API-ключа, которым создан платёж. Для платежей, созданных до появления подписи: ключом того же счёта, иначе ключом с тем же адресом вебхука, иначе самым старым активным ключом. Если активных ключей нет совсем, уведомление уходит без подписи.
Доставка и повторы
- Ответьте любым 2xx в течение 10 секунд. Всё остальное считается неудачной попыткой.
- Неудачную доставку повторяем через 30 секунд и ещё раз через 5 минут — всего три попытки, с тем же телом и тем же X-Webhook-Id.
- После третьей неудачи уведомление помечается как не доставленное и автоматически больше не отправляется. На сам платёж это не влияет: его статус всегда можно получить через API.
WooCommerce
Нужен плагин версии 1.1.0 или новее с заполненным полем Webhook Secret. Секрет скопируйте из настроек ключа (начинается с whsec_). Плагин проверяет каждое уведомление и отклоняет с ответом 403 те, у которых нет подписи, она неверна или поле секрета пустое. Скачать — один PHP-файл в wp-content/plugins/: английская версия https://gate.teleport.ltd/api/crypto-acquiring/developers/download/woocommerce/, русская https://gate.teleport.ltd/api/crypto-acquiring/developers/download/woocommerce-ru/.
curl https://gate.teleport.ltd/api/crypto-acquiring/v1/invoice/<bill_uid>/ \
-H "X-API-Key: <YOUR_API_KEY>"