トークン管理

Issuing を使用して、クレジットカードのネットワークトークンを管理する方法をご紹介します。

トークンについて

トークンは、カード保有者が以下を行うときに発行されるカードの仮想表現です。

Apple Pay や Google Pay などのデジタルウォレットにカードを追加する
オンライン店舗のアカウントまたは仲介決済業者に支払い方法を保存する

顧客は支払いにトークンを使用でき、カードの使用時に毎回機密性の高いカード情報を表示することはありません。そのため、トークンはカード番号、有効期限、確認コードなどのカード詳細の代わりとして機能し、取引や不正利用者によるカード情報の盗難リスクを軽減します。機密性の高いカード情報を表示することがないため、通常はクレジットカードや、決済フォームへのカード詳細の手動入力よりも安全な支払い形式と考えられています。

トークンの使用が最も適しているユーザーは以下のとおりです。

カード保有者が Apple Pay、Google Pay、Samsung Pay を使用して支出できるようにするユーザー
カード非対面取引の Issuing の取引額が高いユーザー (オンライン購入など)
トークンの動作をビジネスロジックに導入するユーザー

トークン管理

Stripe Issuing を使用すると、プログラムで Tokens API を使用して発行されたすべてのトークンに関連付けられた詳細を表示し、管理できます。これらの詳細は、トークンの特性と、どのように使用されているかをより適切に理解できるように提供されます。たとえば、次のような主要な特性の詳細を確認できます。

トークンの発行元: デジタルウォレットプロバイダーとビジネスのどちらがトークンをリクエストしているか。
予想されるトークンのリスク: 指定されたトークンに対する、カードネットワークのリスク評価と、その推奨事項。
トークンに関連付けられているデバイス: 時計、電話、その他のデバイスのどれがトークンを要求しているか、またそのデバイスの評価されているリスク。
トークン発行元のカード保有者の特性: name や address などのカード保有者の値が、追加確認における Stripe のカード保有者の値と一致しているかどうか。

トークンの特性の把握に加えて、Tokens API では希望するワークフローに基づき、トークンを有効化、一時停止、無効化できます。たとえば、以下の処理を選択できます。

プログラムがカードを再発行した際に、既存のトークンから新しいカードに移行される対象を確認します。
不正使用の疑いがあるトークンを、基盤となるカードに影響を与えることなく、無効化します。

issuing.authorization オブジェクトにも token フィールドがあり、トークンを使用する場合に入力されます。

リスク管理

Stripe はトークン化リクエストを受信すると、さまざまな変数を評価してリクエストを承認するかどうかを決定します。この評価の結果、以下のいずれかが選択されます。

トークン化リクエストを承認し、トークンを作成してデジタルウォレットに追加します。
追加の認証を要求し、デジタルウォレットのプロバイダーによる 1 回限りのパスコードフローを開始します。認証に成功すると、トークンが作成され、対応するデジタルウォレットに追加されます。これらのシナリオでは、追加の認証が完了するまで status フィールドは requested と表示されます。
トークン化リクエストを拒否し、トークンが作成されないようにします。

ユーザーは、自社の追加リスク管理を Stripe のリスク管理の最上位に配置することもできます。Tokens API では作成時点でトークン化リクエストを完全に拒否することはできませんが、ユーザーは作成後すぐにトークンを無効化または一時停止できます。

トークンの仕組み

トークンの作成とトークンのライフサイクルの全体像を把握しやすくするために、トークンの仕組みについて説明します。

トークンを作成する

トークンの作成 (トークン化) は、カード保有者、ユーザー、デジタルウォレットプロバイダー、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 がいつでも通知を受け取るとは限りません。

以下のシーケンス図は、トークン化プロセスの詳細を図示したものです。

トークンのライフサイクル

トークンは作成後、デジタルウォレットで次の 4 つの異なる状態になる可能性があります。

Inactive (非アクティブ): トークンリクエストが未処理であり、まだトークンを承認に使用できません。Tokens API で無効なトークンのステータスは requested になります。
Suspended (一時停止): トークンは一時的にウォレットで使用できなくなっています。Tokens API を使用するカード保有者または Stripe ユーザーはトークンの一時停止を開始できます。カード保有者は、Stripe ユーザーによる (デジタルウォレットアプリによる) 一時停止を元に戻せません。ユーザーは Tokens API から直接、一時停止されたカードを再度有効化することしかできません。
Active (アクティブ): 追加されたウォレットでトークンを利用できます。
Deleted (削除済み): トークンはウォレットから削除され、使用できなくなっています。この状態のトークンは修正できません。

以下の状態図は、さまざまな状態と、それらがどのように API に反映されるか、また API を使用して修正する方法を示しています。

Stripe はトークンのステータスが変わったときに、それをカード保有者の状態とカードの状態に自動的に同期します。また、カード再発行時に元のカードが最初にキャンセルされていない場合、Stripe はトークンを移行します。どのトークンがどのカードに関連付けられているかを確認するには、List API を使用します。

マーチャントトークン

ビジネスは、小売業者による将来の使用に備えて支払い方法を保存するときにも、トークンを作成できます (たとえば、カード保有者が Amazon での決済用にカード詳細を保存するなど)。このようなシナリオでは、ビジネスによってトークン作成が開始され、Tokens API は wallet_provider フィールドを保有しません。トークンの発行元である基になるビジネスを評価するには、トークンを使用して実施されたオーソリに関連付けられているビジネスの詳細を調べることをお勧めします。MasterCard からカードを発行する場合、そこから発生するトークンには、network_data.mastercard.token_requestor_name フィールドの読み取り可能な名前が入力される場合があります。

マーチャントトークンは、それを発生させる特定のビジネス (カードネットワークのトークンリクエスター) に関連付けられていて、他のビジネスでは使用できません。

トークンが取引に使用された日時を特定する

トークンを使用する Authorization (オーソリ) または Transaction (取引) には、token 属性で Token オブジェクトへの拡張可能な参照が含まれます。トークンを使用しなかった Authorization または Transaction では、このフィールドは null になります。これを、Authorization オブジェクトまたは Transaction オブジェクトの wallet 属性、または Token オブジェクトの wallet_provider 属性と組み合わせて、デジタルウォレットが使用されたかどうかを判断します。

詳細については、Authorizations (オーソリ) および Transactions (取引) API に関するドキュメントをご覧ください。

ネットワークデータの制限

Issuing トークンオブジェクトには、network_data と呼ばれるオプションの拡張可能フィールドが含まれています。このフィールドには、主にトークン作成プロセスに関連したトークンに関する機密性の高いその他のカードネットワーク情報が含まれています。このデータは機密性が非常に高いため、データにアクセスするために必要な権限を設定した制限付きのアクセスキーを含める必要があり、トークンの作成 (created 値に基づく) から最初の 24 時間以内にのみトークンのデータを表示できます。このデータは、API によるトークンの取得と、API によるトークンのステータスの更新でのみ利用できます。

このデータにアクセスするには、次の権限で制限付きのアクセスキーを設定します。

Retrieve メソッドと List メソッドへの Issuing トークンの読み取りアクセス
Update Status メソッドへの Issuing トークンの書き込みアクセス
24 時間の期限内に network_data にアクセスする Issuing トークンのネットワークデータ読み取りアクセス

当初の利用可能な最初の 24 時間以降も network_data にアクセスする必要がある場合は、制限付きのアクセスキーが使用する IP アドレスを制限する必要があります。

テスト

カード発行会社のカード保有者は、店舗またはデジタルウォレットでトークンを無料で作成できます。任意のデジタルウォレットでトークンを 1 つ作成して、トークン更新の Webhook イベント、API フィールド、影響を把握することをお勧めします。これを行うには、まず手動のプロビジョニングについてデジタルウォレットのガイドに従ってください。

Tokens API をテストする場合は、ウォレットフィールドを使用可能な選択肢の 1 つに設定して、テストオーソリを作成できます。トークン フィールドは、結果のオーソリに設定されます。その後、このトークンの API メソッドを通常どおり使用できます。これらのシナリオでは、network_data を含むすべてのフィールドが設定されているわけではなく、このトークンは後続のテストオーソリには使用されません。

Tokens API

トークンデータには Tokens API を介してのみアクセスできます。いくつかの適用例を以下に示します。

手動プロビジョニングの成功を確認する例

この例では、issuing_token.created と issuing_token.updated イベントに登録します。
issuing_token.created イベントを受け取ったら、Retrieve API を使用して network_data を拡張し、プロビジョニングの詳細を確認します。例を以下に示します。

{
  "id": "evt_1NxBn3FUQNp5XJkna0rkKU2r",
  "object": "event",
  "api_version": "2025-04-30.basil",
  "created": 1691100189,
  "data": {
    "object": {
      "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t",
      "object": "issuing.token",
      "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
      "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 コールで使用します。

Command Line
curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \
 -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
 -d "expand[]"=network_data \
 -G

これにより、以下のレスポンスが生成されます。

{
  "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t",
  "object": "issuing.token",
  "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
  "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 イベントを受信します。

{
  "object": {
    "id": "intok_1NuMIZuTQ2hhXJooNmDzEz0t",
    "object": "issuing.token",
    "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
    "created": 1691100179,
    "device_fingerprint": null,
    "last4": "9203",
    "livemode": true,
    "network": "visa",
    "network_updated_at": 1691100170,
    "status": "active"
  }
}

トークンには wallet_provider フィールドがないため、これはマーチャントトークンです。Retrieve API を使用して network_data を拡張し、プロビジョニングの詳細を確認します。

Command Line
curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \
 -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
 -d "expand[]"=network_data \
 -G

これにより、以下のレスポンスが生成されます。

{
  "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t",
  "object": "issuing.token",
  "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
  "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 を使用して削除します。次に、カード保有者にフォローアップを行い、トークンが実際にリクエストされたものであるかを確認します。カード保有者がリクエストしていなかった場合、カード番号が盗難にあったかアカウントが侵害されたときには、カードをキャンセルして再発行します。

Command Line
curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \
 -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
 -d status=deleted

デバイス監視の例

前の例と同様に、トークンイベントに登録し、イベントを受け取ったときにその ID で Retrieve API リクエストを実行します。このケースでは、device_fingerprint が入力されているため、network_data.device.location フィールドを確認します。場所の座標を使用すると、デバイスが別の国にプロビジョニングされていたと表示されます。このカード保有者が海外に渡航していたという事前通知を受け取っていて、指定された渡航先の国と一致することが分かります。