Finance OS / API

B2B API — Introduction

B2B API позволяет партнёрам Finance OS управлять своими конечными пользователями через единый набор endpoints: создавать managed-customers, проводить им KYC-верификацию, инициировать платежи и подписываться на webhook-события.

⚠
Регуляторное предусловие
B2B-режим — не self-service. Он включается только после подписания договора с Finance OS (агентская модель + соглашение об обработке данных). До этого момента API-ключи получают 403 B2B_ACCESS_REQUIRED на любой /api/v1/customers/* endpoint. Свяжитесь с admin@fin-os.io, чтобы инициировать процесс.

Что входит в B2B

  • Customers — managed end-users партнёра (UUID-идентификация, опционально привязка к partner-side external_id).
  • KYC verification — полный flow: загрузка документов, верификация телефона, статусы, partner-attestation для consent.
  • Payments — buy (RUB → USDT через СБП), sell (USDT → RUB через СБП), crypto deposit/withdraw, баланс per-customer.
  • Webhooks — партнёрские endpoint'ы для асинхронных событий (KYC-результаты, статус платежей), HMAC-подписанные.
  • Sandbox — изолированное окружение для разработки и тестирования. sk_test_* ключи никогда не вызывают апстрим.

Модель доступа

B2B endpoints проверяют стек middleware в таком порядке:

  1. API Key auth — обычная аутентификация через Authorization: Bearer sk_(live|test)_xxx. См. Authentication.
  2. B2B gate — проверка флага users.b2b_enabled = true на учётке владельца ключа. Включается админом Finance OS вручную после договора.
  3. Environment isolation — sk_test_ ключ видит только env='sandbox' customers, sk_live_ — только env='live'. Попытка cross-env → 404 (намеренно, не 403: чтобы не утечь существование).

Сквозной пример интеграции

Шаги для полной интеграции нового партнёра:

  1. Партнёр регистрируется на fin-os.io, проходит свой собственный KYC.
  2. Партнёр и Finance OS подписывают B2B-договор, флаг b2b_enabled поднимается админом.
  3. Партнёр генерирует sk_live_ и sk_test_ ключи в Личном Кабинете → API ключи.
  4. Партнёр подписывает webhook-endpoint через POST /api/v1/webhooks и сохраняет полученный одноразовый секрет.
  5. Для каждого своего end-user'а:
    1. Партнёр собирает консент end-user'а на обработку его данных в Finance OS.
    2. POST /api/v1/customers — создать managed-customer.
    3. POST /api/v1/customers/{uuid}/consent — зафиксировать факт получения консента (IP + timestamp).
    4. Провести KYC-flow для customer.
    5. После kyc_status='verified' — платежи разрешены.

Логика данных

Finance OS — это прокси-фасад поверх внутренних провайдеров (платежи, KYC). Партнёр взаимодействует только с Finance OS API; внутренняя инфраструктура провайдеров скрыта.

  • Customer state хранится у Finance OS: kyc_status, kyc_level, балансы.
  • Документы KYC хранятся у Finance OS, переадресуются провайдеру для верификации.
  • Платежи (СБП) идут через расчётный счёт Finance OS; Finance OS внутренне маркирует операцию customer'ом и обновляет баланс customer'а.
  • Webhook delivery — Finance OS подписывает HMAC и пушит на партнёрский URL с retry-логикой.

Что дальше

  • Managed Customers — модель данных, CRUD endpoints, consent flow
  • KYC Verification — полный flow с примерами
  • Payments — buy/sell/deposit/withdraw
  • Webhooks — подписка и HMAC-верификация
  • Sandbox — тестирование без реальных операций