サードパーティーの API エンドポイントにカード情報を転送する
Vault and Forward API を使用すると、カード情報をトークン化して Stripe の PCI 準拠のボールトに格納し、そのデータをサポートされる決済代行業者またはエンドポイントに振り分けることができます。API を使用して以下を実行できます。
- 複数の決済代行業者に対して Payment Element を使用します。
- Stripe を、決済代行業者間でのカード情報のプライマリボールトとして使用します。
- 自社で構築済みの PCI 準拠のトークンボールトにカード情報を転送します。
アクセスをリクエストする
To gain access to use Stripe’s forwarding service, contact Stripe support.
Forward requests to destination endpoints and populate card details from Stripe’s vault
カード情報を収集して PaymentMethod を作成する
To collect card details, use the Payment Element to create a PaymentMethod. After you create a PaymentMethod, we automatically store card details in Stripe’s PCI compliant vault. If you have your own frontend, you can still use the Vault and Forward API by creating a PaymentMethod directly.
Typically, you can only reuse PaymentMethods by attaching them to a Customer. However, the Vault and Forward API accepts all PaymentMethod objects, including those not attached to a customer. Similarly, the Vault and Forward API doesn’t confirm or capture PaymentIntents. As a result, you might unintentionally use them to capture a payment on Stripe that was already captured on another processor.
セキュリティコードは一定期間が過ぎると、また 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
にある送金先エンドポイントに該当するカード番号フィールドが置き換えられます。
送信先エンドポイントが求めるデータに基づいてリクエストの形式を設定する必要があります。下記の例では、送信先エンドポイントは、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}}' }
注
If you’re using the Vault and the Forward API to make an authorization request, you must handle any post-transaction actions, such as refunds or disputes, directly with the third-party processor. Contact Stripe support if you require 3DS authentication across your multiprocessor setup.
送信先エンドポイントからのレスポンスに対応する
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 エンドポイントを設定するには、以下を行う必要があります。
- 送信先エンドポイントがサポートされていることを確認します。
- Provide a test and production account with Stripe support.
- Share the production details for the destination endpoint with Stripe support.
送信先エンドポイントがサポートされていることを確認する
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
- Worldpay:
access.worldpay.com/tokens
- 自社の PCI 準拠のトークンボールト
Vault and Forward API は、以下の国にのみリクエストを転送できます。
対応可能な国
We can support HTTPS-based APIs that accept JSON requests and return JSON responses. If we don’t already have support for destination endpoint or you require a different API format, provide the details of the endpoint with Stripe support so we can support your destination endpoint.
Provide test accounts to Stripe support
To access the Vault and Forward API, share the account IDs (acct_xxxx
) for your test accounts with Stripe support.
本番環境の詳細を共有する
Share the production details for destination endpoint with Stripe support. These include the following for destination endpoint: URL, HTTP method, documentation, fields, request headers, and encryption keys. Stripe then sets up destination endpoint for use with the Vault and Forward API in live mode.
サードパーティーの 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 Lineecho -n "{{THIRD_PARTY_SECRET_KEY}}" | sha256sum
SHA256
ハッシュを Stripe の公開キーで暗号化し、その結果をBase64
エンコードして、Stripe のキーをtrusted
とマークします。Command Lineecho -n "{{SHA256_HASH}}" | gpg -e -r AE863ADA1603150856C0A853A7B203177D034588 --always-trust | base64 > encrypted_base64.txt
次のコマンドを実行して、
encrypted_base64.txt
を確認します。Command Linecat 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
と表示されます。