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

Всё, что нужно знать для подключения к 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-режим для тестирования без реальных денег

Способы подключения

Twin Bridge поддерживает пять путей интеграции в зависимости от ваших технических возможностей и категории партнёра. Способ хранится в partners.integration_mode и виден в админ-кабинете.

Для провайдеров (PROVIDER) — три варианта

Для провайдера бизнес-модель фиксируется отдельно от подключения флагом partners.has_usdt_custody: custody означает Phase 1, lead-gen означает Phase 2. В режимах self_api и we_pull провайдер остаётся активным участником: ведёт свой KYC, свой UI и передаёт данные в Twin Bridge.

Для VASP-операторов (VASP) — два варианта

С чего начать

Шаг 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 не старше 300 секунд — это защита от 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 не должен отличаться от серверного времени более чем на 300 секунд. Это защищает от перехвата и повторного использования запросов.

Коды ошибок

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

{
  "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://twinbridge.kg/v1/rates

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

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

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

curl -X POST https://twinbridge.kg/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://twinbridge.kg/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://twinbridge.kg/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 вызывает ваш сервис через стандартизированный интерфейс. Вам нужно реализовать следующие методы:

По актуальной модели VASP подключается как hybrid: умеет Phase 1 для custody-провайдеров и Phase 2 для lead-gen провайдеров. Канонический контракт — 7 endpoint'ов /vasp/v1/*: 5 базовых (quote, qr, payout, tx, health) плюс Phase 2 send-usdt и usdt-deposit-address, точная HMAC-подпись и webhooks. Полная спецификация: site/docs/vasp-contract.md.

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

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

# Входящий запрос от Twin Bridge — POST /vasp/v1/quote
{
  "pair":           "KGS/USDT",
  "amount":         "5000.00",
  "direction":      "ON_RAMP",            // или "OFF_RAMP"
  "payment_method": "elqr"                // опционально
}

# Ожидаемый ответ
{
  "quote_id":      "q_7f3d...",
  "rate":          "86.30",               // курс KGS за 1 USDT
  "fiat_amount":   "5000.00",
  "crypto_amount": "57.93",
  "fee":           "0",
  "expires_at":    "2026-04-16T10:25:00Z" // max 5 мин
}

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

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

# Входящий запрос от Twin Bridge — POST /vasp/v1/qr
{
  "tx_id":           "8f3d2a1b-...",
  "provider_slug":   "guardarian",         // counterparty-провайдер (attribution)
  "amount":          "5000.00",
  "currency":        "KGS",
  "kyc_share_token": "sumsub_token_here"   // passthrough, не расшифровывайте
}

# Ожидаемый ответ
{
  "external_tx_id": "vasp-tx-abc",         // ваш ID — по нему матчатся все webhooks
  "data":           "00020101...",         // данные QR (ELQR формат)
  "image_url":      "https://elqr.kg/pay/...",
  "expires_at":     "2026-04-16T10:25:00Z"
}

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

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

# Входящий запрос от Twin Bridge — POST /vasp/v1/payout
# HTTP-заголовок Idempotency-Key = idempotency_key — дедуплицируйте, НЕ платите дважды
{
  "tx_id":            "8f3d2a1b-...",
  "provider_slug":    "guardarian",
  "idempotency_key":  "550e8400-e29b-41d4-a716-446655440000",
  "kgs_amount":       "4996.00",           // KGS к выплате (за вычетом комиссии)
  "recipient_wallet": "1234567890",        // ELQR-кошелёк/счёт ...
  "recipient_phone":  "996700123456"       // ... либо телефон (одно из двух)
}

# Ожидаемый ответ (async ACCEPTED либо sync EXECUTED)
{ "external_tx_id": "vasp-payout-xyz", "status": "EXECUTED" }

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://twinbridge.kg/internal/webhooks/{your_vasp_slug}
X-Signature:  HMAC_SHA256(secret, "{timestamp}\n{METHOD}\n{path}\nsha256:{body_hash}")
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 не должен отличаться от серверного времени более чем на 300 секунд.

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

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

KYC и комплаенс

Для self_api и we_pull KYC проводит провайдер, а Twin Bridge передаёт kyc_share_token или зашифрованные PII. Для widget KYC проходит через TB-managed Sumsub-ready поток.

Вариант A. KYC passthrough (для self_api / we_pull)

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

Twin Bridge не видит содержимое токена и не расшифровывает его. Только транспортирует. Альтернативно, провайдер может передать 30+ PII-полей (имя, паспорт, адрес, документы) прямо в payload POST /v1/transactions — TB шифрует их AES-256-GCM на 24 часа и передаёт VASP'у.

Вариант B. TB-managed KYC (для widget)

Если провайдер использует наш виджет (например, e-commerce без своего KYC), верификация клиента проводится через наш Sumsub-аккаунт. PII шифруется и хранится у TB в таблице customers. При создании транзакции виджет связывает её с customer_id, а в момент GenerateQR/Payout мы передаём данные VASP'у через тот же интерфейс vasp.KYCData.

В этом режиме TB становится data controller для клиентских PII. Поток уже Sumsub-ready: при заданном SUMSUB_APP_TOKEN включается Sumsub WebSDK, а без ключа используется sandbox-форма для тестирования интеграции. Для production также нужны privacy policy и обновлённое legal opinion.

• Twin Bridge не является VASP и не требует финансовой лицензии
• KYC/AML — ответственность провайдера (при passthrough) или TB (при widget-режиме)
• PII шифруются AES-256-GCM, ключ хранится отдельно от БД
• Все VASP-операторы в экосистеме лицензированы ФСА КР

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

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

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

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

Симулятор

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

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