> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 認証・署名 FAQ

> Waffo API 認証に関するよくある質問への回答：API キーの取得場所、リクエストとレスポンスの署名の仕組み、Webhook の検証、A0001/A0002 のトラブルシューティング、RSA 鍵の生成方法。

マーチャントから最もよく寄せられる認証と署名に関する質問です。完全な仕様は
[Acquiring API Specification](/docs/api-reference/introduction) をご覧ください。

## API キーはどこで取得できますか？

API キーは、マーチャントのオンボーディング時に Waffo から提供されます。
**Merchant Portal → Integration**（**Dev** または **Admin** ロールが必要）で
いつでも確認できます。すべての API リクエストで `X-API-KEY` ヘッダーに載せて送信してください。
サンドボックスと本番環境では API キーが異なります。本番移行時には API ドメインとキーの両方を
切り替えてください（[本番移行チェックリスト](/docs/ja/developer-docs/getting-started/go-live)を参照）。

## 自社システムと Waffo の間でやり取りされる鍵は何ですか？

オンボーディング時に、貴社と Waffo は **RSA 公開鍵**を交換します。秘密鍵はそれぞれが自身で保管します。

| 鍵 | 保持者 | 用途 |
| - | - | - |
| マーチャント秘密鍵 | 貴社（サーバー側のみ） | 貴社のリクエストおよび Webhook レスポンスへの署名 |
| マーチャント公開鍵 | 貴社が **Merchant Portal → Integration** で設定 | Waffo が貴社の署名を検証 |
| Waffo 秘密鍵 | Waffo | Waffo のレスポンスおよび Webhook 通知への署名 |
| Waffo 公開鍵 | 貴社が **Merchant Portal → Integration** からコピー | 貴社が Waffo の署名を検証 |

秘密鍵を Waffo に送信したり、リポジトリにコミットしたりしないでください。

## API リクエストにはどのように署名しますか？

署名アルゴリズムは **SHA256WithRSA** です。マーチャントの RSA 秘密鍵を使ってリクエストの
**ボディメッセージ全体**に署名し、その結果を `X-API-KEY` とともに `X-SIGNATURE` ヘッダーで
送信します。Waffo は Portal で設定されたマーチャント公開鍵で署名を検証し、検証に失敗した場合は
署名無効エラーでリクエストを拒否します。すべてのリクエストは HTTP POST で、
`Content-Type: application/json`（UTF-8）、TLS 1.2 以上で送信します。

## Waffo の API レスポンスはどのように検証しますか？

Waffo はすべてのレスポンスボディに自身の秘密鍵で署名し、その署名をレスポンスの `X-SIGNATURE` で
返します。レスポンスを処理する前に、**Waffo 公開鍵**（Merchant Portal → Integration から取得）を
使って SHA256WithRSA で検証してください。検証に失敗した場合は、調査のうえ Waffo にご連絡いただき、
**問題が解決するまで新しい取引の送信を停止してください**。貴社側でレスポンスを受け入れられなかった場合でも、
Waffo はすでにリクエストを処理している可能性があります。

## Webhook 通知はどのように検証しますか？

レスポンスと同じ仕組みです。各 Webhook リクエストには、Waffo 秘密鍵で署名された `X-SIGNATURE` が
付いています。Waffo 公開鍵で検証してください。**生のリクエストボディ**に対する SHA256WithRSA
（JSON をパースして再文字列化しないこと）で、署名は Base64 からデコードします。イベントを処理する前に
必ず検証してください。SDK の `handleWebhook()` がこれを代行します。完全な手順と Node.js/Go の例は
[Webhook 署名検証](/docs/ja/developer-docs/webhook/signature-verification)にあります。

## Waffo への Webhook レスポンスにも署名は必要ですか？

はい。Waffo のコールバックに対する貴社のレスポンスにも `X-SIGNATURE` ヘッダーを付け、マーチャント秘密鍵で
ボディメッセージ全体に署名します。ボディは処理結果に応じて
`{"message": "success / failed / unknown"}` とします。

## A0001 と A0002 の違いは何ですか？

| コード | 意味 | HTTP ステータス | 指し示すもの |
| - | - | - | - |
| `A0001` | Invalid Api secret key | 401 | 送信した `X-API-KEY` がこの環境では有効でない |
| `A0002` | Invalid signature | 401 | `X-SIGNATURE` が設定済みの公開鍵に対する検証に失敗した |

## A0001 が返されます。何を確認すべきですか？

1. `X-API-KEY` ヘッダーが存在し、**Merchant Portal → Integration** に表示されているキーと一致していること。
2. サンドボックスのキーを本番ドメインに送っていない（またはその逆でない）こと。環境ごとにキーは別です。

## A0002 が返されます。何を確認すべきですか？

1. **ボディメッセージ全体**に署名していること。送信するバイト列そのものであり、再シリアライズしたコピーではないこと。
2. マーチャントの**秘密**鍵を使い、**SHA256WithRSA** で署名していること。
3. **Merchant Portal → Integration** で設定したマーチャント**公開**鍵が、その秘密鍵と対応していること。
4. 本番移行後は本番用の鍵ペアを使っていること。サンドボックスの事前生成鍵を再利用しないこと。

## RSA 鍵ペアはどのように生成しますか？

仕様書の付録にあるとおり、openssl（[https://www.openssl.org/source）を使用します。](https://www.openssl.org/source）を使用します。)

```bash theme={null}
# generate private key
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -out merchant_private_key.pem

# generate public key
openssl rsa -in merchant_private_key.pem -pubout > merchant_public_key.pem
```

[本番移行チェックリスト](/docs/ja/developer-docs/getting-started/go-live)には、PEM のラッパーを取り除いて
Portal の公開鍵フィールドが求める 1 行の Base64 値にする方法も記載されています。

## チームの誰が Integration ページにアクセスできますか？

API キーと Waffo 公開鍵の閲覧、およびマーチャント公開鍵の設定には、いずれも Merchant Portal の
**Dev** または **Admin** ロールが必要です。

## 複数のマーチャントアカウントを持っています。1 つの API キーをすべてのアカウントで使えますか？

いいえ。各 API キーは単一のマーチャントアカウント（MID）に紐づいています。アカウント A のキーで認証した
リクエストはアカウント A のデータにしか操作できません。アカウント B に属する注文をそのキーで照会すると、
キー自体は有効であっても失敗します。複数の MID を運用する場合は、アカウントごとに 1 つの鍵ペアを保持し、
常にその注文を作成した MID のキーで呼び出してください。

関連する照会上の落とし穴：**サブスクリプションの注文は、ワンタイム決済の Order Inquiry では返されません**。
サブスクリプションとその決済注文は、サブスクリプション専用の照会 API で照会してください。

## SDK の決済手段照会で `payMethods` が空配列で返るのはなぜですか？

SDK 経由で決済手段の設定を照会すると、結果の `payMethods` フィールドは常に空配列になります。これは想定どおりの
動作です。実際のデータは **`payMethodDetails`** にあり、契約済みの決済手段ごとに 1 エントリで、
`productName`、`payMethodName`、`country`、`currentStatus`（その手段が現在利用可能かどうか）を含みます。
`payMethodDetails` を走査して、国ごとに契約上で実際に有効な決済手段のリストを構築してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.