Потрібно автоматично створювати віртуальні картки для клієнтів, проєктів або бізнес-акаунтів? 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 у безпеці та ніколи не розміщуйте його у фронтенд-коді або загальнодоступних репозиторіях.
Далі надайте статичну вихідну 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 допоможуть командам обслуговувати дедалі більшу кількість карток із меншими витратами ручної праці.
