# 自社のトークンボールトにカード情報を転送する

社内ボールトを Stripe に保存されたカード情報で更新します。

[PaymentMethod](https://docs.stripe.com/api/payment_methods.md) を作成し、トークンボールトに支払い方法を[転送](https://docs.stripe.com/api/forwarding/request.md)します。

> #### アクセスをリクエストする
> 
> Stripe の転送サービスを使用するには、[Stripe サポート](https://dashboard.stripe.com/login?redirect=https%3A%2F%2Fsupport.stripe.com%2Fcontact%2Femail%3Fquestion%3Dother%26topic%3Dpayment_apis%26subject%3DHow%2520can%2520I%2520access%2520the%2520Vault%2520and%2520Forward%2520API%3F%26body%3DWhat%2520endpoint%28s%29%2520would%2520you%2520like%2520to%2520forward%2520card%2520details%2520to%3F)にお問い合わせください。
自社のトークンボールトにカード情報を転送する (See full diagram at https://docs.stripe.com/payments/forwarding-token-vault)
## PaymentMethod を作成する

カード情報を収集して、Vault and Forward API で使用するために Stripe に送信するには、Payment Element を使用して [PaymentMethod](https://docs.stripe.com/payments/finalize-payments-on-the-server-legacy.md?type=payment#create-pm) を作成します。PaymentMethod を作成すると、カード情報は Stripe の PCI 準拠のボールトに自動的に保存されます。自社で構築済みのフロントエンドがある場合でも、[PaymentMethod を直接作成する](https://docs.stripe.com/api/payment_methods/create.md)ことで Vault and Forward API を引き続き使用できます。

## ForwardingRequest を作成する

サーバーのリクエストエンドポイントに PaymentMethod ID を渡します。Stripe は、Stripe のボールトからカード認証情報を正常に取得できることを確認するために、テスト用エンドポイント (`https://forwarding-api-demo.stripedemos.com/tokens`) とテスト用支払い方法 (`pm_card_visa`) を提供しています。システムを社内ボールトに連結する前に、このテスト用エンドポイントにカード詳細を送信します。

```curl
curl https://api.stripe.com/v1/forwarding/requests \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d payment_method=pm_card_visa \
  --data-urlencode "url=https://forwarding-api-demo.stripedemos.com/tokens" \
  -d "request[headers][0][name]=Authorization" \
  -d "request[headers][0][value]=Bearer eyJhbGciOiJIUzI1NiJ9.Zm9yd2FyZGluZy1hcGktZGVtbw.2qoK37CNBmMjMDRERSYUSE-YrjsTgGhHnxMeqOxjrAg" \
  --data-urlencode "request[body]={\"metadata\":{\"reference\":\"Your Token Reference\"},\"card\":{\"number\":\"\",\"exp_month\":\"\",\"exp_year\":\"\",\"cvc\":\"\",\"name\":\"\"}}" \
  -d "replacements[0]=card_number" \
  -d "replacements[1]=card_expiry" \
  -d "replacements[2]=card_cvc" \
  -d "replacements[3]=cardholder_name"
```

## 社内のトークンボールトのエンドポイントを設定する

Vault and Forward API からプライマリーアカウント番号 (PAN) を受信するには、トークンボールトが次の仕様に従っている必要があります。

### PCI 準拠

コンテナが PCI に準拠していることを確認し、Stripe のサポートに有効な PCI 準拠証明書を提供してください。この構成証明は毎年更新する必要があります。

### API 要件

ボールトには、JSON を受け入れて JSON レスポンスを返す HTTPS ベースの API が含まれている必要があります。XML や ISO 8583 など、他の形式には対応していません。

API には単一の静的 URL が含まれていることを確認してください。セキュリティ対策のために Vault and Forward API でこれを設定します。リクエスト間で URL を変更することはできません。

### 認証

Vault and Forward API を使用して、ベアラートークンを含む HTTP ヘッダーベースの認証スキームを使用して、ボールトによる認証を行います。

転送されるすべての API コールには、ボールトで認証するための認証ヘッダーが含まれていることを確認してください。

クライアント証明書の認証には対応していません。

### リクエストヘッダー

ボールトに転送されるリクエストに追加のヘッダーを含めることができます。ただし、ボールトの設定でこれらのヘッダーが明示的にサポートされていることを確認する必要があります。実装を開始する前に、Stripe サポートに連絡して、必要な追加ヘッダーが正しく設定されていることを確認してください。さらに、ヘッダーには、ベアラートークンを除き、機密情報が含まれていないことを確認してください。

### リクエスト本文

ボールトが次の形式の JSON オブジェクトを受信することを確認します。

```javascript
{
  "card": {
    "number": "4242424242424242",
    "exp_month": "12",
    "exp_year": "2023",
    "name": "John Doe",
    "cvc": "123"
  },
  "metadata": {
    // Put your additional fields here
  }
}
```

必要に応じて、このリクエストのメタデータキーに追加のフィールドを含めることができます。追加処理を行わずにそれらを渡します。

Vault and Forward API は、復号化されたデータを次のフィールドに配置します。

| フィールド名      | タイプ | 説明                                                                                                    |
| ----------- | --- | ----------------------------------------------------------------------------------------------------- |
| `number`    | 文字列 | カードの 15 桁または 16 桁の PAN。                                                                               |
| `exp_month` | 文字列 | カードの有効期限月を表す 2 桁の数字。                                                                                  |
| `exp_year`  | 文字列 | カードの有効期限を表す 4 桁の数字。                                                                                   |
| `name`      | 文字列 | カード保有者名。                                                                                              |
| `cvc`       | 文字列 | カード確認値。これは、トークン化後の Stripe への最初の API リクエストでのみ使用できるようになります。Stripe はこの情報を短期間でシステムから削除します。この値を保存しないでください。 |

ボールトでこれらすべてのフィールドに対応する必要はありません。Vault and Forward API は、送信するリクエスト本文に値が存在する場合にのみ、リクエストに値を配置します。さらに、リクエスト本文には追加のフィールドを含めることができ、Vault and Forward API はそれを受信側のエンドポイントに渡します。

### レスポンス本文

Vault and Forward API は、ボールトからのレスポンス本文を必要としません。本文を提供すると、それは Vault and Forward API の呼び出し元に返されます。レスポンスに機密情報フィールドを含めることはできません。

### レスポンスコード

Vault and Forward API は、すべてのレスポンスを「成功」として扱い、トークンボールトエンドポイントから送信されたものと同じレスポンスコードを、Stripe を介して呼び出し元に返します。たとえば、アップストリームが `400` のステータスコードを Stripe に返すと、Vault and Forward API は `200` のステータスコードで応答します。レスポンス本文には、アップストリームの `400` レスポンスとエラーメッセージが含まれます。

## トークンボールトで実装を確認する

ボールトエンドポイントを含む構築済みのシステムが適切に機能することを確認するために、Stripe のエンドポイントをお客様のボールト設定に置き換えます。次に、作成した PaymentMethod を使用して ForwardingRequest を開始します。

このリクエストには 15 秒のタイムアウトがあります。

## 最新の認証情報でトークンボールトを更新する

Stripe Webhook をリッスンして、[カードが更新されたかどうかを確認](https://docs.stripe.com/payments/cards/overview.md#automatic-card-updates)します。Vault and Forward API を呼び出して、更新された PaymentMethod をトークンボールトに転送します。