Список необходимой информации для начала интеграции

​

Этап 1: Настройка среды, условия интеграции и предоставление доступов

​

Предоставление API-документации со стороны партнера Holders

1. Предоставляемая вами документация должна содержать подробное описание всех ресурсов, эндпоинтов, включая URL, HTTP-методы, заголовки, параметры запросов и форматы ответов (JSON).
2. Необходимо предоставить примеры полного процесса оплаты и возврата в виде реальных webhook-примеров по транзакциям, включая clearing, для следующих процессов:
   1. decision_request and notification (with all types)
      1. online payments
      2. offline payments
      3. contactless payments
      4. full reversal
      5. partial reversal
      6. refund
      7. multiple authorizations (if applicable)
   2. clearing
      1. full clearing
      2. partial clearing (if available)
      3. multi-clearing (if available)
   3. decline (with all types)
      1. after decision_request
      2. as notification
3. Нужно предоставить подробную информацию о методах обработки транзакций для всех типов операций.
4. Нужен детальный обзор всех доступных эндпоинтов, покрывающих полный жизненный цикл карты: выпуск, активацию, блокировку, просмотр данных, управление пользователями, проверку баланса, получение истории транзакций, а также эндпоинты для дополнительных сервисов. Для ориентира используйте methods checklist для партнера.
5. Предоставьте полный список возможных кодов ошибок, их значения и рекомендуемые действия при их возникновении. Также укажите информацию о версии API.

​

Предоставление стабильного доступа к окружениям

Предоставьте рабочие учетные данные доступа, включая API-ключи и URL эндпоинтов, для изолированного Sandbox API-окружения.

• Критерии оценки тестового окружения:
  • Возможность пройти полный KYC-процесс для клиента максимально близко к production-сценарию
  • Выпуск карты
  • Получение карточных данных
  • Возможность тестировать транзакции и webhook-и
• Четко опишите процедуру получения доступа к Production API и предоставьте отдельный доступ в это окружение. Укажите все различия в конфигурации или поведении между Production и Sandbox.

​

Согласование, утверждение и кастомизация дизайна карты

• Опишите внутренний процесс согласования и утверждения дизайнов банковских карт у партнера, включая требования к форматам файлов, дизайн-элементам и срокам ревью.
• Согласуйте финальный макет, включая расположение логотипов, обязательного текста, например условий использования и контактов банка-эмитента, а также прочих элементов.
• Подтвердите получение дизайна карты, подготовленного командой Holders в формате SVG, и его техническую пригодность к использованию. Формат SVG нужен для качественной печати и масштабирования изображения. Если требуется, согласуйте другой формат, приемлемый для партнера.
• Зафиксируйте понятные и реалистичные сроки технической реализации утвержденного дизайна карты в системах партнера и его отображения в интерфейсах, например через iframe. Укажите нужные форматы и способы передачи финальных дизайн-файлов.

​

Кастомизация и отображение детальных карточных данных

• Предоставьте подробную техническую информацию по реализации iframe или других безопасных способов отображения чувствительных данных карты: полного номера карты, CVV и срока действия. Добавьте примеры встраивания и описание передаваемых параметров. Важно: наш уровень PCI DSS соответствует SAQ, полной PCI DSS-compliance у нас нет.
• Уточните, какие минимальные возможности кастомизации внешнего вида iframe доступны, если это применимо: передача параметров фона, шрифтов, наличие CSS-классов для переопределения стилей, чтобы внешний вид был максимально близок к дизайну приложения Holders.
• Опишите меры безопасности, реализованные в iframe для предотвращения несанкционированного доступа к карточным данным.

​

Валюты и расчеты

Предоставьте следующую информацию:

• Укажите валюту счета в вашей системе
• Перечислите поддерживаемые валюты для платежей
• Опишите, какие данные содержатся в транзакции:
  • Сумма в валюте транзакции
  • Сумма в валюте счета
  • Можно ли показывать сумму транзакции в USDT/USDC вместе с фиатной суммой
• Уточните, каким должен быть settlement-баланс и в какой валюте он ведется
• В какой валюте будут приниматься платежи
• Опишите процесс оплаты услуг партнера, то есть settlement-расчеты с Holders

​

Поддержка 3DS

• Какие типы 3DS поддерживаются:
  • Кнопка подтверждения в приложении
  • SMS от партнера
  • Webhook от партнера в Holders, чтобы Holders мог управлять процессом отправки сообщений
• Требуется ли 3DS-пароль
• Кто отправляет SMS
• В какие моменты SMS отправляет партнер, а в какие Holders:
  • Например, при добавлении карт в Apple Pay или Google Pay партнер может отправлять SMS независимо от остальных настроек.

​

Дизайн карты для Apple Pay и Google Pay

Если это требуется, уточните, нужен ли отдельный дизайн карты для отображения в Apple Pay и Google Pay.

​

Требования к KYC

Соберите требования к перечню обязательных документов в зависимости от региона.
Опросник:

• Как передаются данные на сторону партнера, возможные варианты:
  • API: отправка документов и полного набора клиентских данных
  • Sumsub share token
  • Упрощенная верификация, например только адрес
  • Только Holders проводит проверку клиента, дополнительная верификация не требуется, а партнер может провести ее по запросу на основе документов, предоставленных клиентом.
• Предоставьте список стран и соответствующий перечень обязательных документов с подробным описанием. Нужен ли proof of address и какие требования предъявляются к документам:
  • Требования к номеру документа
  • Соответствие документа, подтверждающего адрес, удостоверению личности
  • Требования к адресу
  • Нужно ли дополнительно запрашивать номера документов через форму ввода данных помимо загрузки основных документов

​

Этап 2: Договорные и юридические аспекты

На этом этапе должны быть окончательно согласованы и юридически оформлены все коммерческие, операционные и правовые аспекты сотрудничества.

​

Финализация и подписание договора

• Внимательно изучите и прокомментируйте предложенный Holders Term Sheet, который фиксирует ключевые коммерческие и операционные условия сотрудничества. Term Sheet служит основой для финального договора.
• Согласуйте и окончательно определите все ключевые коммерческие условия, включая:
  • Полный процесс обмена денежных средств, а при необходимости и криптовалюты: включены ли комиссии, кто выполняет обмен, партнер или Holders, и какую биржу можно использовать в регионе, если обмен выполняем мы.
  • Размер ежемесячной подписки и условия льготного периода на старте проекта.
  • Стоимость выпуска каждой виртуальной и или физической карты.
  • Размер и условия комиссий за транзакции, обработку chargeback-ов и refund-ов, если применимо.
  • Тарифы и условия по дополнительным платежным сервисам: ACH, RTP, Push to Card, Venmo, PayPal, включая возможные минимальные объемы или дополнительные затраты на подключение.
  • Подробные условия эксклюзивности: география, срок, конкретные сервисы.
  • Условия оплаты инвойсов и валюта settlement-расчетов.

На основе согласованного Term Sheet подготовьте финальный текст основного договора. Особое внимание уделите ясности формулировок в разделах о зонах ответственности сторон, порядке урегулирования споров, условиях расторжения и ограничениях ответственности.

• Организуйте подписание финального договора уполномоченными представителями обеих компаний.

​

Предоставление и согласование пользовательских соглашений

• Предоставьте полные и актуальные тексты основных Terms of Service эмитента, а также собственных Terms of Service партнера, если они существуют и применяются к конечным пользователям Holders.
• Подтвердите, что предоставленные тексты являются финальными и могут быть встроены в onboarding пользователей Holders.
• Уточните, есть ли у партнера особые требования к отображению и акцепту этих документов пользователями в приложении Holders, например необходимость отдельных чекбоксов для каждого документа.

​

Подтверждение и детализация зон ответственности

• Формально подтвердите, что партнер полностью отвечает за соблюдение всех применимых регуляторных требований, как федеральных, так и локальных, а также правил банка-эмитента карт.
• Подробно опишите процесс взаимодействия по AML/KYC-процедурам. Подтвердите, что партнер выполняет финальную проверку и принимает решения по клиенту, получая при этом необходимые данные от Holders. Опишите формат и протокол передачи KYC-данных. Либо обсудите и зафиксируйте альтернативную модель.
• Уточните процедуры взаимодействия с банком-эмитентом и регуляторами в случае запросов или инцидентов, связанных с пользователями Holders.

​

Для партнеров, предоставляющих юридическое лицо

​

Предоставление безопасного доступа к инфраструктурным сервисам

Предоставьте административный доступ к следующим облачным сервисам и аккаунтам, зарегистрированным на юридическое лицо партнера. Передача доступов должна выполняться с использованием GPG encryption; публичный GPG-ключ предоставит команда Holders:

• Amazon Web Services (AWS): нужен для развертывания основной инфраструктуры Holders, включая Kubernetes, базы данных, очереди и другие сервисы.
• Cloudflare: используется для управления DNS, CDN и защиты веб-приложения. Понадобится доступ к домену, на котором будут запускаться сервисы Holders.
• Temporal.io: необходим для управления сложными workflow-процессами; на старте достаточно плана Essentials. Нужны корпоративные Google- или Microsoft-аккаунты. AWS Temporal не подходит.
• GitHub: нужен для совместной работы над инфраструктурным кодом и конфигурациями, то есть доступ к организации или репозиториям для корпоративного аккаунта.
• Grafana Cloud: нужен для настройки мониторинга и сбора метрик производительности сервисов.

Важное замечание по безопасности: при настройке и администрировании этих сервисов командой Holders доступ к указанным системам, особенно AWS, должен выполняться с отдельной защищенной рабочей станции, например Mac mini или выделенного Windows-сервера, расположенного на площадке юридического лица и имеющего статический IP-адрес. Это необходимо, чтобы минимизировать риск блокировок со стороны облачных провайдеров из-за подозрительной активности или нетипичных IP-адресов.

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

​

Этап 3: Настройка сервиса, функциональность и поддержка

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

​

Подтверждение полного списка доступных сервисов и тарифов

• Предоставьте полный перечень всех сервисов, доступных Holders через API партнера, включая не только выпуск карт, но и все доступные способы платежей и переводов: ACH, Check, RTP, Push to Card, Prepaid Visa, Venmo, PayPal.
• Предоставьте финальные и актуальные тарифы для каждого подтвержденного сервиса. Если стоимость зависит от объемов транзакций, приложите соответствующую тарифную сетку. Укажите наличие минимальных комиссий или скрытых сборов, если они есть.
• Подтвердите отсутствие дополнительных платежей за активацию перечисленных сервисов.

​

Уточнение и документирование деталей обработки транзакций

• Финально подтвердите наличие или отсутствие механизма Webhooks для асинхронного уведомления системы Holders об изменениях статусов транзакций, например успешной авторизации, подтверждении settlement, реверсале авторизации или refund.
• Если Webhooks отсутствуют, дайте четкие рекомендации по polling-механизму API: рекомендуемая частота запросов, конкретные эндпоинты для проверки статуса, параметры фильтрации транзакций и способы выявления изменений.
• Подробно опишите действующий процесс обработки валютных, то есть FX, транзакций.
• Предоставьте полное описание всех возможных статусов транзакций в системе партнера и опишите типовой жизненный цикл транзакции от авторизации до финального settlement или отмены и возврата. Уточните, как эти статусы отражаются в API-ответах или в данных polling-запросов.

​

Уточнение функциональности карты и лимитов

• Укажите точные лимиты на операции снятия и списания: максимальная сумма на одну операцию, дневной лимит и месячный лимит. Уточните связанные комиссии.
• Официально подтвердите текущую географию использования карт. Укажите, планируется ли расширение регионов в будущем, и опишите roadmap, если он существует.
  • Список стран, резидентов которых Holders может онбордить
  • Список стран, в которых пользователи Holders могут проводить транзакции
  • Есть ли требование, чтобы номер телефона соответствовал стране выпуска карты
  • Существует ли список стран или телефонных кодов, на которые нельзя отправлять 3DS-коды, либо где требуются отдельные соглашения с локальными операторами

​

Сверки

• По процессу reconciliation предоставьте примеры документов и их форматов, используемых для сверки. Например:
  • еженедельный отчет по транзакциям
  • ежемесячный инвойс-отчет со всеми расходами, выставленными нам, с разбивкой по категориям

​

Организация процесса поддержки

• Предоставьте понятные контактные данные для связи с L2-поддержкой по техническим и операционным вопросам платформы партнера: email, телефон, support-портал.
• Подробно опишите процесс регистрации и обработки обращений от команды Holders.
• Подтвердите согласованный SLA, включая гарантированное время первого ответа, например в течение 4 рабочих часов, и целевое время решения инцидентов разной критичности, например критические за 8 часов, стандартные за 24 часа.
• Опишите процесс эскалации внутри службы поддержки партнера, если проблема не была решена на уровне L2 в целевой срок.

​

Настройка контроллера, запуск и пополнения

Если используется юридическое лицо партнера, предполагается, что именно партнер пополняет сервисные кошельки. В зависимости от опыта партнера можно рекомендовать способы обмена в нужную валюту, а также примерные суммы в долларах, которые следует обменять по текущему курсу.
TON

• TON Deploy — 2 TON, только для деплоя
• TON Authority — 2 TON, для более чем 100 возвратов и выводов из treasury

После того как команда технической интеграции, либо другой владелец скрипта, который создает кошельки с окончаниями TON и USDT и выдает нужные доступы, сгенерирует адрес:

• 50–100 TON для создания пользовательских smart contract accounts и обновления их состояния

Solana

• Solana Authority — 0.0005 SOL, для 100 возвратов и выводов из treasury
• Solana Controller — 2 SOL, для создания примерно 250 пользовательских smart contract accounts и обновления их состояния

Необходимо отправлять инструкции в формате:

• Wallet — сумма в валюте

Общая сумма в валюте должна учитывать и gas, который потребуется оплатить за переводы.