# トークン管理 Issuing を使用して、クレジットカードのネットワークトークンを管理する方法をご紹介します。 トークンは、カード保有者が以下を行うときに発行されるカードの仮想表現です。 - Apple Pay や Google Pay などのデジタルウォレットにカードを追加する - オンライン店舗のアカウントまたは仲介決済業者に支払い方法を保存する 顧客は支払いにトークンを使用でき、カードの使用時に毎回機密性の高いカード情報を表示することはありません。そのため、トークンはカード番号、有効期限、確認コードなどのカード詳細の代わりとして機能し、取引や不正利用者によるカード情報の盗難リスクを軽減します。機密性の高いカード情報を表示することがないため、通常はクレジットカードや、決済フォームへのカード詳細の手動入力よりも安全な支払い形式と考えられています。 トークンは、以下の場合に最も適しています。 - カード会員が Apple Pay、Google Pay、または Samsung Pay を使用して支出できるようにする - カード非対面取引の Issuing の取引額が高いユーザー (オンライン購入など) - トークンの動作をビジネスロジックに導入する ## トークン管理 Stripe Issuing を使用すると、プログラムで [Tokens API](https://docs.stripe.com/api/issuing/tokens.md) を使用して発行されたすべてのトークンに関連付けられた詳細を表示し、管理できます。これらの詳細は、トークンの特性と、どのように使用されているかをより適切に理解できるように提供されます。たとえば、次のような主要な特性の詳細を確認できます。 - **トークンの発行元:** [デジタルウォレットプロバイダーとビジネス](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-wallet_provider)のどちらがトークンをリクエストしているか。 - **予想されるトークンのリスク:** 指定されたトークンに対する、カードネットワークの[リスク](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-visa-token_risk_score)評価と、その[推奨事項](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-suggested_decision)。 - **トークンに関連付けられているデバイス:** 時計、電話、その他の[デバイス](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-device-type)のどれがトークンを要求しているか、またそのデバイスの[評価されているリスク](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-device_trust_score)。 - **トークン発行元のカード保有者の特性:** [name](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-cardholder_name) や [address](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-cardholder_address) などのカード保有者の値が、追加確認における Stripe のカード保有者の値と一致しているかどうか。 トークンの特性の把握に加えて、Tokens API では希望するワークフローに基づき、トークンを有効化、一時停止、無効化できます。たとえば、以下の処理を選択できます。 - プログラムがカードを再発行した際に、既存のトークンから新しいカードに移行される対象を確認します。 - 不正使用の疑いがあるトークンを、基盤となるカードに影響を与えることなく、無効化します。 `issuing.authorization` オブジェクトにも [token フィールド](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-token)があり、トークンを使用する場合に入力されます。 ## リスク管理 Stripe はトークン化リクエストを受信すると、さまざまな変数を評価してリクエストを承認するかどうかを決定します。この評価の結果、以下のいずれかが選択されます。 - トークン化リクエストを承認し、トークンを作成してデジタルウォレットに追加します。 - 追加の認証を要求し、デジタルウォレットのプロバイダーによる 1 回限りのパスコードフローを開始します。認証に成功すると、トークンが作成され、対応するデジタルウォレットに追加されます。これらのシナリオでは、追加の認証が完了するまで [status フィールド](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-status) は `requested` と表示されます。 - トークン化リクエストを拒否し、トークンが作成されないようにします。 お客様は、Stripe のリスク管理に加えて独自のリスク管理を置くこともできます。Token API は作成時にトークン化リクエストを完全に拒否することはできませんが、作成直後にトークン化を無効にしたり一時停止したりすることはできます。 ## トークンの仕組み トークンの作成とトークンのライフサイクルの全体像を把握しやすくするために、トークンの仕組みについて説明します。 ### トークンを作成する トークンの作成 (トークン化) はカード会員、Stripe ユーザー、デジタルウォレットのプロバイダー、Stripe そしてカードネットワークといった様々な関係者が関わる複数ステップにわたるプロセスです。下記はそのシナリオ例で、カード会員が完了しなければならない段階と、貴社プログラムの一環として Tokens API を利用する際に関与するプロセスを明らかにしています。 #### シナリオ例 Issuing プログラムのカード保有者が、Stripe の発行するカードを Apple Pay などのデジタルウォレットに追加することを希望しています。これを行うために、カード保有者はデジタルウォレットアプリを開き、カード保有者情報 (氏名と請求先住所など) とカード情報 (カード番号と有効期限など) の入力を求める画面を完了します。 この情報は、次にウォレットプロバイダー (この場合は Apple Pay) に送信されます。ウォレットプロバイダーはカードの基本となるネットワーク (Visa や Mastercard など) とともに、ネットワークに「トークンリクエスター」として登録されています。次に、カードネットワークはこのデータに対して一連の検証を実施し、自社のデータと結合してトークン化リクエストを作成し、Stripe による決定のために転送します。Stripe は自社の追加検証を実施してリクエストの処理方法を決定します。このページで前述したように、この検証ステップは次の 3 つの結果になります。 - Stripe がトークン化を承認し、それによりウォレット内のトークンが有効化され、使用する準備が整います。Stripe は `issuing_token.created` イベントを、リッスンされている任意の Webhook エンドポイントに送信します。 - Stripe は追加の確認を求め、カード保有者に認証チャレンジが表示されます。Stripe は `issuing_token.created` イベントを、リッスンされている任意の Webhook エンドポイントに送信します。カード保有者がこのステップの完了に成功すると、トークンは有効になります。Stripe は、トークンが有効になり次第、リッスンされている任意の Webhook エンドポイントに `issuing_token.updated` イベントを送信します。 - Stripe がトークン化リクエストを拒否し、それによりウォレットにトークンが追加されることがなくなります。Stripe は `issuing_token.created` イベントを、リッスンされている任意の Webhook エンドポイントに送信しません。 ウォレットプロバイダーまたはカードネットワークは、トークン化プロセスのどの段階でも、トークン化リクエストの進行を停止できます (この場合、Stripe がいつでも通知を受け取るとは限りません)。 以下のシーケンス図は、トークン化プロセスの詳細を図示したものです。 成功したプロビジョニングリクエストの概略フロー (See full diagram at https://docs.stripe.com/issuing/controls/token-management) ```text [カード保有者] -- カード情報を提供 --> [デバイス (スマートフォンなど)] [デバイス (スマートフォンなど)] -- データを転送 --> [ウォレットプロバイダー (Apple Pay など)] [ウォレットプロバイダー (Apple Pay など)] -- プロビジョニングデータを送信 --> [カードネットワーク (Visa など)] [カードネットワーク (Visa など)] -- プロビジョニングリクエストを送信 --> [Stripe] [Stripe] -- issuing_token.created: 承認のプロビジョニングレスポンスを送信 --> [カードネットワーク (Visa など)] [カードネットワーク (Visa など)] -- プロビジョニングレスポンスを確定 --> [ウォレットプロバイダー (Apple Pay など)] [ウォレットプロバイダー (Apple Pay など)] -- プロビジョニングレスポンスを転送 --> [デバイス (スマートフォンなど)] [デバイス (スマートフォンなど)] -- ウォレットでトークンを使用する準備ができる --> [カード保有者] ``` ### トークンのライフサイクル トークンは作成後、デジタルウォレットで次の 4 つの異なる状態になる可能性があります。 - **Inactive (非アクティブ)**: トークンリクエストが未処理であり、まだトークンを承認に使用できません。Tokens API で無効なトークンのステータスは `requested` になります。 - **Suspended (一時停止)**: トークンは一時的にウォレットで使用できなくなっています。Tokens API を使用するカード保有者または Stripe ユーザーはトークンの一時停止を開始できます。カード保有者は、Stripe ユーザーによる (デジタルウォレットアプリによる) 一時停止を元に戻せません。ユーザーは Tokens API から直接、一時停止されたカードを再度有効化することしかできません。 - **Active (アクティブ)**: 追加されたウォレットでトークンを利用できます。 - **Deleted (削除済み)**: トークンはウォレットから削除され、使用できなくなっています。この状態のトークンは修正できません。 以下の状態遷移図では、さまざまな状態とそれらの API における反映方法、および API を使用した変更方法について説明しています。 トークンライフサイクルの状態図 (See full diagram at https://docs.stripe.com/issuing/controls/token-management) ```text [無効requested] -- カード保有者のみ --> [アクティブactive] [アクティブactive] -- カード保有者または Stripe --> [削除済みdeleted] [アクティブactive] -- カード保有者または Stripe --> [一時停止suspended] [一時停止suspended] -- カード保有者または Stripe --> [削除済みdeleted] [一時停止suspended] -- カード保有者 (一時停止を開始した場合) または Stripe --> [アクティブactive] ``` Stripe はトークンのステータスが変わったときに、それをカード保有者の状態とカードの状態に自動的に同期します。また、カード再発行時に元のカードが最初にキャンセルされていない場合、Stripe はトークンを移行します。どのトークンがどのカードに関連付けられているかを確認するには、[List API](https://docs.stripe.com/api/issuing/tokens/list.md) を使用します。 ### マーチャントトークン Businesses can also create tokens when saving a payment method for future use at a retailer (for example, a cardholder saving their card details for checkout at Amazon). In these scenarios, the business originates the token creation, and the Tokens API won’t have the [wallet_provider field](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-wallet_provider). To assess the underlying business that originated the token, examin the [business details](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-merchant_data) associated with authorizations conducted using the token. If you issue cards from Mastercard, tokens that originate from them might populate a readable name in the [network_data.mastercard.token_requestor_name field](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-mastercard-token_requestor_name). マーチャントトークンは、それを発生させる特定のビジネス (カードネットワークのトークンリクエスター) に関連付けられていて、他のビジネスでは使用できません。 ### トークンが取引に使用された日時を特定する トークンを使用する Authorization (オーソリ) または Transaction (取引) には、`token` 属性で Token オブジェクトへの拡張可能な参照が含まれます。トークンを使用しなかった Authorization または Transaction では、このフィールドは null になります。これを、Authorization オブジェクトまたは Transaction オブジェクトの `wallet` 属性、または Token オブジェクトの [wallet_provider](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-wallet_provider) 属性と組み合わせて、デジタルウォレットが使用されたかどうかを判断します。 詳細については、[Authorizations (オーソリ)](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-token) および [Transactions (取引)](https://docs.stripe.com/api/issuing/transactions/object.md#issuing_transaction_object-token) API に関するドキュメントをご覧ください。 ## ネットワークデータの制限 Issuing トークンオブジェクトには、[展開可能フィールド](https://docs.stripe.com/api/expanding_objects.md)である [network_data](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data) という省略可能なフィールドが含まれます。これには、主にトークン作成プロセスに関連する、トークンに関する追加の機微なカードネットワーク詳細が含まれます。このデータは非常に機微であるため、データにアクセスするには必要な権限を持つ[制限付き API キー](https://docs.stripe.com/keys.md#create-restricted-api-key)が必要です。また、このデータをトークン上で表示できるのは、トークン作成後の最初の 24 時間以内 (**created** の値に基づく) に限られます。このデータは、[トークンを取得](https://docs.stripe.com/api/issuing/tokens/retrieve.md)する API と、[トークンのステータスを更新](https://docs.stripe.com/api/issuing/tokens/update.md)する API でのみ利用できます。 このデータにアクセスするには、次の権限で制限付きのアクセスキーを設定します。 - Retrieve メソッドと List メソッドへの Issuing トークンの読み取りアクセス - Update Status メソッドへの Issuing トークンの書き込みアクセス - 24 時間の期限内に **network\_data** にアクセスする Issuing トークンのネットワークデータ読み取りアクセス 最初の 24 時間の利用可能期間を過ぎても `network_data` にアクセスする必要がある場合は、制限付きアクセスキーに対して[アクセスポリシーを設定する](https://docs.stripe.com/keys.md#access-policies)必要があります。 ## テスト カード発行会社のカード保有者は、店舗またはデジタルウォレットでトークンを無料で作成できます。任意のデジタルウォレットでトークンを 1 つ作成して、トークン更新の Webhook イベント、API フィールド、影響を把握することをお勧めします。これを行うには、まず手動のプロビジョニングについて[デジタルウォレットのガイド](https://docs.stripe.com/issuing/cards/digital-wallets.md)に従ってください。 Tokens API をテストする場合は、[ウォレットフィールド](https://docs.stripe.com/api/issuing/authorizations/test_mode_create.md#test_mode_create_authorization-wallet)を使用可能な選択肢の 1 つに設定して、テストオーソリを作成できます。**トークン** フィールドは、結果のオーソリに設定されます。その後、このトークンの API メソッドを通常どおり使用できます。これらのシナリオでは、**network\_data** を含むすべてのフィールドが設定されているわけではなく、このトークンは後続のテストオーソリには使用されません。 ## Tokens API トークンデータには Tokens API を介してのみアクセスできます。いくつかの適用例を以下に示します。 ### 手動プロビジョニングの成功を確認する例 - この例では、`issuing_token.created` と `issuing_token.updated` イベントに登録します。 - `issuing_token.created` イベントを受け取ったら、Retrieve API を使用して **network\_data** を拡張し、プロビジョニングの詳細を確認します。例を以下に示します。 ```json { "id": "evt_1NxBn3FUQNp5XJkna0rkKU2r", "object": "event", "api_version": "2026-08-26.dahlia", "created": 1691100189, "data": { "object": { "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "created": 1691100179, "device_fingerprint": "intd_1JDmgz2OpvKigH2CxnEEs", "last4": "9203", "livemode": true, "network": "mastercard", "network_updated_at": 1691100170, "status": "requested", "wallet_provider": "apple_pay" } }, "livemode": true, "pending_webhooks": 0, "request": { "id": "req_ARTvFhTufhHna9", "idempotency_key": "49a40678-8f45-4c91-9d6f-98a5bd569f9d" }, "type": "issuing_token.created" } ``` - デジタルウォレットによって開始されたことを示す、**wallet\_provider** フィールドが入力されていることを確認し、オブジェクトの **id** をメモします。それを Retrieve API コールで使用します。 ```bash curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \ -u <>: \ -d "expand[]"=network_data \ -G ``` これにより、次のレスポンスが生成されます。 ```json { "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "created": 1691100159, "device_fingerprint": "intd_1JDmgz2OpvKigH2CxnEEs", "last4": "9203", "livemode": true, "network": "mastercard", "network_data": { "device": { "device_fingerprint": "intd_1JDmgz2OpvKigH2CxnEEs", "ip_address": null, "location": "+30.22/-89.10", "name": "AB's phone", "phone_number": null, "type": "phone" }, "mastercard": { "card_reference_id": "...", "token_reference_id": "...", "token_requestor_id": "...", "token_requestor_name": "APPLE PAY" }, "type": "mastercard", "wallet_provider": { "account_id": null, "account_trust_score": null, "card_number_source": "manual", "cardholder_address": null, "cardholder_name": null, "device_trust_score": null, "hashed_account_email_address": null, "reason_codes": [], "suggested_decision": null, "suggested_decision_version": null } }, "network_updated_at": 1691100170, "status": "requested", "wallet_provider": "apple_pay" } ``` - この例では、**card\_number\_source** は `manual` で、トークンの **status** は `requested` であり、Apple Pay ウォレットが使用されます。これは、カード保有者がカードを Apple Wallet に登録したときにカード詳細を保有していて、ウォレットでカードを使用する前に追加の確認を完了する必要があることを示します。 - 数秒後に、同じトークンの `issuing_token.updated` イベントを確認できます。トークンのステータスは `active` 状態になります。これは、カード保有者が確認を正常に完了し、カードを Apple Pay に使用できることを示します。 ### 疑いのあるマーチャントトークンを削除する例 - この例では、`issuing_token.created` イベントに登録します。 - Webhook は `issuing_token.created` イベントを受信します。 ```json { "object": { "id": "intok_1NuMIZuTQ2hhXJooNmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "created": 1691100179, "device_fingerprint": null, "last4": "9203", "livemode": true, "network": "visa", "network_updated_at": 1691100170, "status": "active" } } ``` - トークンには **wallet\_provider** フィールドがないため、これはマーチャントトークンです。Retrieve API を使用して **network\_data** を拡張し、プロビジョニングの詳細を確認します。 ```bash curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \ -u <>: \ -d "expand[]"=network_data \ -G ``` これにより、以下のレスポンスが生成されます。 ```json { "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "created": 1691100186, "device_fingerprint": null, "last4": "4674", "livemode": true, "network": "visa", "network_data": { "visa": { // ...other fields }, "type": "visa", "wallet_provider": { "card_number_source": "manual", "cardholder_address": null, "cardholder_name": "abc" // ...other fields } }, "network_updated_at": 1691100170, "status": "active" } ``` - カード保有者の氏名が、想定される氏名と一致しない無効な値になっていることが分かります。 - 不正行為を回避するには、トークンが使用可能になる前に Update Status API を使用して削除します。次に、カード保有者にフォローアップを行い、トークンが実際にリクエストされたものであるかを確認します。カード保有者がリクエストしていなかった場合、カード番号が盗難にあったかアカウントが侵害されたときには、カードをキャンセルして再発行します。 ```bash curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \ -u <> \ -d status=deleted ``` ### デバイス監視の例 前の例と同様に、トークンイベントに登録し、イベントを受け取ったときにその ID で Retrieve API リクエストを実行します。このケースでは、**device\_fingerprint** が入力されているため、**network\_data.device.location** フィールドを確認します。場所の座標を使用すると、デバイスが別の国にプロビジョニングされていたと表示されます。このカード保有者が海外に渡航していたという事前通知を受け取っていて、指定された渡航先の国と一致することが分かります。