この記事では、アカウントの準備やカードBINの選択から、バーチャルカードの発行、利用可能な状態になったことの確認まで、一連の手順を詳しく解説します。
バーチャルカードを発行する前に必要なもの
作業を始める前に、以下のものを準備してください。
- APIアクセスが有効になっているBuveiアカウント
- API KeyとAPI Secret
- APIアクセス用に承認された固定の送信元IPアドレス
- Webhook通知を受信するためのHTTPSエンドポイント
- 発行するカードに必要な十分なウォレット残高
Buveiを初めて利用する場合は、アカウントを登録し、カード管理ダッシュボードの操作に慣れてからAPI連携を始めましょう。
ステップ1：Buveiに登録してウォレットに入金する
Buveiアカウントを作成する
Buvei.com にアクセスし、アカウントを作成してメールアドレスを認証した後、ダッシュボードにログインします。
次の手順に進む前に、ご利用のアカウントでAPIアクセスが利用可能になっていることを確認してください。
ウォレットにチャージする
Walletセクションを開き、ご利用のアカウントでサポートされている入金方法を選択します。利用可能な場合は、TRC20またはERC20ネットワークを通じてUSDTを入金できます。
入金アドレスをコピーし、送金ネットワークが選択したネットワークと一致していることを確認してから、資金の反映を待ちます。カードを発行する前に、利用可能残高を確認してください。
ウォレット残高がカードの初期チャージ額と適用される手数料をカバーできることを確認しましょう。
ステップ2：API認証情報を取得してアクセスを設定する
BuveiアカウントのAPI設定画面から、API KeyとAPI Secretを取得します。
API Keyはプロジェクトを識別するために使用され、API Secretはリクエストへの署名に使用されます。API Secretは安全に管理し、フロントエンドのコードや公開リポジトリに絶対に含めないでください。
次に、アプリケーションがBuveiへの接続に使用する固定の送信元IPアドレスを登録し、許可リストへの追加を依頼します。承認されていないIPアドレスからのリクエストは拒否される場合があります。
また、Webhook通知を受信するためのHTTPSエンドポイントも必要です。これらの通知を利用することで、カードの作成が完了した際にアプリケーション側で処理を実行できます。
ステップ3：リクエストを認証して利用可能なBINを取得する
バーチャルカードをリクエストする前に、API認証が正しく設定されていることを確認してください。
各リクエストには、API認証情報、タイムスタンプ、一意のnonce、有効な署名を含める必要があります。認証情報が不足していたり、正しくなかったりすると、リクエストが拒否される可能性があります。そのため、カード発行を進める前にこれらの情報を確認しましょう。
利用可能なカードBINを確認する
カードを発行する前に、プロジェクトで利用できるBINを確認してください。最適なものを選ぶために、それぞれのカードブランド、発行国、通貨、カード保有者に関する追加要件を確認します。
BINは、カードブランド、発行国、通貨など、カードの重要な特性を決定します。また、携帯電話番号、メールアドレス、PIN、請求先住所、本人確認済みのカード保有者など、追加情報が必要かどうかも、提供されている情報から確認できます。
利用目的に合ったBINを選択し、カード発行リクエストに使用する識別子を控えておきましょう。
次に進む前に、選択したBINの要件を確認してください。 BINによって認証要件が異なる場合があり、カードの通貨は選択したBINによって決まります。
ステップ4：カード保有者の要件を確認する
カード発行リクエストを送信する前に、選択したBINの要件を確認してください。
BINによってはカード保有者の本人確認が必要な場合があり、別のBINでは特定の連絡先情報や請求情報が求められることがあります。KYCが必要な場合は、該当する本人確認手続きを完了し、カード保有者が承認されていることを確認してください。
BINによっては、携帯電話番号、メールアドレス、PIN、請求先住所の入力も必要になります。
これらの情報を事前に準備しておくことで、回避可能なリクエストエラーを防ぎやすくなります。すべてのバーチャルカードで要件が同じだと考えないようにしましょう。
ステップ5：Buvei API を通じてバーチャルカードを発行する
適切なBINを選択し、必要な情報を準備したら、カードの発行に進みます。リクエストを送信する前に、カード保有者に関する必須情報がすべて入力されており、ウォレットに十分な残高があることを確認してください。
リクエストには、選択したカードBIN、初期チャージ額、必要なカード保有者情報を含める必要があります。BINによっては追加情報が必要になる場合があります。カード保有者の本人確認が必要な場合は、該当するカード保有者が承認されていることを確認してから進めてください。
初期チャージ額を確認する
初期チャージ額は、通貨の最小単位で送信する必要があります。例えば、10,000という金額は100.00米ドルを表します。
ドキュメントに記載されている範囲は、1.00米ドルから40,000.00米ドルです。利用可能な金額はアカウントや選択したBINによっても異なる場合があるため、リクエストを送信する前に該当する要件を確認してください。
送信後、APIからカード識別子と初期ステータスが返されます。カードの作成は非同期で行われるため、リクエストが成功しても、必ずしもカードがすぐに利用可能になるわけではありません。
カード発行 の重複を防ぐ
リクエストがタイムアウトした場合、すぐにまったく新しい発行リクエストを送信しないでください。
対応している場合、冪等性キー（Idempotency Key）を使用すると、再試行時に同じ発行操作であることを識別でき、カードが重複して作成されるリスクを軽減できます。Buveiの認証要件に従い、同じリクエストには同じキーを再利用してください。
リクエストが競合エラーを返した場合は、再試行する前に、最初の操作が処理されたかどうかを確認しましょう。
ステップ6：Webhookでカードの作成を確認する
発行リクエストを送信した後、Buveiからの CARD_CREATED Webhook通知を待ちます。
新しくリクエストされたカードは、プロビジョニングが進行している間、最初は作成待ちの状態になる場合があります。BuveiからCARD_CREATEDイベントが送信されると、プロビジョニングプロセスは完了しています。
アプリケーション側では、Webhookの署名を検証し、イベントの種類を確認して、該当するカードを特定したうえで内部記録を更新する必要があります。また、通知の重複や一時的な配信エラーにも対応できるようにしてください。
通知を受信したら、Buveiのカード詳細サービスを通じてカードの現在のステータスを確認し、有効化されていることを確かめてから利用可能と判断しましょう。
ステップ7：Buvei APIでよくあるエラーを解決する
カードの発行に失敗した場合は、返されたエラーメッセージを確認し、以下のよくある問題をチェックしてください。
| 問題 | 確認する項目 |
|---|---|
| リクエストが無効 | 必須情報、BINの要件、チャージ額、請求先住所 |
| 認証エラー | API認証情報、タイムスタンプ、nonce、リクエスト署名 |
| アクセス拒否 | IP許可リスト、アカウントのアクセス権限 |
| リクエストの競合 | nonceの再利用、または異なるリクエスト内容に関連付けられた冪等性キー |
| レート制限超過 | APIの利用制限、再試行のタイミング |
| カード作成の遅延 | Webhookの配信状況、カードの現在のステータス |
リクエストが無効な場合は、必須情報とエラーの詳細を確認し、修正が必要な箇所を特定してください。認証やアクセスに関する問題であれば、署名の生成処理、タイムスタンプ、IP設定、アカウントのアクセス権限を確認しましょう。
リクエストがタイムアウトした場合や競合エラーを返した場合は、別のリクエストを送信する前に、最初の発行リクエストが処理されたかどうかを確認してください。これにより、カードの重複発行を防ぎやすくなります。
カードの作成が遅れているように見える場合は、Webhookが届いているかどうかを確認し、カードの現在のステータスを調べてください。通知が遅れているだけで、カードの発行に失敗したとは限りません。
まとめ
Buvei APIを利用すると、既存のビジネスワークフローにバーチャルカードの発行機能を直接統合できます。適切なBINを選び、必要なカード保有者情報を準備し、各カードの最終ステータスを確認することで、開発者はより一貫性があり、管理しやすい発行プロセスを構築できます。
API連携を適切に設定すれば、カードの自動発行とWebhook通知によって、手作業を減らしながら、増加するカード発行ニーズに対応しやすくなります。
