決済APIキーは、PINのない現金カードのような働きをします。キーを送信した者は、請求書を作成し、決済データを読み取り、ペイアウトを利用している場合は残高から資金を引き出すことができます。したがって、決済APIのセキュリティは3つの習慣に集約されます。キーを自社サーバー上に保管すること、APIがそのサーバーのアドレスからのリクエストのみを受け付けるようにすること、そしてWebhookを受けて行動する前に、決済内容を照会して確認することです。
本ガイドは、ユーロで決済を行う暗号資産決済APIを接続しているPSP、EMI、銀行、加盟店のエンジニアリング責任者および決済部門責任者を対象としています。キーをIPアドレスおよびCIDR範囲で制限する方法、キーの保管場所、Webhookの確認方法、ペイアウトの周辺に設けるべき管理策を説明します。例はItisPayのAPIおよびダッシュボード（デモデータ）を使用しています。
主なポイント
要点
- APIキーは権限の証明となる資格情報（ベアラークレデンシャル）です。GitGuardianは2025年に公開GitHubのコミットで新たに2865万件のハードコードされたシークレットを確認しました。そのため、キーを安全に保つことだけでなく、キーが漏えいする事態を想定して備えてください。
- IP許可リストがあれば、漏えいしたキーもネットワーク外では使えなくなります。実際の送信元アドレスを網羅する、必要最小限のIPv4またはIPv6範囲を登録してください。リストが空の場合は、すべてのアドレスが許可されます。
- Webhookは通知であり、証明ではありません。出荷または口座入金の前に、キーを使ってIDで請求書を読み直してください。
- ペイアウトには、自社側での人的管理が必要です。2段階認証、登録済みの受取人のIBANおよびウォレット、一定額を超える場合の2人目の承認者を設けてください。
決済APIキーが漏えいすると、なぜ危険なのですか？#
決済APIキーは連携先の身元そのものであるため、漏えいすると危険です。ItisPay APIを含む多くの決済APIと同様に、各リクエストは1つのヘッダー（Api-key）で認証され、同じ認証で請求書の作成、IBANまたはウォレットへのペイアウト、外部アドレスへの暗号資産出金がすべて可能になります。そのため、ドキュメントではキーを「クライアント側のコードや公開リポジトリに露出させないこと」を求めています。
実際には、キーはコード、ログ、チャットといった日常的な場所から漏えいします。GitGuardianの「State of Secrets Sprawl 2026」（2026年3月）によると、2025年に公開GitHubのコミットに新たに追加されたハードコード済みシークレットは2865万件で、前年比34%増となりました。GitGuardianが2022年に漏えいしたシークレットを再検証したところ、2026年1月時点で64%超が依然として有効でした。チームはキーを公開したまま、交換を忘れてしまうのです。
OWASP API Security Top 10（2023年版）は「Broken Authentication（認証の不備）」を2位に挙げ、「認証の仕組みは誰にでも露出しているため、攻撃者にとって狙いやすい標的となる」と警告しています。Verizonの2025 Data Breach Investigations Reportは、認証情報の悪用を最も多い初期攻撃経路とし、その割合は22%としています。シークレット文字列だけでは防御は脆弱なので、本ガイドの残りでは、文字列が流出した後も機能する層を追加します。
IP許可リストはAPIキーをどのように保護しますか？#
IP許可リスト（IPホワイトリストとも呼ばれます）は、キーを文字列だけでなく場所にも結び付けることで保護します。APIは、登録したアドレスからのリクエストの場合にのみキーを受け付けます。開発者のノートPCに置かれたキーのコピー、CIのログ、貼り付けサイトに残ったキーは機能しません。
ItisPayのダッシュボードでは、この設定は「Projects」、「Settings」、「Security」の順に進み、「API Allowed IPs」欄にあります。この欄には、単一アドレスとCIDRブロックをカンマ区切りで入力します。ヘルプテキストには「すべてのIPを許可するには空欄のままにしてください。IPv4とIPv6の両方に対応しています。」とあります。同じリストは、プロジェクト作成時にAPIのapi_allowed_ipsフィールドで設定することもできます。256.256.256.256のような無効なエントリは保存されず、検証エラーで拒否されます。
空のデフォルト値が重要です。新規プロジェクトは、誰かが欄に入力するまで、どこからのキーでも受け付けます。そのため、この手順は後で整えればよい項目ではなく、本番公開前のチェックリストに入れてください。スクリーンショットのデモ値である203.0.113.10と198.51.100.0/24は、RFC 5737がドキュメント用に予約した範囲から取られたものです。実際のリストには、自社の公開アドレスを入力します。各プロジェクトには独自の64文字のキーと独自のリストがあるため、本番環境は2〜3台のサーバーのみに制限し、テスト用プロジェクトはより広い範囲を許可することができます。
IPv4とIPv6のCIDR範囲はどのように記述しますか？#
APIへの接続にサーバーが実際に使用するすべてのアドレスを網羅する、最小の範囲を記述してください。許可リストのトラブルの多くは、範囲が広すぎること、または誰かが見落とした送信経路に起因します。
プレフィックスの読み方#
CIDRブロックは、アドレスの後にスラッシュとプレフィックス長を付けたものです。RFC 4632は、プレフィックス長を有効ビット数と定義しています。192.168.99.0/24は先頭24ビットを固定し、残り8ビットが自由となるため、256個のアドレスになります。プレフィックスから1ビット減らすごとにブロックの大きさは2倍になります。/32はIPv4アドレス1つ、/29は8個、/24は256個、/16は65,536個です。
IPv6も128ビットで同様に機能します。/128はアドレス1つです。RFC 4291は、ほとんどのIPv6アドレスのインターフェース部を64ビットと定めているため、サーバーのネットワークは通常/64となり、OSが一時アドレスを生成する場合などに、そのネットワーク内でホストのアドレスが変わることがあります。ホストのIPv6アドレスが変わり、その/64が自社専用である場合は、単一の/128ではなく/64を登録してください。IPv6の例に使うドキュメント用範囲は2001:db8::/32（RFC 3849）なので、実際の許可リストには絶対にコピーしないでください。
実際の送信元アドレスの確認#
重要なのは、サーバーが自身について報告するアドレスではなく、APIが認識するアドレスです。クラウドのNATゲートウェイや企業のファイアウォールの背後では、多くのマシンが1つか2つの公開アドレスを共有しています。サーバーレス関数も、固定の出口経由に設定しない限り、共有プールから送信されることが多いです。各環境から「自分のIPは何か」を返すサービスを呼び出すか、ファイアウォールのログで送信元アドレスを確認し、そのアドレスを正確に登録してください。
| 構成 | 登録する内容 | 判定 |
|---|---|---|
| 固定のパブリックIPv4アドレスを持つサーバー1台 | そのアドレスを /32 付き、または単独で | 動作する |
| クラウドのNAT（ネットワークアドレス変換）ゲートウェイの背後にある複数のサーバー | NATゲートウェイのパブリックアドレス | 動作する |
| アドレスが変わるIPv6ホスト | ホストの /64。他に利用者がいない場合 | 条件による |
| 手動テスト用のオフィスネットワーク | プロバイダーが保証している場合のオフィスの固定アドレス | 条件による |
| 固定の出口を持たないサーバーレス関数 | まず固定アドレスを持つNATを経由させる | 不可 |
| クラウドプロバイダーのリージョン全体のレンジ | 何も登録しない。他の顧客も含まれるため | 不可 |
変更を保存する前に、まず新しいアドレスを追加し、デプロイして、トラフィックが流れていることを確認してから、古いアドレスを削除してください。稼働中のサーバーを一覧から漏らしたまま保存すると、自社のチェックアウトがブロックされます。
APIキーはどこに置き、誰が見られるのか?#
キーは自社のサーバー上のシークレットストアに保管すべきで、それ以外の場所に置いてはいけません。ブラウザのページやモバイルアプリに組み込むと誰でも読み取れてしまうため、決して配布しないでください。URLに含めることも避けてください。OWASP（Open Worldwide Application Security Project）のREST Security Cheat Sheetは、URL内のキーがWebサーバーのログに記録され得ると警告しています。チェックアウトページは自社のバックエンドと通信し、バックエンドがペイメントAPIと通信する構成にしてください。
キーはシークレットマネージャーまたは環境変数から起動時に読み込み、リポジトリ内の設定ファイルには書かないでください。コードをGitHubでホストしている場合は、プッシュ保護を有効にしてください。GitHubのドキュメントによると、「プッシュの試行中に潜在的なシークレットを検出した場合、そのプッシュをブロックします」とのことです。
環境ごとにキーを1つずつ用意してください。ItisPayのプロジェクトごとに、それぞれ固有のキーと許可リストが割り当てられます。本番環境とステージング環境のプロジェクトを分ければ、ステージング用キーが漏洩しても本番の決済には影響しません。本番キーを閲覧できる人を制限してください。EBA（欧州銀行監督機構）が2019年に公表したICT（情報通信技術）セキュリティに関するガイドラインは、「知る必要がある者だけ」のアクセスと「最小限のアクセス権」を原則として定めており、技術担当者も対象です。2025年以降は、DORA（Digital Operational Resilience Act、デジタル・オペレーショナル・レジリエンス法）が大半の決済事業者にこの義務を課しています。
また、キーを置き換える手順を、必要になる前に文書化しておいてください。OWASPのCryptographic Storage Cheat Sheetは、一定期間ごとに、また漏洩が疑われる場合にはいつでもキーをローテーションすることを推奨し、「キーのローテーションに必要なコードと手順は、それが必要になる前に整備されていること」を求めています。
ペイメントAPIからのWebhookはどのように検証すべきか?#
Webhookは、何かが変化したことを知らせる通知として扱い、支払いが行われた証明として扱ってはいけません。コールバックURLを知った者は、偽の「完了」メッセージを送信できてしまいます。安全なパターンは、自社のキーを使ってAPIから請求書の情報を読み直し、APIが返す内容に基づいて処理することです。
ItisPayの請求書を作成する際、callback_urlフィールドでステータス更新の送信先アドレスを設定します。Webhookが届いたら、そこから請求書IDを取得し、IDを指定して請求書に対してGETを呼び出してください。期待するステータスと、価格設定した金額がレスポンスで確認できた場合にのみ、商品の出荷や入金処理を行ってください。このエンドポイントのドキュメントでは、「ユーザーへの表示または検証のため」に決済ステータスとブロックチェーンの詳細を返すと説明されています。
ハンドラーをすっきり保つための規則は次のとおりです。
- WebhookはHTTPSでのみ受け付け、平文のHTTPは拒否してください。
- ハンドラーは冪等にしてください。処理済みの請求書IDとステータスを保存し、重複を読み飛ばしてください。プロバイダーは通知を再送することがあるためです。
- すばやく応答し、処理はキューに渡して行ってください。データベースの遅延によって再試行が発生しないようにするためです。
- プロバイダーがWebhookにHMAC（ハッシュベースのメッセージ認証コード）で署名している場合は、RFC 2104で定義された鍵付きハッシュを使い、署名を再計算して、定数時間の関数で比較してください。OWASP Webhook Security Cheat Sheetは率直に次のように述べています。「==は決して使わないこと。タイミング情報が漏れ、エンドポイントが署名オラクルになり得る。」署名付きのタイムスタンプが古すぎるメッセージは拒否してください。
本番稼働前にテストしてください。ItisPayには、実際のテスト用請求書のステータス変更をシミュレートするエンドポイントと、請求書または注文IDに対する最新のWebhookを再送するエンドポイントがあります。実際の資金を使わずに、再試行と重複を確認できます。
出金とダッシュボードへのアクセスをどのように制限するか?#
出金では、盗まれたキーが実際の金銭的損失につながるため、その周辺に人手による管理を加えてください。ItisPayの出金エンドポイントを通じて、法定通貨の出金は受取人のIBANへ、暗号資産の出金はウォレットアドレスへ、いずれも利用可能残高から行われます。APIはリクエストの内容どおりに処理するだけであり、そのリクエストが正当かどうかを判断するのは自社の責任です。
自社側で有効な管理策は次のとおりです。
- ダッシュボードまたは出金の権限を持つすべての人に対する2段階認証。 EUの決済規制では、決済ユーザーに対してすでにこの考え方が採用されています。PSD2の強固な顧客認証ルールでは、「知識」「所持」「固有の要素」のうち、少なくとも2つの独立した要素が求められています。同じ基準を自社のスタッフにも適用してください。
- 登録済みの受取人。 承認済みのIBANとウォレットアドレスの一覧を自社で管理し、出金サービスはその一覧に載っている宛先にのみ送信するようにしてください。新しい受取人は、理想的には冷却期間を設けたうえで、別途承認を経る必要があります。
- 一定額を超えた場合の第二承認者。 一人が準備し、別の一人が承認します。金額は自社のリスク許容度に基づいて設定してください。
- 出金サービスの分離。 請求書を作成するチェックアウト用サーバーとは別に、固定アドレスを許可リストに登録した独立したサービスから出金を実行してください。
| 管理策 | 防げること | 判定 |
|---|---|---|
| キーへのIP許可リスト | 漏えいしたキーの、自社ネットワーク外からの使用 | 有効 |
| キーはサーバーのみに保持 | ブラウザ、アプリ、リポジトリからのキー窃取 | 有効 |
| ウェブフック受信後に請求書を再取得 | 偽の「支払い済み」通知 | 有効 |
| 登録済み受取人と第二承認者 | 攻撃者のIBANやウォレットへの送金 | 有効 |
| 許可リスト内の侵害されたサーバーに対し、いずれか1つの管理策だけを使う場合 | 内部にすでにいる者による窃取 | 効果なし |
DORAとPCI DSSはAPIアクセスに何を求めているか？#
規制対象のEU金融機関であれば、これらの管理策は任意の追加措置ではありません。デジタル運用レジリエンス法（DORA、規則（EU）2022/2554）は、EBAによれば2025年1月17日から適用されています。その第9条は、企業に対して「物理的または論理的なアクセスを制限するポリシーを実装する」こと、および「強力な認証の仕組みに関するポリシーとプロトコルを実装する」ことを求めています。許可リストで制限され、サーバー側のみで使用され、ローテーション計画を伴うキーは、監査人が確認を求める種類の証拠です。
PCI DSSはカード情報を対象とするもので、暗号資産の請求書は対象外です。同じチームがカード決済も運用している場合、要件8.4.2は、カード会員データ環境へのすべてのアクセスに多要素認証を求めています。また、バージョン4.0の将来適用の要件は2025年3月31日に義務化されました。
支払いAPIのセキュリティ管理が効かなくなるのはどこか？#
これらの管理策は侵入経路を絞り込むものです。それだけで連携を安全にするわけではありません。ウェブフックの送信元であっても、OWASPのウェブフックシートはIP許可リストを「追加の層にすぎない」と位置づけ、その理由として「共有の送信元IPは本人性の証明ではない」と述べています。
効果がない場合
- 許可リスト上のサーバーが侵害された場合。攻撃者は信頼できるアドレスから、実際のキーを使ってリクエストを送信します。
- 共有の送信元アドレス。他のテナントが同じNATアドレスからクラウドを経由して外部に出る場合、許可リストではその相手と自社を区別できません。
- 二段階認証のないダッシュボードのパスワード窃取。攻撃者はAPIを経由せずに済みます。
- 請求書の項目内の個人データ。ItisPayの公開請求書エンドポイントは、未払いの請求書について、キーなしで詳細情報をすべて返します。そのため、顧客の氏名やメールアドレスは注文名に含めないでください。
安全な連携を1日の午後で始めるには？#
決まった順序に従えば、安全な連携の技術的な部分は午後のうちに終えられます。以下の手順ではItisPayを使用していますが、同じ順序はどのプロバイダーでも有効です。
- テスト用プロジェクトと本番用プロジェクトを、それぞれ個別のキーを持たせて作成します。
- 両方のキーをシークレットマネージャーに保存し、サーバー上でのみ読み込みます。
- 各環境の公開送信元アドレスを確認し、「API Allowed IPs」に入力します。
- バックエンドから請求書を作成します。Api-keyヘッダーを付けて https://api.itispay.com/api/v1/invoices にPOSTし、一意のorder_id、fiat_currencyがEURのfiat_amount、currencyに暗号資産、そしてcallback_urlを指定します。
- ウェブフックハンドラーを構築します。HTTPSのみを使用し、冪等性を持たせ、いかなる処理の前にもIDで請求書を再取得します。
- 処理対象の各ステータスについてウェブフックのシミュレーションを実行し、その後に再送エンドポイントで重複をテストします。
- 送金機能は最後に有効にし、登録済み受取人と第二承認者を設定します。
手早く始めるには、ダッシュボードのAsk AIアシスタントに依頼すると、サンプルコードを作成できます。例えば、Api-keyヘッダーを設定したNode.jsでの請求書作成呼び出しなどです。これは下書きとして扱ってください。出荷前にフィールド名をAPIリファレンスと照合してください。契約として従うべきものはリファレンスであり、生成された例ではないためです。ItisPayはnpmで公式TypeScriptクライアント @itispay/typescript-client も公開しています。
もし支払いオーケストレーションのより広い構成にこれを組み込む場合は、各プロバイダーに個別のキー、許可リスト、ウェブフックハンドラーを割り当ててください。IDで再取得する同じレコードは、経理チーム向けの暗号資産決済の照合にも使われます。
自社でシステムを構築することなくユーロを受け取りつつ、ステーブルコイン決済を受け付けたい場合は、ItisPayがAPI、請求書発行、ウェブフック、照合、そして支払いAPIセキュリティの第一層を提供します。その第一層とは、自社のIPアドレスに制限できるキーです。ライセンス、KYC、自社IBANへの決済は、EUの認可を受けたCASP＋決済機関パートナーを通じて行われ、多くのチームはKYBから最初の取引まで1週間未満で進みます。
本記事は情報提供のみを目的としており、法律または規制上の助言を構成するものではありません。
