Руководство по интеграции

Всё, что нужно знать для подключения к Twin Bridge — без лишней технической глубины.

Что такое Twin Bridge

Twin Bridge — это технологический мост между международными крипто-провайдерами и локальными лицензированными криптоVASP-операторами. Простыми словами: если провайдер хочет предложить своим клиентам обмен KGS/USDT, но не имеет локальной лицензии и инфраструктуры — Twin Bridge решает эту задачу.

Важно понимать: Twin Bridge не является финансовой компанией, VASP-оператором или кошельком. Мы не прикасаемся к деньгам и не храним средства. Мы передаём данные между участниками — как почтальон, который доставляет письма, но не читает их.

Как это работает

Рассмотрим на примере: клиент провайдера хочет купить USDT за KGS в Кыргызстане.

Для кого

Если вы — провайдер (On/Off-Ramp)

У вас есть международные клиенты, которые хотят работать с KGS или другими локальными валютами. Вам нужны локальные лицензированные партнёры для исполнения — но строить интеграцию с каждым по отдельности долго и дорого.

Twin Bridge даёт вам единый API для доступа ко всем подключённым VASP-операторам. Интегрировались один раз — получили доступ к экосистеме.

Если вы — VASP-оператор

У вас есть лицензия, инфраструктура и возможность исполнять сделки. Но привлечение международного трафика требует ресурсов. Самостоятельно интегрироваться с провайдерами — это месяцы работы для каждого.

Twin Bridge берёт это на себя. Вы подключаетесь один раз, получаете поток клиентов от всех провайдеров в экосистеме.

• Не нужна финансовая лицензия от Twin Bridge — её имеют провайдеры и VASP-операторы
• KYC не нужно проходить повторно — клиент уже верифицирован у провайдера, токен передаётся через Twin Bridge
• Один API вместо N интеграций с каждым партнёром
• Sandbox-режим для тестирования без реальных денег

С чего начать

Шаг 1. Свяжитесь с нами

Напишите на [email protected] или заполните форму на главной странице. Мы согласуем тип партнёрства (провайдер или VASP-оператор) и подпишем NDA.

Шаг 2. Получите API-ключи

После подписания договора вы получите два набора ключей:

• Sandbox-ключи — для тестирования. Реальные сервисы не вызываются, деньги не двигаются.
• Production-ключи — выдаются после успешного тестирования.

Каждый запрос подписывается через HMAC-SHA256. Ключи хранятся только на вашей стороне — мы их не храним в открытом виде.

Шаг 3. Настройте webhook-URL

Укажите URL, на который Twin Bridge будет отправлять уведомления о статусах транзакций. Все входящие webhooks подписаны — вы проверяете подпись и принимаете только легитимные запросы.

Шаг 4. Протестируйте в Sandbox

Запустите несколько тестовых транзакций через Симулятор. Убедитесь, что ваш сервис корректно обрабатывает все статусы и вебхуки.

Шаг 5. Production

Замените Sandbox-ключи на Production. Первые транзакции проходят под нашим мониторингом — мы готовы помочь оперативно, если что-то пойдёт не так.

Поток транзакции

Транзакция проходит через несколько статусов. Каждый статус означает конкретное состояние и следующий ожидаемый шаг.

ON_RAMP (KGS → USDT)

1. Провайдер создаёт транзакцию → статус INITIATED
2. Twin Bridge получает курс и QR → статус PENDING_PAYMENT, QR возвращается провайдеру
3. Клиент оплачивает → статус PAID
4. VASP-оператор исполняет → статус PROCESSING
5. Успешно завершено → статус COMPLETED, webhook провайдеру

Статусы транзакции

Это все возможные состояния транзакции, которые вы будете получать в webhooks и ответах API.

Webhooks

Twin Bridge передаёт уведомления на ваш webhook-URL при каждом изменении статуса транзакции. Это основной способ получать обновления в реальном времени.

Какие события приходят

• payment.created — транзакция создана, QR готов
• payment.completed — транзакция успешно завершена
• payment.failed — транзакция не удалась
• payment.cancelled — транзакция отменена

Как проверить подлинность webhook

Каждый webhook подписан через HMAC-SHA256. Заголовки запроса содержат:

• X-Timestamp — время отправки (Unix timestamp)
• X-Signature — подпись: HMAC_SHA256(secret, timestamp + "." + body)

Проверяйте подпись и убеждайтесь, что timestamp не старше 60 секунд — это защита от replay-атак.

Структура payload

Тело каждого webhook — JSON-объект следующей структуры:

{
  "event_type":  "payment.completed",
  "tx_id":       "8f3d2a1b-...",
  "status":      "COMPLETED",
  "timestamp":   "2026-04-13T10:23:45Z",
  "payload": {
    "tx_id":           "8f3d2a1b-...",
    "status":          "COMPLETED",
    "direction":       "ON_RAMP",
    "fiat_amount":     "5000.00",
    "fiat_currency":   "KGS",
    "crypto_amount":   "57.93",
    "crypto_currency": "USDT",
    "rate":            "86.30",
    "created_at":      "2026-04-13T10:20:00Z",
    "paid_at":         "2026-04-13T10:22:10Z",
    "completed_at":    "2026-04-13T10:23:45Z"
  }
}

Поле failure_reason присутствует только в событиях payment.failed и payment.cancelled. В событии payment.created дополнительно возвращается объект payment с qr_data, qr_url, expires_at, amount, currency.

Гарантия доставки

Twin Bridge использует Outbox Pattern. Если ваш сервер временно недоступен, webhook повторяется по расписанию: немедленно, затем через 1 с, 5 с, 30 с и 5 мин — итого 5 попыток. После исчерпания попыток событие помечается как необработанное и требует ручного разбора. Сделайте ваш обработчик идемпотентным — одно событие может прийти более одного раза.

Авторизация

Каждый запрос к API Twin Bridge должен содержать три заголовка:

• X-API-Key — ваш публичный API-ключ
• X-Timestamp — текущий Unix timestamp
• X-Signature — HMAC-SHA256 подпись запроса

Подпись формируется так: HMAC_SHA256(api_secret, timestamp + method + path + sha256(body))

Timestamp не должен отличаться от серверного времени более чем на 60 секунд. Это защищает от перехвата и повторного использования запросов.

Коды ошибок

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

{
  "error": "Человекочитаемое описание",
  "code":  "MACHINE_READABLE_CODE"
}

Для ошибок, связанных с конкретной транзакцией, дополнительно возвращается поле tx_id.

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

Twin Bridge применяет rate limiting на уровне API-ключа. Лимит: 100 запросов в минуту на каждый ключ (Production и Sandbox считаются раздельно).

При превышении лимита API возвращает 429 Too Many Requests с заголовком Retry-After, указывающим, через сколько секунд лимит сбросится.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error": "rate limit exceeded",
  "code":  "RATE_LIMIT_EXCEEDED"
}

Идемпотентность

Все POST-запросы требуют заголовок Idempotency-Key. Это защита от дублирования: если запрос был отправлен, но ответ не получен (сетевой сбой, таймаут), повторная отправка с тем же ключом вернёт тот же результат без создания новой транзакции.

Как работает

• При первом запросе с ключом — выполняется операция, результат сохраняется на 24 часа
• При повторном запросе с тем же ключом — возвращается сохранённый результат, операция не выполняется повторно
• Ответ на повторный запрос содержит заголовок X-Idempotency-Replayed: true

POST /v1/transactions
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

# Повторный запрос с тем же ключом — ответ идентичен первому:
# X-Idempotency-Replayed: true

Версионирование

Текущая версия API — v1. Все B2B-эндпоинты доступны по префиксу /v1/.

Политика совместимости

В рамках версии v1 мы гарантируем обратную совместимость: не удаляем существующие поля из ответов, не меняем типы данных и не изменяем семантику статусов. Добавление новых необязательных полей в ответы не считается breaking change.

При необходимости ввести несовместимые изменения — выпускается версия v2 по префиксу /v2/. Версия v1 при этом продолжает работать с периодом поддержки не менее 12 месяцев.

Что скачать для интеграции

Готовые артефакты — копируйте и адаптируйте. Все самодостаточные, зависят только от стандартной библиотеки.

• openapi.yaml — машиночитаемый контракт нашего API (Swagger UI, Postman import, codegen)
• openapi-ru.yaml — то же на русском
• openapi-vasp.yaml — обратный контракт для VASP-операторов (DantePay и др.)
• twin-bridge.postman_collection.json — Postman-коллекция со всеми endpoints и авто-подписью запросов
• samples/ — примеры кода:
  • hmac-sign.{go,js,php} — подпись исходящего запроса к TB
  • webhook-receiver.{go,js,php} — приёмник и верификация входящего webhook

Примеры запросов

Ниже — cURL-примеры для основных операций. Замените $API_KEY, $TIMESTAMP и $SIGNATURE своими значениями согласно алгоритму авторизации или используйте готовые sample'ы.

Получить текущие курсы

curl -X GET https://api.twinbridge.io/v1/rates

Получить котировку

curl -X GET "https://api.twinbridge.io/v1/quote?direction=ON_RAMP&fiat_amount=5000&fiat_currency=KGS&crypto_currency=USDT"

Создать транзакцию

curl -X POST https://api.twinbridge.io/v1/transactions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "direction":       "ON_RAMP",
    "fiat_amount":     "5000.00",
    "fiat_currency":   "KGS",
    "crypto_currency": "USDT",
    "crypto_address":  "TRX_ADDRESS_OF_CLIENT",
    "flow":            "QR",
    "kyc_share_token": "sumsub_share_token_here"
  }'

Получить статус транзакции

curl -X GET https://api.twinbridge.io/v1/transactions/8f3d2a1b-4c5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H "X-API-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE"

Отменить транзакцию

curl -X POST https://api.twinbridge.io/v1/transactions/8f3d2a1b-4c5e-6f7a-8b9c-0d1e2f3a4b5c/cancel \
  -H "X-API-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: 660f9511-f3ac-52e5-b827-557766551111" \
  -H "Content-Type: application/json" \
  -d '{}'

Если вы — VASP-оператор

Вы — лицензированный криптообменник Кыргызстана. У вас есть инфраструктура для исполнения сделок KGS/USDT через ELQR. Twin Bridge подключает вас к потоку международных провайдеров через единый стандартизированный интерфейс.

С чего начать (VASP-оператор)

Шаг 1. Свяжитесь с нами

Напишите на [email protected]. Мы проверим наличие лицензии ФСА, согласуем коммерческие условия (referral fee) и подпишем договор.

Шаг 2. Получите API-ключи и webhook-секрет

После подписания договора вы получаете два набора ключей:

• Sandbox API-ключ — для тестирования. Реальные деньги не двигаются.
• Production API-ключ — после успешного прохождения sandbox.
• Webhook-секрет — для верификации входящих запросов от Twin Bridge.

Шаг 3. Реализуйте интеграцию

Twin Bridge вызывает ваш API по стандартному интерфейсу. Подробности — в разделе Что нужно реализовать.

Шаг 4. Настройте входящий webhook-endpoint

Укажите URL вашего сервиса. Twin Bridge передаёт на него подписанные запросы от провайдера при создании транзакции, получении котировки и команды на исполнение. Проверяйте подпись перед обработкой.

Шаг 5. Протестируйте в Sandbox

Пройдите полный цикл в Sandbox: ON_RAMP и OFF_RAMP, успешное завершение, отмена по TTL, FAILED сценарий. Только после этого — Production.

Что нужно реализовать (VASP-оператор)

Twin Bridge вызывает ваш сервис через стандартизированный интерфейс. Вам нужно реализовать следующие методы:

GetQuote — получить котировку

Twin Bridge запрашивает актуальный курс перед созданием каждой транзакции. Rate Engine параллельно опрашивает всех подключённых VASP и выбирает лучший.

# Входящий запрос от Twin Bridge
POST /your-api/quote
{
  "direction":       "ON_RAMP",          // или "OFF_RAMP"
  "fiat_currency":   "KGS",
  "crypto_currency": "USDT",
  "fiat_amount":     "5000.00"           // для ON_RAMP
  // или "crypto_amount": "58.00"        // для OFF_RAMP
}

# Ожидаемый ответ
{
  "rate":            "86.30",            // курс KGS за 1 USDT
  "fiat_amount":     "5000.00",
  "crypto_amount":   "57.93",
  "available":       true,               // есть ли ликвидность
  "expires_at":      "2026-04-16T10:25:00Z"
}

GenerateQR — создать QR для ON_RAMP

Twin Bridge запрашивает QR-ссылку ELQR, которую провайдер покажет клиенту. Клиент сканирует и оплачивает KGS через ELQR — деньги приходят на ваш счёт.

# Входящий запрос от Twin Bridge
POST /your-api/generate-qr
{
  "tx_id":         "8f3d2a1b-...",
  "fiat_amount":   "5000.00",
  "fiat_currency": "KGS",
  "kyc_share_token": "sumsub_token_here"   // passthrough, не расшифровывайте
}

# Ожидаемый ответ
{
  "qr_data":   "00020101...",              // данные QR (ELQR формат)
  "qr_url":    "https://elqr.kg/pay/...", // ссылка для клиента
  "expires_at": "2026-04-16T10:25:00Z"   // TTL QR-кода
}

CreateDepositAddress — создать адрес для OFF_RAMP

Twin Bridge запрашивает TRC-20 адрес, на который провайдер отправит USDT. Вы резервируете адрес и передаёте его обратно через Twin Bridge провайдеру.

# Входящий запрос от Twin Bridge
POST /your-api/deposit-address
{
  "tx_id":           "8f3d2a1b-...",
  "crypto_amount":   "58.00",
  "crypto_currency": "USDT",
  "network":         "TRC20",
  "recipient_kgs_wallet": "+996700123456",  // куда выплачивать KGS клиенту
  "kyc_share_token": "sumsub_token_here"
}

# Ожидаемый ответ
{
  "deposit_address": "TRxMOCK7Kzj...",    // TRC-20 адрес для депозита USDT
  "network":         "TRC20",
  "expires_at":      "2026-04-16T11:00:00Z"
}

Execute (ON_RAMP) — отправить USDT клиенту

После подтверждения оплаты KGS (webhook PAID) Twin Bridge передаёт команду от провайдера на перевод USDT на крипто-адрес клиента.

# Входящий запрос от Twin Bridge
POST /your-api/execute
{
  "tx_id":          "8f3d2a1b-...",
  "crypto_amount":  "57.93",
  "crypto_address": "TRx_CLIENT_WALLET",   // куда слать USDT
  "fiat_amount":    "5000.00"
}

# Ожидаемый ответ — успех
{ "status": "ok", "execution_id": "exec_123" }

# Ожидаемый ответ — ошибка
{ "status": "error", "reason": "insufficient_liquidity" }

ExecuteKGSPayout (OFF_RAMP) — выплатить KGS клиенту

После подтверждения поступления USDT Twin Bridge командует выплатить KGS на реквизиты клиента.

# Входящий запрос от Twin Bridge
POST /your-api/execute-kgs-payout
{
  "tx_id":                "8f3d2a1b-...",
  "fiat_amount":          "4996.00",        // KGS к выплате (за вычетом комиссии)
  "recipient_kgs_wallet": "+996700123456"   // телефон / реквизиты ELQR
}

# Ожидаемый ответ
{ "status": "ok", "payout_id": "payout_456" }

Webhooks от VASP → Twin Bridge

После подтверждения событий на вашей стороне — вы отправляете подписанный webhook в Twin Bridge. Это единственный способ обновить статус транзакции.

Какие события отправлять

• PAID — клиент оплатил KGS через ELQR (ON_RAMP) или вы получили USDT (OFF_RAMP)
• COMPLETED — USDT отправлен клиенту (ON_RAMP) или KGS выплачен клиенту (OFF_RAMP)
• FAILED — исполнение не удалось (технический сбой, нет ликвидности)

Endpoint Twin Bridge для webhooks от вас

POST https://api.twinbridge.io/internal/webhooks/{your_exchanger_id}
X-DantePay-Signature: HMAC_SHA256(secret, timestamp + "." + body)
X-Timestamp: 1713260625

{
  "tx_id":   "8f3d2a1b-...",
  "status":  "PAID",            // или "COMPLETED", "FAILED"
  "event":   "payment.paid",
  "timestamp": "2026-04-16T10:22:10Z"
}

Алгоритм подписи

Подпись формируется так же, как у провайдеров: HMAC_SHA256(webhook_secret, timestamp + "." + body). Секрет выдаётся при подключении. Timestamp не должен отличаться от серверного времени более чем на 60 секунд.

Гарантия доставки

Twin Bridge принимает ваш webhook и подтверждает приём кодом 200 OK. Если ваш webhook не дошёл (ошибка сети), повторите отправку с тем же tx_id — Twin Bridge идемпотентен и не создаст дубликат.

KYC и комплаенс

Twin Bridge не проводит KYC и не хранит персональные данные клиентов. Вся верификация — ответственность провайдера и VASP-оператора.

Как работает KYC passthrough

Если провайдер уже верифицировал клиента (через Sumsub или аналогичный сервис), он передаёт kyc_share_token при создании транзакции. Twin Bridge передаёт этот токен VASP-оператору — тот проверяет его напрямую у KYC-провайдера.

Twin Bridge не видит содержимое токена и не расшифровывает его. Только транспортирует.

• Twin Bridge не является VASP и не требует финансовой лицензии
• KYC/AML — ответственность провайдеров и VASP-операторов
• Персональные данные клиентов не хранятся на стороне Twin Bridge
• Все VASP-операторы в экосистеме лицензированы ФСА КР

Тестовая среда (Sandbox)

Sandbox позволяет протестировать полный поток транзакции без реальных денег. Все вызовы к VASP-операторам и провайдерам перехватываются Mock-адаптерами.

Как включить Sandbox

Добавьте заголовок X-Sandbox: true к любому запросу — и он будет обработан через Mock-адаптеры. Используйте Sandbox API-ключи (они отличаются от Production).

Симулятор

Откройте Симулятор — интерактивный дашборд, который демонстрирует все тестовые сценарии: успешный ON_RAMP, отмену, возврат, таймаут и другие.

Вопросы и ответы