サードパーティーの API エンドポイントにカード情報を転送する

Vault and Forward API を使用して、複数の決済代行業者間でカード詳細を安全に共有します。

Vault and Forward API を使用すると、カード情報をトークン化して Stripe の PCI 準拠のボールトに格納し、そのデータをサポートされる決済代行業者またはエンドポイントに振り分けることができます。API を使用して以下を実行できます。

複数の決済代行業者に対して Payment Element を使用します。
Stripe を、決済代行業者間でのカード情報のプライマリボールトとして使用します。
自社で構築済みの PCI 準拠のトークンボールトにカード情報を転送します。

アクセスをリクエストする

Stripe の転送サービスを使用するには、Stripe サポートにお問い合わせください。

送信先エンドポイントにリクエストを転送し、Stripe のボールトからカード詳細を入力する

カード情報を収集して PaymentMethod を作成する

カード情報を収集するには、Payment Element を使用して PaymentMethod を作成します。PaymentMethod を作成すると、カード情報は Stripe の PCI 準拠のボールトに自動的に保存されます。自社で構築済みのフロントエンドがある場合でも、PaymentMethod を直接作成することで Vault and Forward API を使用できます。

通常、PaymentMethods は、顧客に関連付けなければ再利用できません。ただし Vault and Forward API は、顧客に関連付けられていないものも含め、すべての PaymentMethod オブジェクトを受け入れます。

また、Vault and the Forward API は PaymentIntents の確定も、キャプチャーも行いません。そのため、別の決済代行業者ですでにキャプチャーされたものを Stripe での支払いのキャプチャーに誤って使用するおそれがあります。

セキュリティコードは一定の期間が過ぎると自動的に期限切れになり、Vault and Forward API を使用した場合にも期限切れになります。これらの条件のいずれかを満たした後にセキュリティコードが必要な場合は、カード詳細を再収集する必要があります。

ForwardingRequest を作成する

Stripe のボールトからカード情報を送信するには、ForwardingRequest を作成し、次のパラメーターを含める必要があります。

payment_method: Stripe が Stripe のボールト内で顧客のカード情報を識別し、そのデータをリクエスト本文に挿入できるようにするオブジェクト。
url: リクエストの正確な送信先エンドポイント。
request.body: 送信先エンドポイントに送信する API リクエスト本文 (別の決済代行業者に送信する支払いリクエストなど)。通常の場合に顧客のカード情報などを入力するフィールドはすべて空白のままにします。
replacements: Stripe が request.body で置き換えるようにするフィールド。常に設定することをお勧めする使用可能なフィールドは、card_number、card_expiry、card_cvc、cardholder_name です。たとえば、replacements 配列に card_number を含めると、request.body にある送金先エンドポイントに該当するカード番号フィールドが置き換えられます。

注意

Stripe は、カード保有者名フィールドの検証に関して他の業者よりも寛容な場合があります。cardholder_name 置換フィールドを使用する場合は、使用する名前が宛先エンドポイントによって実施される検証に合格することを徹底する責任があります。たとえば、宛先エンドポイントですべての名前に A ～ Z の文字のみを使用し、アクセント記号やその他の表記体系を使用しないことが求められている場合は、転送するカードの詳細がこの要件を満たしていることを確認する必要があります。別の方法としては、cardholder_name 置換フィールドを使用せず、リクエスト本文でカード保有者名を直接リクエストに指定する方法があります。

送信先エンドポイントが求めるデータに基づいてリクエストの形式を設定する必要があります。下記の例では、送信先エンドポイントは、Idempotency-Key ヘッダーを求め、支払いの詳細が記載された JSON 本文を受け取ります。

セキュリティのヒント

API リクエストごとに、送信先エンドポイントの API キーを渡す必要があります。Stripe はお客様が指定した API キーを使用してリクエストを転送し、送信先エンドポイントの API キーのハッシュ化および暗号化されたバージョンのみを保持します。

注意

Idempotency-Key を指定し、同じキーを使用するリクエストで 1 つのアウトバウンドリクエストのみが生成されることを確認できます。Stripe の別の一意のキーと、基になるサードパーティーのリクエストで指定するべき等キーを使用してください。

request.body フィールドまたは request.header フィールドを更新するたびに、新しい Idempotency-Key を使用します。以前のべき等キーを渡すと、API は以前の検証エラーを含む以前のレスポンスを再実行します。

カード情報を含むリクエストを転送する

Stripe は、PaymentMethod からのカード詳細を request.body に挿入することで、お客様の代わりに送信先エンドポイントにリクエストを送信します。自動カード更新機能 (CAU) は、有効かつ利用可能な場合は、カード詳細の更新を自動的に試み、リクエストに利用できる最新のカード詳細を提供します。

Stripe は、次にリクエストを送信先エンドポイントに転送します。例:

Stripe はエンドポイントに POST リクエストを送信します。

POST /v1/payments HTTP/1.1
User-Agent: Stripe
Accept: */*
Host: endpoint-url
Content-Type: application/json
Content-Length: 321

Stripe には以下のヘッダーが含まれます。

Destination-API-Key: {{DESTINATION_API_KEY}}
Destination-Idempotency-Key: {{DESTINATION_IDEMPOTENCY_KEY}}

Stripe は、リクエストに以下の JSON 本文を含めます。

{
  amount: {
    value: 1000,
    currency: 'usd'
  },
  paymentMethod: {
    number: '4242424242424242',
    expiryMonth: '03',
    expiryYear: '2030',
    cvc: '123',
    holderName: 'First Last',
  },
  reference: '{{REFERENCE_ID}}'
}

注

Vault and the Forward API を使用してオーソリリクエストを行う場合は、返金や不審請求の申請など、取引後のアクションをサードパーティーの決済代行業者と直接処理する必要があります。複数の決済代行業者の設定で 3DS 認証が必要な場合は、Stripe サポートにお問い合わせください。

送信先エンドポイントからのレスポンスに対応する

Vault and Forward API を使用してカード詳細をサードパーティーの決済代行業者に転送する際、Stripe は同時に送信先エンドポイントからのレスポンスを待機します。このレスポンスのタイムアウト期間は 1 分未満です。Stripe は、特定された PCI 機密データを非表示にし、送信先エンドポイントからの非表示のレスポンスを保存し、リクエストとレスポンスに関するデータが含まれた ForwardingRequest オブジェクトを返します。

注意

Vault and Forward API を使用してカード情報をサードパーティーの決済代行業者に転送する際、Stripe は、転送された API リクエストに対して代行業者が特定の応答を行うことを保証できません。サードパーティーの決済代行業者が応答しない場合、問題を解決するには、その決済代行業者に直接連絡する必要があります。

{
  id: "fwdreq_123",
  object: "forwarding.request",
  payment_method: "{{PAYMENT_METHOD}}",
  request_details: {
    body: '{
      "amount": {
        "value": 1000,
        "currency": "usd"
      },
      "paymentMethod": {
        "number": "424242******4242",
        "expiryMonth": "03",
        "expiryYear": "2030",
        "cvc": "***",
        "holderName": "First Last",
      },
      "reference": "{{REFERENCE_ID}}"
    }',
    headers: [
      {
        name: "Content-Type",
        value: "application/json",
      },
      {
        name: "Destination-API-Key",
        value: "{{DESTINATION_API_KEY}}",
      },
      {
        name: "Destination-Idempotency-Key",
        value: "{{DESTINATION_IDEMPOTENCY_KEY}}",
      },
      ...
    ]
  },
  request_context: {
      "destination_duration": 234,
      "destination_ip_address": "35.190.113.80"
  },
  response_details: {
    body: '{
      // Response from the third-party endpoint goes here
      ...
    }',
    headers: [
      ...
    ],
    status: 200,
  },
  replacements: [
    "card_number",
    "card_expiry",
    "card_cvc",
    "cardholder_name"
  ]
  ...
}

Vault and Forward API エンドポイントを設定する

Vault and Forward API エンドポイントを設定するには、以下を行う必要があります。

送信先エンドポイントがサポートされていることを確認します。
Stripe サポートにテストと本番環境用のアカウントを提供します。
Stripe サポートに送信先エンドポイントの本番環境の詳細を共有します。

送信先エンドポイントがサポートされていることを確認する

Stripe は、次のエンドポイントへの API リクエストの転送をサポートしています。

Adyen:
- [prefix]-checkout-live.adyenpayments.com/v68/payments
- [prefix]-checkout-live.adyenpayments.com/v69/payments
- [prefix]-checkout-live.adyenpayments.com/v70/payments
Braintree: payments.braintree-api.com/graphql
Checkout:
- api.checkout.com/tokens
- api.checkout.com/payments
GMO ペイメントゲートウェイ: p01.mul-pay.jp/payment/ExecTran.json
PaymentsOS: api.paymentsos.com/tokens
Spreedly: core.spreedly.com/v1/payment_methods.json
Tabapay: [prefix]/v1/clients/[ClientID]/accounts
Worldpay:
- access.worldpay.com/tokens
- secure.worldpay.com/jsp/merchant/xml/paymentService
Flexpay:
- api.flexpay.io/v1/gateways/charge
自社の PCI 準拠のトークンボールト

Stripe では、JSON/XML リクエストを受け付け、JSON/XML レスポンスを返す HTTPS ベースの API をサポートしています。送信先のエンドポイントがサポートされていない場合、または別の API 形式が必要な場合は、エンドポイントの詳細を Stripe サポートにお知らせください。貴社固有のニーズに合わせてサポートいたします。

対応可能な国

Vault and Forward API は、以下の国にのみリクエストを転送できます。

リクエスト転送機能を使用できる国

加えて、Stripe アカウントが以下のいずれかの国に登録されていることを確認してください。

アメリカ

イギリス

オーストラリア

カナダ

シンガポール

スイス

ノルウェー

リヒテンシュタイン

日本

香港

Stripe サポートにテスト用アカウントを提供する

Vault and Forward API にアクセスするには、テスト用アカウントのアカウント ID (acct_xxxx) を Stripe サポートと共有します。

送信先エンドポイントの本番環境の詳細を Stripe サポートと共有します。これには、送信先エンドポイントの URL、HTTP メソッド、ドキュメント、フィールド、リクエストヘッダー、暗号化キーが含まれます。次に Stripe は、本番環境の Vault and Forward API で使用する送信先エンドポイントを設定します。

サードパーティーの API キーを共有するには、Vault and Forward API に特化した Stripe の公開キーを使用して暗号化する必要があります。GNU Privacy Guard (PGP) を使用した公開キーのインポートから始めてください。PGP の基本を理解したら、次の PGP キーを使用して、サードパーティーの API キーを暗号化します。

Vault and Forward API PGP キー

Vault and Forward API PGP キーを使用してサードパーティーの API キーを暗号化するには、以下を行います。

プライベートキーの SHA256 ハッシュを計算し、そのハッシュ値を 16 進エンコードします。このハッシュ値をシークレットとして扱います。
Command Line
```
echo -n "{{THIRD_PARTY_SECRET_KEY}}" | sha256sum
```
SHA256 ハッシュを Stripe の公開キーで暗号化し、その結果を Base64 エンコードして、Stripe のキーを trusted とマークします。
Command Line
```
echo -n "{{SHA256_HASH}}" |  gpg -e -r AE863ADA1603150856C0A853A7B203177D034588 --always-trust | base64 > encrypted_base64.txt
```
次のコマンドを実行して、encrypted_base64.txt を確認します。
Command Line
```
cat encrypted_base64.txt | base64 -d | gpg --list-only --list-packets
```

encrypted_base64.txt に次の特性が含まれていることを確認してください。

キー ID: 27E4B9436302901A
キータイプ: RSA
キーサイズ: 4096 ビット
ユーザー ID: Forward API Secret Encryption Key (Forward API Secret Encryption Key) <multiprocessor-ext@stripe.com>

実装内容をテストする

既存のシステムが送信先エンドポイントで正しく機能することを確認するために、作成した PaymentMethod を使用して ForwardingRequest を開始します。この例では、支払い方法として pm_card_visa を使用します。

注意

Vault and Forward API は、送信先エンドポイントからのレスポンスを successとして扱い、response.body 内の送信先エンドポイントのレスポンスコードとともに 200 を返します。たとえば、送信先エンドポイントが 400 のステータスコードを Stripe に返すと、Vault and Forward API は 200 のステータスコードで応答します。 response.body には、送信先エンドポイントの 400 レスポンスとエラーメッセージが含まれます。送信先エンドポイントに送信する API リクエストを別途テストして、エラーがないことを確認します。

ダッシュボードでリクエストログを確認する

Vault and Forward API に関連するリクエストログとエラーは、ワークベンチで確認できます。さらに、List API を使用して、Stripe からログを取得できます。

セキュリティのヒント

受信するリクエストの request.headers と request.body は暗号化され、ダッシュボードで encrypted_request と表示されます。

注

サードパーティーの API エンドポイントにカード情報を転送する

Vault and Forward API を使用して、複数の決済代行業者間でカード詳細を安全に共有します。

アクセスをリクエストする

送信先エンドポイントにリクエストを転送し、Stripe のボールトからカード詳細を入力する

カード情報を収集して PaymentMethod を作成する

ForwardingRequest を作成する

注意

セキュリティのヒント

注意

カード情報を含むリクエストを転送する

注

送信先エンドポイントからのレスポンスに対応する

注意

Vault and Forward API エンドポイントを設定する

送信先エンドポイントがサポートされていることを確認する

対応可能な国

リクエスト転送機能を使用できる国

Stripe サポートにテスト用アカウントを提供する

本番環境の詳細を共有する

Vault and Forward API PGP キー

実装内容をテストする

注意

ダッシュボードでリクエストログを確認する

セキュリティのヒント