Issuing Elements の使用

PCI に準拠した方法でウェブアプリケーションにカードの詳細を表示する方法をご紹介します。

Stripe.js には、Issuing カードの機密データを PCI 要件に遵守した方法でウェブに表示するために使用できる、ブラウザー側の JavaScript ライブラリが含まれています。機密データは Stripe がオンラインで提供する iframe 内にレンダリングされるため、お客様のサーバーに影響することはありません。

注

Stripe.js は、ユーザーを保護するために追加データを収集します。高度な不正利用検出のために Stripe がどのようにデータを収集するかについて、詳細をご確認ください。

一時キー認証

Stripe.js は、一時キーを使用して、シークレットキーを公開することなく安全に Stripe API からカード情報を取得します。これを設定するには、サーバー側で一時キー交換を行う必要があります。

一時キーの作成プロセスは、ブラウザで Stripe.js を使用して nonce を作成すると、ブラウザで開始されます。この nonce とは、一時キーを作成する 1 回限りのトークンです。この nonce がサーバーに送信され、そこで Stripe API を (シークレットキーを使用して) 呼び出すことで一時キーと交換します。

サーバー側で一時キーを作成したら、Stripe.js が使用できるようにそれをブラウザに渡します。

安全なエンドポイントを作成する
サーバー側

Issuing Elements を組み込むための最初のステップは、表示するカードの一時キーを生成する安全なサーバー側のエンドポイントを作成することです。Issuing Elements Web 組み込みがこのエンドポイントを呼び出します。

さまざまな言語のウェブアプリケーションフレームワークに一時キー作成エンドポイントを実装する方法を以下に示します。

注

一時キーを作成する際は、API バージョンを指定する必要があります。現在、必要なバージョンは 2020-03-02 です。また、ウェブ組み込みで作成できる一時キーの nonce を渡す必要もあります。

Web API 組み込み
クライアント側

まず、ページに Stripe.js を含めます。Stripe.js の設定方法について、詳細は Stripe.js を含めるをご覧ください。

stripe.createEphemeralKeyNonce を使用して、取得するカードの Stripe インスタンスと一時キー nonce を作成します。作成したサーバー側のエンドポイントを呼び出し、nonce を使用して一時キーを取得します。

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

// Initialize Elements which you'll need later
const elements = stripe.elements();

// Use Stripe.js to create a nonce
const cardId = 'ic_1ITi6XKYfU8ZP6raDAXem8ql';
const nonceResult = await stripe.createEphemeralKeyNonce({
  issuingCard: cardId,
});
const nonce = nonceResult.nonce;

// Call your ephemeral key creation endpoint to fetch the ephemeral key
const ephemeralKeyResult = await fetch('/ephemeral-keys', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    card_id: cardId,
    nonce: nonce,
  })
});

const ephemeralKeyResponse = await ephemeralKeyResult.json();
const ephemeralKeySecret = ephemeralKeyResponse.ephemeralKeySecret;

一時キーを作成したので、カードの機密情報を表示することができます。これは、以下の Elements のいずれかを使用して実行でき、同じページの複数の Elements に同じ nonce と一時キーのペアを再利用できます。

Element	名前	提供状況
番号 (PAN)	`issuingCardNumberDisplay`	バーチャルカードのみ
セキュリティコード	`issuingCardCvcDisplay`	バーチャルカードのみ
有効期限	`issuingCardExpiryDisplay`	バーチャルカードのみ
PIN	`issuingCardPinDisplay`	物理カードのみ

各 Element は以下の設定を使用します。

名前	タイプ	使用状況
`style`	Style オブジェクト	一部のバリアント、疑似クラス、およびプロパティは入力 Element 用であり、これらの Element には適用されないことに注意してください。`::placeholder` は、入力専用の疑似クラスの例です。
`issuingCard`	`string`	発行されたカードの ID (`ic_abc123` など)
`nonce`	`string`	一時キー nonce
`ephemeralKeySecret`	`string`	一時キーの `secret` コンポーネント

注

issuingCardPinDisplay を使用する場合は、適切なメソッドを実装して、アクセスを認証されたユーザーに制限する必要があります。特に、issuingCardPinDisplay を使用して、ページへのアクセスを提供する前に 2 段階認証 (2FA) を適用する必要があります。お客様が十分なセキュリティ対策が実施されていないと Stripe が判断した場合、この Element へのアクセスを一時停止することがあります。

以下は、上記の例で作成した nonce と一時キーを使用して、これらの Elements の 1 つを表示する方法の例です。

const number = elements.create('issuingCardNumberDisplay', {
  issuingCard: cardId,
  nonce: nonce,
  ephemeralKeySecret: ephemeralKeySecret,
  style: {
    base: {
      color: '#fff',
      fontSize: '16px'
    },
  },
});

number.mount('#card-number');

コピーボタンを追加する

すでに説明した「カードデータ表示 Element」の他に、issuingCardCopyButton Element もあります。この Element は、toCopy 引数を受け取り、親の <div> の領域を占有する透明な「クリップボードにコピー」ボタンをレンダリングします。これにより、すべてのクリックイベントをイベントハンドラでインターセプトし、対応するカードデータ (初期化時に指定したもの) を取得し、クリップボードにコピーできるようになります。

これを使用すると、クレジットカード番号、有効期限、セキュリティコードの横に「クリップボードにコピー」ボタンを表示して、カード保有者がクレジットカードのデータを手動でコピーすることを防止できます。Stripe のこのコピー機能は、PCI に準拠した <iframe> に制限されています。

issuingCardCopyButton Element は、以下の構成を使用します。

名前	タイプ	使用状況
style	Style オブジェクト	一部のバリアント、疑似クラス、およびプロパティは入力 Element 用であり、これらの Element には適用されないことに注意してください。`::placeholder` は、入力専用の疑似クラスの例です。
toCopy	`'expiry'` または `'cvc'` または `'number'` または `'pin'`

このコンポーネントの使用方法例を以下に示します。

const cardNumber = elements.create('issuingCardNumberDisplay', {
  issuingCard: cardId,
  nonce: nonce,
  ephemeralKeySecret: ephemeralKeySecret,
});

cardNumber.mount('#card-number');

const cardNumberCopy = elements.create('issuingCardCopyButton', {
  toCopy: 'number',
  style: {
    base: {
      fontSize: '12px',
      lineHeight: '24px',
    },
  },
});

cardNumberCopy.mount('#card-number-copy');

ボタンをクリックしたときの反応が悪いときは、iframe をボタンに合わせて正しく配置するようにしてください。画像とそれを含む <div> はスタイルシート内で自由にカスタマイズできます。

#card-number-copy {
  height: 24px;
  width: 24px;
  position: relative;
  background-repeat: no-repeat;
  background-position: center;
  background-size: contain;
  background-image: url('data:image/svg+xml;base64,...');
}

最後のステップとして、「クリック後のフィードバック」オプションをユーザーに提供します。これを行うには、issuingCardCopyButton Element のon click イベントを使用します。これにより、以下に示すように一時的に新しいアイコンが表示されます。

#card-number-copy-success {
  display: none;
  height: 24px;
  width: 24px;
  background-image: url('data:image/svg+xml;base64,...');
  background-size: 100%;
}

// Example of hiding, replacing, and re-showing icons upon click
const timeout = (ms) => {
  return new Promise((resolve) => setTimeout(resolve, ms));
};
const hideAndShowSuccess = (iconElementId, successIconElementId) => {
  const el = document.getElementById(iconElementId);
  el.style.display = 'none';
  const elSuccess = document.getElementById(successIconElementId);
  elSuccess.style.display = 'block';
  timeout(2000).then(() => {
    elSuccess.style.display = 'none';
    el.style.display = 'block';
  });
};

cardNumberCopy.on('click', () => {
  hideAndShowSuccess('card-number-copy', 'card-number-copy-success');
});

その他の詳細情報

返されたカードオブジェクトには、result.issuingCard ペイロードから完全に削除された PCI フィールド (番号など) が含まれています。

上記の例の .mount() に加えて、Elements は次のメソッドもサポートしています。

.destroy()
.unmount()
.update({style})

Issuing Elements とネイティブアプリケーション

Issuing Elements は、iOS、Android、React Native などのネイティブアプリケーションを直接サポートしていません。

ネイティブアプリで Issuing Elements のカードの機密情報を表示するには、ウェブビューを使用します。このガイドに従ってサーバーでウェブ版の実装を構築し、その実装へのウェブビューの URL を指定します。ネイティブアプリ向けのウェブビューの実装について、詳細は以下の外部リソースをご覧ください。

iOS および iPadOS: WKWebView
Android: WebView
React Native: react-native-webview
Flutter: webview-flutter