> ## 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 の連携、決済、セキュリティに関するよくある質問と回答。

## 連携

<AccordionGroup>
  <Accordion title="どの連携方法が推奨されますか?">
    素早く本番稼働させたい場合は **Checkout 連携** を使用してください。カードのセンシティブ情報を扱う必要がなく、連携の工数も最小限です。
  </Accordion>

  <Accordion title="ONE_TIME_PAYMENT と DIRECT_PAYMENT の違いは何ですか?">
    `DIRECT_PAYMENT` は初期のプロダクトで、現在ではほとんど使用されていません。新しい加盟店は `ONE_TIME_PAYMENT` を直接連携してください。

    システムレベルでは両者は同一です。違いはビジネス関係にあります。

    * **ONE\_TIME\_PAYMENT**: Waffo が PSP として、アクワイアリングサービス全体を提供 (情報フロー + 資金決済)
    * **DIRECT\_PAYMENT**: Waffo が ISV/PG として、システム接続のみを提供 (資金の取り扱いは行いません)
  </Accordion>

  <Accordion title="なぜ金額は String 型である必要があるのですか?">
    浮動小数点の精度問題を避けるためです。たとえば `0.1 + 0.2 = 0.30000000000000004` となり、金融シナリオでは受け入れられません。
  </Accordion>

  <Accordion title="通貨の精度要件は?">
    * **同通貨注文**: ほとんどの通貨は ISO 4217 に従って小数点以下 2 桁が必要ですが、`IDR`、`COP`、`KES`、`TWD` は**小数を含めてはいけません**
    * **通貨跨ぎ注文**: すべての通貨金額は ISO 4217 の精度に準拠する必要があります。例外はありません
  </Accordion>

  <Accordion title="Webhook をローカルでテストするには?">
    cloudflared や ngrok などのトンネリングツールを使用して、ローカルポートをパブリック URL として公開してください。
  </Accordion>
</AccordionGroup>

## パラメーター

<AccordionGroup>
  <Accordion title="payMethodType と payMethodName はどのように渡せばよいですか?">
    * **両方省略**: ユーザーが Waffo のチェックアウトページで決済手段を選択します
    * **カード決済**: `payMethodType="CREDITCARD,DEBITCARD"` を渡し、`payMethodName` は省略します。Waffo はユーザーが入力したカード BIN から自動的にカードスキームを判定し、1 注文内で Visa/Mastercard およびクレジット/デビットカードをサポートします
    * **VA (バーチャルアカウント)**: `payMethodType="VA"` を渡し、`payMethodName` は省略します。ユーザーはチェックアウトページで銀行を選択します
    * **特定の手段を指定する場合**: `payMethodType` と `payMethodName` の両方を渡します。正確な値はポータルの Payin ページで確認できます

    詳細なパラメーター規則は [Cashier 連携 - カスタマイズオプション](/docs/ja/developer-docs/integration/checkout/customization) を参照してください。
  </Accordion>

  <Accordion title="userEmail は省略できますか?">
    注文作成時、`userEmail` は必須項目です。

    加盟店がユーザーのメールアドレスを収集していない場合は、`userId@examples.com` 形式で送信できます (実際の `userId` に置き換えてください)。

    Waffo に連絡し、加盟店の承認のもとで Waffo がこの形式に上書きすることもできます。

    本番稼働後は実際のメールアドレスを渡すことを推奨します。`test` のような文字列や、複数ユーザーで同じメールアドレスを共用することは、リスクコントロールを誘発する可能性があるため避けてください。
  </Accordion>

  <Accordion title="orderExpiredAt は渡すべきですか?">
    任意です。このフィールドは、ユーザーがチェックアウトページで注文を送信できる時間枠を制御します (UTC+0 である必要があります)。注文が決済チャネルに送信された後は、有効期限は決済手段自体によって制御されます。一部の決済手段はチャネル側の有効期限の指定に対応しています。詳細はポータルの Payin ページを確認してください。
  </Accordion>

  <Accordion title="同通貨注文と通貨跨ぎ注文の違いは何ですか?">
    * **同通貨**: 加盟店の建値通貨とユーザーのローカル通貨が一致 (例: IDR 建て → インドネシアのユーザーが IDR で支払う)
    * **通貨跨ぎ**: 加盟店の建値通貨とユーザーの支払い通貨が異なる (例: USD 建て → インドネシアのユーザーが DANA を通じて IDR で支払う)

    通貨跨ぎ注文では、`payMethodType` または `payMethodName` のいずれかが指定されていない場合、`payMethodCountry` を渡す必要があります。`userCurrency` は任意です。
  </Accordion>

  <Accordion title="payMethodCountry はいつ渡せばよいですか?">
    チェックアウトで**特定の国**の決済手段のみを表示したい場合に渡します。省略すると、加盟店の契約に含まれるすべての国の利用可能な決済手段がすべて表示されます。

    * **グローバルカード** (CREDITCARD/DEBITCARD): このフィールドは**渡さないでください**。グローバルカードは特定の国に属しません。

    詳細なパラメーター規則は [Cashier 連携 - カスタマイズオプション](/docs/ja/developer-docs/integration/checkout/customization) を参照してください。
  </Accordion>
</AccordionGroup>

## 決済

<AccordionGroup>
  <Accordion title="orderAction の webUrl と deeplinkUrl のどちらを使用すべきですか?">
    `orderAction.actionType` で判定します。

    * `actionType = "WEB"` → `webUrl` を使用
    * `actionType = "DEEPLINK"` → `deeplinkUrl` を使用

    ほとんどの場合 `webUrl` のみ存在します。`userTerminal=APP` を渡した場合、外部認可が必要な一部のウォレット系決済手段はディープリンクを返します。

    > サンドボックスでは、シミュレーターが使用されるためディープリンクで実際のウォレットアプリを起動することはできません。この動作は本番環境で確認してください。
  </Accordion>

  <Accordion title="注文作成で orderStatus = AUTHORIZATION_REQUIRED が返ってきた場合どうすればよいですか?">
    外部認可ページにユーザーをリダイレクトしてください。URL は `orderAction` から取得できます。`actionType` に応じて `webUrl` または `deeplinkUrl` を使用してください。
  </Accordion>

  <Accordion title="UnknownStatus 例外を受け取った場合どうすればよいですか?">
    この例外は、決済チャネル呼び出し時のネットワークタイムアウトによって発生します。注文が正常に作成されたかどうかが不明な状態です。

    * **注文作成時**: エラー条件下でユーザーが決済を完了できないと確認できる場合 (例: チェックアウト URL の返却を必要とする決済手段)、注文を破棄できます。
    * **返金時**: 同じ `refundRequestId` で必ず再試行してください。リクエストを破棄してはいけません。

    [エラーハンドリング](/docs/ja/developer-docs/core-concepts/error-handling)を参照してください。
  </Accordion>

  <Accordion title="一部のサンドボックス金額で C0005、C0001、E0001 が即時返るのはなぜですか?">
    これはサンドボックスの受け入れテストと例外テスト用に用意された挙動です。現在の受け入れテンプレートでは、チャネル拒否、システム利用不可、Unknown Status を意図的に再現するために特定の金額を使用します。

    * 通常の成功 / 失敗フローだけをテストしたい場合は、これらの金額を避けてください
    * 特定の例外を再現したい場合は、[サンドボックスシミュレーター](/docs/ja/developer-docs/tools-and-references/developer-tools/sandbox-simulator) にある対応金額を使用してください
    * `A0011` と返金 `A0003` は特殊金額ではなく、リクエストパラメーターの組み合わせで発生します
  </Accordion>

  <Accordion title="ユーザーの決済は成功したのに Webhook を受信しません。どうすればよいですか?">
    1. `notifyUrl` が HTTPS でパブリックに到達可能か確認
    2. コールバックのポートが 80 または 443 であることを確認 (Waffo 本番は標準ポートのみ受け入れます)
    3. 応答ボディが `{"message": "success"}` で、Content-Type が `application/json` であることを確認
    4. 応答に `X-SIGNATURE` ヘッダーが含まれていることを確認
    5. 照会 API を能動的に呼び出して最新ステータスを取得
    6. それでも受信しない場合は Waffo テクニカルサポートにお問い合わせください
  </Accordion>

  <Accordion title="照会 API は必須ですか?">
    強く推奨します。ユースケース:

    * ユーザーが成功/失敗ページに到達したときに能動的に照会して、最もスムーズな体験を提供する
    * 過去の注文の結果を取得する
    * Webhook の署名検証が失敗したときのフォールバックとして照会 API を使用する
  </Accordion>

  <Accordion title="複数の決済手段を同時に使用できますか?">
    `payMethodType` / `payMethodName` を指定しない場合、チェックアウトには利用可能なすべての決済手段が表示され、ユーザーが選択できます。
  </Accordion>
</AccordionGroup>

## 署名とセキュリティ

<AccordionGroup>
  <Accordion title="署名検証が失敗する一般的な原因は何ですか?">
    1. **秘密鍵のフォーマット誤り**: 鍵は PKCS#8 フォーマットでなければなりません
    2. **署名対象の誤り**: HTTP ボディ全体に署名する必要があり、一部のフィールドだけに署名することはできません
  </Accordion>

  <Accordion title="RSA 鍵の最小要件は何ですか?">
    2048 ビットの RSA 鍵ペア、署名アルゴリズムは SHA256WithRSA (RSASSA-PKCS1-v1\_5 + SHA-256) です。
  </Accordion>

  <Accordion title="サンドボックスと本番環境で同じ鍵セットを使用できますか?">
    推奨しません。サンドボックスと本番では、異なる API キーと RSA 鍵ペアを使用してください。
  </Accordion>
</AccordionGroup>

## アプリ連携

<AccordionGroup>
  <Accordion title="加盟店 App にチェックアウトを組み込む際の注意点は?">
    * App と WebView が外部 App または外部ブラウザページを開けることを確認
    * App と WebView がダウンロード、コピー、長押し保存に対応していることを確認。QR、OTC、銀行振込系の決済手段ではこれらの機能が必要になることがあります
    * ネイティブ App と WebView の間で URL を受け渡す際、query パラメータが保持されることを確認
    * WebView 経由で読み込む場合は、`userTerminal` を `APP` に設定
    * 詳細な制限については、[決済手段別の連携注意事項](/docs/ja/developer-docs/tools-and-references/references/payment-method-integration-notes)を参照してください
  </Accordion>

  <Accordion title="加盟店が Google Pay / Apple Pay を独自に連携することはできますか?">
    推奨しません。Waffo チェックアウトに組み込まれている GP/AP 機能を直接使用してください。

    | 比較項目              | Waffo チェックアウトを利用 | 独自連携    |
    | ----------------- | ---------------- | ------- |
    | GP/AP デベロッパーアカウント | 不要               | 必要      |
    | ドメイン登録および検証       | 必要               | 必要      |
    | 暗号化証明書/鍵の管理       | Waffo が管理        | 加盟店が管理  |
    | サーバーサイドのトークン処理/復号 | Waffo が処理        | 加盟店が管理  |
    | PCI DSS 準拠        | 不要               | 必要な場合あり |
    | チェックアウト UI        | Waffo が提供        | 加盟店が構築  |
    | **連携の複雑さ**        | **低**            | **高**   |

    独自連携が必要な特別な理由がある場合は、Waffo テクニカルサポートに連絡し、詳細な連携ガイドをご請求ください。
  </Accordion>

  <Accordion title="PayMe 決済は App を起動しますか?">
    はい、PayMe App を起動します。ユーザーがインストールしていない場合は、ダウンロードを促されます。
  </Accordion>
</AccordionGroup>