Нужно автоматически создавать виртуальные карты для клиентов, проектов или бизнес-аккаунтов? API Buvei позволяет разработчикам интегрировать выпуск виртуальных карт в собственные приложения, сокращая объем ручной работы и упрощая масштабирование процесса создания карт.
В этом руководстве описан весь процесс: от подготовки аккаунта и выбора BIN карты до выпуска виртуальной карты и подтверждения ее готовности к использованию.
Что необходимо подготовить перед выпуском виртуальной карты
Перед началом убедитесь, что у вас есть:
- Аккаунт Buvei с включенным доступом к API
- API Key и API Secret
- Статический исходящий IP-адрес, одобренный для доступа к API
- HTTPS-эндпоинт для получения уведомлений Webhook
- Достаточный баланс кошелька для выпуска карты
Если вы еще не знакомы с Buvei, сначала зарегистрируйте аккаунт и изучите панель управления картами, прежде чем приступать к интеграции.
Шаг 1: Зарегистрируйтесь в Buvei и пополните кошелек
Создайте аккаунт Buvei
Перейдите на Buvei.com, создайте аккаунт, подтвердите адрес электронной почты и войдите в панель управления.
Прежде чем продолжить, убедитесь, что для вашего аккаунта доступен API.
Пополните кошелек
Откройте раздел Wallet и выберите способ пополнения, поддерживаемый вашим аккаунтом. Если такая возможность доступна, вы можете внести USDT через сети TRC20 или ERC20.
Скопируйте адрес для пополнения, убедитесь, что сеть перевода совпадает с выбранной сетью, и дождитесь поступления средств. Перед выпуском карты проверьте доступный баланс.
Убедитесь, что на кошельке достаточно средств для первоначального пополнения карты и оплаты применимых комиссий.
Шаг 2: Получите учетные данные API и настройте доступ
Получите API Key и API Secret в разделе настройки API своего аккаунта Buvei.
API Key идентифицирует ваш проект, а API Secret используется для подписания запросов. Храните API Secret в безопасности и никогда не размещайте его в коде frontend или общедоступных репозиториях.
Затем укажите статический исходящий IP-адрес, который ваше приложение использует для подключения к Buvei, чтобы добавить его в список разрешенных. Запросы с неодобренных IP-адресов могут быть отклонены.
Также потребуется HTTPS-эндпоинт для получения уведомлений Webhook. Эти уведомления позволяют вашему приложению реагировать на завершение создания карты.
Шаг 3: Аутентифицируйте запросы и получите список доступных BIN
Прежде чем запрашивать выпуск виртуальной карты, убедитесь, что аутентификация API настроена правильно.
Каждый запрос должен содержать учетные данные API, временную метку, уникальный nonce и действительную подпись. Отсутствие необходимых данных аутентификации или ошибки в них могут привести к отклонению запроса. Поэтому проверьте все эти параметры перед выпуском карты.
Найдите доступный BIN карты
Перед выпуском карты проверьте, какие BIN доступны вашему проекту. Прежде чем выбрать подходящий вариант, изучите платежную систему карты, страну выпуска, валюту и дополнительные требования к держателю карты.
BIN определяет важные характеристики карты, включая платежную систему, страну выпуска и валюту. В доступной информации также указывается, требуются ли дополнительные данные, например номер мобильного телефона, адрес электронной почты, PIN-код, платежный адрес или подтвержденная личность держателя карты.
Выберите BIN, соответствующий предполагаемому сценарию использования, и сохраните его идентификатор для запроса на выпуск карты.
Перед продолжением проверьте требования выбранного BIN. Для разных BIN могут действовать разные требования к проверке, а валюта карты определяется выбранным BIN.
Шаг 4: Проверьте требования к держателю карты
Перед отправкой запроса на выпуск карты изучите требования выбранного BIN.
Для некоторых BIN требуется проверка личности держателя карты, тогда как другие могут предусматривать предоставление определенных контактных данных или платежной информации. Если требуется KYC, пройдите соответствующую процедуру проверки и убедитесь, что держатель карты получил одобрение.
В зависимости от BIN вам также может потребоваться указать номер мобильного телефона, адрес электронной почты, PIN-код или платежный адрес.
Подготовка этих данных заранее помогает избежать ошибок при отправке запросов. Не предполагайте, что требования для всех виртуальных карт одинаковы.
Шаг 5: Выпустите виртуальную карту через API Buvei
После выбора подходящего BIN и подготовки необходимых данных можно приступать к выпуску карты. Перед отправкой запроса убедитесь, что все обязательные сведения о держателе заполнены, а на кошельке достаточно средств.
Запрос должен содержать выбранный BIN карты, сумму первоначального пополнения и необходимые данные держателя. В зависимости от BIN может потребоваться дополнительная информация. Если необходима проверка держателя карты, убедитесь, что соответствующий пользователь прошел ее и получил одобрение.
Проверьте сумму первоначального пополнения
Сумму первоначального пополнения необходимо передавать в минимальных единицах валюты. Например, значение 10 000 соответствует 100,00 доллара США.
Согласно документации, допустимый диапазон составляет от 1,00 до 40 000,00 доллара США. Доступные варианты также могут зависеть от вашего аккаунта и выбранного BIN, поэтому перед отправкой запроса уточните применимые требования.
После отправки API возвращает идентификатор карты и ее первоначальный статус. Создание карты выполняется асинхронно, поэтому успешный запрос не обязательно означает, что карта уже готова к использованию.
Избегайте дублирования выпуска карт
Если время ожидания запроса истекло, не отправляйте сразу совершенно новый запрос на выпуск карты.
Если такая возможность поддерживается, ключ идемпотентности помогает распознать одну и ту же операцию выпуска при повторных попытках и снижает риск создания дублирующих карт. Для повторной отправки того же запроса используйте прежний ключ, соблюдая требования Buvei к аутентификации.
Если запрос возвращает конфликт, прежде чем повторять попытку, проверьте, была ли обработана исходная операция.
Шаг 6: Подтвердите создание карты с помощью Webhook
После отправки запроса на выпуск дождитесь уведомления Webhook CARD_CREATED от Buvei.
Новая карта может первоначально оставаться в статусе ожидания создания, пока продолжается процесс ее подготовки. После отправки Buvei события CARD_CREATED процесс выпуска карты считается завершенным.
Ваше приложение должно проверить подпись Webhook, подтвердить тип события, определить соответствующую карту и обновить внутренние записи. Также необходимо предусмотреть обработку повторных уведомлений и временных сбоев доставки.
После получения уведомления проверьте текущий статус карты через сервис получения сведений о картах Buvei и убедитесь, что она активирована, прежде чем считать ее готовой к использованию.
Шаг 7: Устраните распространенные ошибки API Buvei
Если выпуск карты завершился ошибкой, проверьте возвращенное сообщение об ошибке и рассмотрите следующие распространенные проблемы.
| Проблема | Что проверить |
|---|---|
| Некорректный запрос | Обязательные данные, требования BIN, сумму пополнения и платежный адрес |
| Ошибка аутентификации | Учетные данные API, временную метку, nonce и подпись запроса |
| Доступ запрещен | Список разрешенных IP-адресов и права доступа аккаунта |
| Конфликт запроса | Повторно использованный nonce или ключ идемпотентности, связанный с другими параметрами запроса |
| Превышен лимит запросов | Ограничения использования API и интервалы между повторными попытками |
| Создание карты задерживается | Доставку Webhook и текущий статус карты |
Если запрос некорректен, проверьте обязательные данные и подробности ошибки, чтобы определить, что необходимо исправить. При проблемах с аутентификацией или доступом проверьте процесс подписания запросов, временную метку, настройки IP-адреса и права доступа аккаунта.
Если время ожидания запроса истекло или он вернул конфликт, выясните, была ли обработана первоначальная заявка на выпуск карты, прежде чем отправлять новую. Это поможет избежать создания дублирующих карт.
Если создание карты задерживается, проверьте, поступил ли Webhook, и изучите текущий статус карты. Само по себе задержанное уведомление не означает, что выпуск карты завершился неудачей.
Заключение
API Buvei позволяет интегрировать выпуск виртуальных карт непосредственно в существующие бизнес-процессы. Выбирая подходящий BIN, подготавливая необходимые данные держателя и проверяя окончательный статус каждой карты, разработчики могут сделать процесс выпуска более последовательным и удобным для управления.
После правильной настройки интеграции автоматическое создание карт и уведомления Webhook помогут командам справляться с растущей потребностью в картах, сокращая объем ручной работы.
