> ## 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.

# クロスカレンシーのサブスクリプションと Portal の FAQ

> ある通貨で価格を設定し別の通貨で課金するサブスクリプションで FX がどのように機能するか、換算後の金額とレートがどこで見られるか、マーチャント Portal でサブスクリプション・課金・返金をどのように探すかを説明します。

ある通貨で価格を設定し別の通貨で課金するサブスクリプションと、それらをマーチャント Portal で再び見つける方法について説明します。

金額の設定は[サブスクリプションの金額と期間ごとのスケジューリング FAQ](/docs/ja/support/subscription-amount-scheduling-faq)に、作成のルールは[サブスクリプションの作成と検証 FAQ](/docs/ja/support/subscription-creation-validation-faq)にあります。単発の注文における一般的な FX の挙動は[為替レート FAQ](/docs/ja/support/exchange-rates-faq)にあります。

## クロスカレンシーのサブスクリプションでは、作成時に為替レートが固定されますか？

**いいえ。** クロスカレンシーのサブスクリプションは**期間ごとに個別に換算されます**。作成時に固定されるものはなく、サブスクリプションの存続期間を通じて単一のレートが適用されることもありません。

実務上の意味は次のとおりです。

| | 挙動 |
| - | - |
| レートの適用範囲 | 課金期間ごとに 1 回の換算 |
| レートが決まるタイミング | その期間の課金が Waffo によって**開始された**とき |
| 課金日との関係 | レートは課金が開始された瞬間に属し、課金が確定する暦日とは**必ずしも一致しません** |
| 期間をまたいだレートの再利用 | なし |
| 加盟店側の金額 | 変わりません — 貴社の価格通貨で同じ金額を請求し続けます |
| ユーザー側の金額 | レートの変動に応じて期間ごとに変わります |

したがって、貴社の通貨で固定金額に設定されたサブスクリプションは、**期間によって異なる現地通貨の金額**を表示します。これは価格設定の誤りではなく正しい挙動です。ユーザー側の金額が一定であると仮定した照合を作らないでください。また、将来の期間について固定の現地通貨価格をユーザーに提示しないでください。

ある期間の課金が開始された時点で通貨ペアのレートが取得できない場合、その期間は古いレートで課金されることはありません。不明なレートで換算するのではなく、試行自体が失敗します。

## クロスカレンシーの期間で、ユーザーは実際に何を支払いますか？

ユーザーの通貨で課金される金額は、換算後の金額に**該当するユーザー手数料を加えたもの**で、ユーザーの通貨の精度に丸められます。両方の部分がレートとともに期間ごとに再計算されるため、ユーザー側の合計は期間ごとの数値です。

貴社側の帳簿は影響を受けません。サブスクリプションの `amount`（または期間ごとに予定された金額）は貴社の価格通貨のままです。

## 換算後の金額と使用されたレートはどこで見られますか？

サブスクリプション単位ではなく、課金単位で見られます。サブスクリプションの照会レスポンスは、ユーザーが課金される通貨である `userCurrency` を報告しますが、換算後の金額、レート、手数料の内訳は含みません。

それらを得るには、個別の課金を参照してください。

| 欲しいもの | どこで得るか |
| - | - |
| その期間の課金 ID | `paymentDetails=1` を指定した `/api/v1/subscription/inquiry` — 各エントリに `acquiringOrderId` と `period` があり、その期間に追加の課金があった場合は `topupDetails` のリストも含まれます |
| ユーザーが実際に支払った金額 | その `acquiringOrderId` に対する注文照会：`finalDealAmount` と `userCurrency` |
| その期間の貴社側の請求金額 | 注文照会：`orderAmount` と `orderCurrency` |
| 決済時にユーザーに表示されたレートとユーザー手数料 | 注文が認証待ちの間の注文照会の `orderAction.actionData` — `paymentAmount`、`paymentCurrency`、`userFeeAmount`、`userFeeCurrency`、`exchangeRate` を含みます。自社でチェックアウトを描画する加盟店向けです。 |

`finalDealAmount` は、通貨が異なる場合やユーザー手数料が適用される場合に `orderAmount` と異なります。その差こそがこのフィールドの存在意義であり、ユーザーの銀行の明細と照合すべき数値です。

Portal では、同じ情報がサブスクリプション詳細ページではなく、（サブスクリプションの決済履歴から到達できる）個別の**決済詳細**ページにあります。

## ある Order ID がどのサブスクリプションに属するか調べられますか？

はい。**Subscription → Agreements** の検索ボックスには軸のセレクターがあり、**Order ID** はその選択肢の 1 つです。注文 ID を入力すると、その課金が属するサブスクリプションが返ります。

その一覧における検索軸の全体は次のとおりです。

| 軸 | 備考 |
| - | - |
| Subscription Id | 既定の選択 |
| User Id | 貴社の `merchantUserId` |
| User Email | |
| Card Last 4 Digits | ちょうど 4 桁でなければならず、そうでなければ検索結果は返りません |
| Order ID | 逆引き — 課金が属するサブスクリプションを見つけます |

サブスクリプションの課金ではない注文 ID は、単に**結果なし**を返します。単発の注文には指し示すサブスクリプションがないためです。存在しない ID や他の加盟店に属する ID でも同様です。

検索ボックスと並んで、一覧は **Period**、**Payment Method**、**Status**（9 つのサブスクリプションステータスすべてを選択可能）、**Created Datetime** で絞り込めます。Created Datetime は必須で、選択できる期間は約 2 か月に制限されているため、選んだ期間の外で作成されたサブスクリプションは、どの検索軸を使っても表示されません。検索で想定外に結果が返らない場合は、まず日付の範囲を広げてください。

## Portal のサブスクリプション一覧には何が表示されますか？

| 列 | 備考 |
| - | - |
| Subscription Id | Waffo の ID |
| Merchant Subscription Id | 貴社の ID |
| Period Interval | 期間タイプ + 間隔からサイクルとして描画されます |
| Payment Method | |
| Card Number | マスク済み。カード方式のサブスクリプションのみ |
| User Id | |
| User Email | |
| Subscription Amount | サブスクリプションの通貨とともに |
| Status | |
| Created Datetime | |
| Action | サブスクリプション詳細ページを開きます |

行をダブルクリックすると、Action のリンクと同じ詳細ページが開きます。

## Portal でサブスクリプションを閲覧・キャンセルできるのは誰ですか？

Agreements 一覧とサブスクリプションの詳細ページの閲覧は、Subscription メニューにアクセスできる Portal のロールで利用できます。

**キャンセル**にはさらに、ロールにサブスクリプションのキャンセル権限が必要です。したがって読み取り専用のユーザーにはサブスクリプションは見えてもキャンセルボタンは表示されません。権限のほかに、キャンセルボタンは Waffo がそのサブスクリプションをキャンセル可能と示している場合にのみ表示されます。すでに最終ステータスに達したサブスクリプションにはキャンセルのアクションは提供されません。キャンセルは確認を求めた後すぐに実行されます。取り消しはできず、再度契約するには新しいサブスクリプションを作成することになります。

## 1 つのサブスクリプションに紐づくすべての返金や課金を一覧できますか？

はい。どちらの取引一覧でも可能です。**Transactions → Refunds** と **Transactions → Payments** の検索軸セレクターには **Subscription Id** が含まれます。それを選んでサブスクリプション ID を貼り付けると、一致するすべてのレコードが返ります。

どちらの一覧にも **Subscription Id** の列があり、サブスクリプションのトラフィックと単発のトラフィックをひと目で区別できます。

| ケース | 列の値 |
| - | - |
| レコードがサブスクリプションに属する | サブスクリプション ID |
| サブスクリプション由来でない単発の注文 | `-` |

これを前提に業務プロセスを作る前に知っておくべき挙動：

* 存在しない、または他の加盟店に属するサブスクリプション ID は、エラーではなく**空の一覧**を返します。したがって、結果が空であることはそのサブスクリプションに返金がないことの証明にはなりません。
* この方法で絞り込んだ返金レコードには、貴社が開始した返金**と**異議申し立てに起因する返金の両方が含まれます。このフィルターは由来を区別しません。
* 単発の返金にはサブスクリプション ID がないため、このフィルターで一致することはありません。
* Refunds の一覧を直接開くと独自の既定の期間（おおむね直近 3 か月）が適用されるため、より古い返金を探すときは範囲を広げてください。

## サブスクリプションからその返金へどのように移動しますか？

サブスクリプションの詳細ページには、そのサブスクリプションの **Refund count** が表示されます。件数が 0 より大きい場合はリンクになっており、クリックすると Subscription Id のフィルターが適用された状態で **Transactions → Refunds** が開きます。

その遷移で適用される日付の範囲は、**サブスクリプションの開始日から現在まで**です。これは意図的に広く取られており、直近の一部ではなくサブスクリプションの存続期間全体をカバーします。件数が 0 の場合はリンクのない通常のテキストです。

2 つの注意点：

* 件数は由来に関わらずそのサブスクリプションのすべての返金を集計し、絞り込まれた一覧の表示と一致します。
* サブスクリプションの課金が複数の通貨にわたる場合、この件数は合計金額ではなく**返金の件数**です。金額は一覧そのものから読み取ってください。

## 期間のフィルターに「Yearly」の選択肢がないのはなぜですか？

`YEARLY` というサイクルが存在しないためです。期間のフィルターは 2 段階のピッカーで、上位の段階は Waffo がサポートするちょうど 3 つのサイクルタイプ（**Weekly**、**Monthly**、**Daily**）、下位の段階は間隔です。

年次のサブスクリプションは間隔 `12` の `MONTHLY` なので、絞り込みもそのように行います。**Monthly** を選び、次に **12** を選んでください。四半期は Monthly + 3、半年は Monthly + 6、隔週は Weekly + 2 です。マッピングの全体は[サブスクリプションの作成と検証](/docs/ja/support/subscription-creation-validation-faq)にあります。

同じ形はエクスポートされたファイルにも現れ、サイクルは名前付きのプランではなく間隔 + 単位（`1 Month`、`12 Month`、`3 Week`）として描画されます。ページとエクスポートが同じ文言を使うのは意図的で、絞り込みに使った値がそのままファイル内で見つかる値になります。

## サブスクリプションの一覧をエクスポートするには？ファイルはどこに現れますか？

**Subscription → Agreements** でフィルターを設定し、**Export** を使ってください。エクスポートは直接のダウンロードではなく**サーバー側のジョブ**です。送信すると **Subscription → Reports** タブへ移動し、そこにエクスポートの記録がステータスとともに一覧され、準備ができるとダウンロードできます。

| エクスポートのステータス | 意味 |
| - | - |
| Wait Export | キューに入っています |
| Need Retry | ジョブが失敗し、再試行されます |
| Success | ダウンロードできます |
| Failed | ファイルを生成できませんでした |

レコードが最終状態でない間、Reports タブは自動で更新されるので、再読み込みせずに開いたままにしておけます。

エクスポートは**ボタンを押した時点で適用されていたフィルター**を使用します。必須の作成日時の範囲も含まれます。「すべてをエクスポート」ではありません。

## Export ボタンがグレーアウトしているのはなぜですか？行数の上限はありますか？

3 つの異なる条件があり、それぞれメッセージが異なります。

| 表示 | 理由 | 対処 |
| - | - | - |
| ボタンが無効 | すでに実行中のエクスポートがあります。同時に 1 件のみです。 | Reports タブのレコードが最終ステータスになるまで待ってください。 |
| 「The current query data is empty」 | 適用したフィルターに一致するサブスクリプションがありません。 | フィルターを広げてください。原因はたいてい作成日時の範囲です。 |
| 「Too many records to export, please narrow your query」 | 結果セットがエクスポートの上限を超えています。 | 日付の範囲を狭めるかフィルターを追加し、分割してエクスポートしてください。 |

上限そのものはサーバー側で強制され、Portal には表示されません。上限を計算しようとするのではなく、メッセージをシグナルとして扱ってください。作成日時で分割するのが、大量の履歴を取り出す確実な方法です。このフィルターはいずれにせよ必須だからです。

## 取引一覧から自動更新の課金を見分けるには？

**Transactions → Payments** には **Card Transaction Type** のフィルターがあり、2 つの値を持ちます。

| 値 | 意味 |
| - | - |
| `CIT` | 顧客起点 — 顧客が同席し、自ら決済を承認したもの |
| `MIT` | 加盟店起点 — 保存されたマンデートに対してバックグラウンドで課金されたもの |

自動更新は `MIT` です。サブスクリプションの最初の課金や、顧客がチェックアウトで承認したプラン変更は `CIT` です。

引っかかりやすい挙動が 1 つあります。**Card Transaction Type の列は、この項目で絞り込んだときにのみ値が入ります**。絞り込みのないクエリでは全行が空欄になります。これはデータの欠落ではなく、絞り込んだクエリだけが要求する射影です。したがって CIT/MIT を見るには、CIT/MIT で絞り込む必要があります。

このフィルターはカードのトラフィックに適用されます。決済手段に関わらず「この行はそもそもサブスクリプションの一部か」を知りたい場合は、上記の **Subscription Id** の列とフィルターを使ってください。

## サブスクリプションにある、課金期間ではない追加の行は何ですか？

サブスクリプションには、その期間のいずれでもない課金が紐づくことがあります。それらは他のサブスクリプションのトラフィックと同様にサブスクリプションの ID とともに取引一覧に現れ、注文照会のレスポンスでは `subscriptionInfo.subscriptionEvent` によって区別されます。

| `subscriptionEvent` | 何か | 期間番号を持つか |
| - | - | - |
| `PERIOD_CHARGE` | 課金期間 | はい |
| `USER_ADD_PAYMENT_METHOD` | 顧客が決済手段を追加した際に発生するゼロ金額のオーソリ | いいえ |
| `TOPUP_CHARGE` | 独自の期間ではなく、既存の期間の内側で取られた追加の課金 | 独自の期間ではなく、その課金が行われた期間を持ちます |

これを正しく読むことは照合にとって重要です。

* **ゼロ金額の検証行も実在の注文です。** 取引一覧に現れ、注文 ID を持ち、何も集金しません。サブスクリプションが期間の課金しか生まないと仮定するのではなく、金額またはイベントで収益レポートから除外してください。
* **`TOPUP_CHARGE` は期間ではありません。** トライアルの印も、独自の期間の開始・終了も持ちません。すでにそれらを持つ期間の内側に属するからです。`paymentDetails=1` を指定した `/api/v1/subscription/inquiry` では、それが行われた**期間の下にネストされて**返され、その期間のエントリの `topupDetails` リストになります（各項目はトップアップの `acquiringOrderId`、`topupRequest`、`topupAmount`、`orderCurrency`、`orderStatus` を持ち、その期間にトップアップがなければリストは存在しません）。したがって、サブスクリプションの総集金額は、トップレベルの行の合計だけではなく、期間の金額**に**その `topupDetails` を加えたものです。
* Portal とホスト型の管理ページでは、これらの追加の課金は属する期間に対して **`period-n`** の番号で表示されます。`5-2` は期間 5 の内側で受け付けられた 2 件目のトップアップを意味します。素の期間番号を持つのは期間の行だけで、トップアップの行の期間の列は `-` です。課金履歴が期間ごとにきれいに 1 行ずつではなく、期間の後に追加の行が続く形になり得るのはこのためです。

トップアップは `topupInfo` ブロックを指定した `/api/v1/subscription/update` で作成します。それが継続課金の金額に何をもたらすかは金額のページを参照してください。

これらを見つけるには、`acquiringOrderId` で注文を照会し `subscriptionInfo` を読んでください。これら専用の一覧エンドポイントはありません。


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