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

# 税、割引、Point Topup のエッジケース

> 扱いにくいケース：複数回の部分返金にまたがって税がどのように返金され、合計が正確に一致するのか、税計算の失敗がどんなときに注文を止め、どんなときに非課税のまま注文が進むのか、割引レコードの各状態が何を意味し、どの注文イベントがそれを動かすのか、1 件の注文で 2 つの割引を併用できない理由、そして未払いの Point Topup 注文が在庫をどれだけ確保し続けるのか。

このページで 3 つの主題が交わるのは、それらが 1 つの性質を共有しているためです。通常のケースは
単純で、資金がおかしくなるのはエッジケースだということです。それぞれにメインのページがあり、
このページはそれを繰り返すのではなく補足します。

* [手数料と税の取り扱い](/docs/ja/support/fee-and-tax-treatment-faq) — 誰が税を負担するのか、
  各モードで顧客に何が請求されるのか、税が精算ファイルにどう現れるのか。
* [クーポンとプロモーションコード](/docs/ja/support/coupons-and-promotion-codes-faq) —
  割引エンジンの全体像：クーポンの定義、コードの発行、利用レコード、分析、アカウント単位の上限。
* [Point Topup リセラー API](/docs/ja/support/point-topup-reseller-api-faq) — 6 つのリセラー
  エンドポイント、カタログと価格のフィールド、注文ステータス。

## 注文を分割して返金しました。毎回どれだけの税が戻りますか？

各返金は、その注文における自分の取り分に対して税が計算されます。**ただし最後の 1 回は例外**で、
合計が正確に一致するように補正されます。

理由は丸めです。税は計算のたびに小数点以下 2 桁に丸められるため、複数回の部分返金にわたると、
個別に計算された税額の合計が、元の決済で実際に徴収された税を上回ったり下回ったりすることが
あります。放置すれば、4 回に分けて全額返金を受けた顧客が、支払った額より 1 セント多く、
あるいは 1 セント少なく受け取る可能性があります。

そのため最後の返金は計算されるのではなく、**導出**されます。

| 返金 | 返金される税 |
| - | - |
| 注文を使い切らない返金 | その返金自身の金額に対して計算される |
| 注文を使い切る返金 | **当初徴収された税 − すでに返金された税** |

「注文を使い切る」とは、すでに行われた返金とこの返金の合計が、元の注文金額に達するか
それを超えることを意味します。失敗した税の返金は累計から除外されるため、税側で失敗した返金が
残額を食いつぶすことはありません。また、この引き算が負になる場合、金額は誤った方向に進むことを
許されず、ゼロで下限が設けられます。

これが保証する性質は次のとおりです。**何回に分けて注文を全額返金しても、戻ってくる税は
徴収された税とちょうど一致します。** 丸めのずれがどちらの方向にも蓄積しません。

## 返金の合計が元の注文を超えた場合はどうなりますか？

超過分は返金されません。税が算出される前に、返金の課税ベースが残額に対してクランプされます。

| 状況 | この返金に使われる課税ベース |
| - | - |
| これまでの返金とこの返金の合計が元の金額の範囲内 | この返金の金額、そのまま |
| これまでの返金とこの返金の合計が元の金額を超える | 元の金額**から**これまでの返金を引いた額 |
| これまでの返金がすでに元の金額に達しているか超えている | **ゼロ** — これ以上の税は返金されない |

計画に織り込むべきは 3 行目です。ある注文の税がすでに全額返金されている場合、それに対する
追加の返金活動は、エラーもなく静かに、**それ以上の税の返金を生みません**。過剰に返金されること
はありませんが、税の構成要素がゼロだったことを知らせるものもありません。税を突き合わせる場合は、
各返金が戻したように見える額を合計するのではなく、元の決済の税額に対して突き合わせてください。

## チャージバックの返金は、通常の返金と同じように税を扱いますか？

同じ累計の会計処理を通ります。チャージバックと返金は、元の決済に対する 1 つの累計を共有するため、
チャージバックは返金とまったく同じように返金可能な残りの税を消費し、最終取引の補正は
どちらであれ最後に着地したものに適用されます。

デフォルトに 1 つ違いがあります。**チャージバックは全額に対するものと想定されます。**
部分的なチャージバックが発生する場合、金額を明示的に指定する必要があります。指定がなければ、
元の金額の全額が戻し処理の対象になります。

チャージバックが残りの資金 — 手数料、精算、係争金額 — に何をするかは別の主題です。
[手数料と税の取り扱い](/docs/ja/support/fee-and-tax-treatment-faq) を参照してください。

## 注文の税を計算できませんでした。注文は拒否されたのですか？

**理由によります**。そして 2 つの結果は正反対です。

| 失敗の種類 | 結果 |
| - | - |
| 税計算側が**ダウングレード可能**と印を付けた失敗 — その注文の国に税の取り決めがない場合を含む | 税は**スキップ**されます。注文は非課税の金額で進みます |
| 解決できない**郵便番号 / 国**の組み合わせ | 注文は**拒否**され、それ専用の理由が付きます |
| それ以外のすべて — 不正な通貨、計算入力の欠落や不正 | 注文は税計算の失敗として**拒否**されます |

つまり「税計算に失敗した」は 1 つの挙動ではありません。ダウングレードの経路は、その注文に
ついて税が正当に適用されないケースのために存在し、意図的に何も表示しません。ダウングレード
された注文は、税のフィールドが何も埋まっていない、ごく普通の非課税注文に見えます。
貴社の目に触れるエラーではありません。

連携で対処する価値があるのは郵便番号のケースです。それは**貴社が送信したデータが原因**であり、
修正可能だからです。郵便番号が国と整合しない住所 — 桁の入れ替わり、国の不一致、その国が
使用しない郵便番号の形式 — は、ダウングレードされずに注文を失敗させます。住所を自社で収集
しているなら、注文を作成する前に郵便番号を国に対して検証してください。チェックアウトページが
収集している場合は、顧客に訂正を促す表示が出ます。

またタイムアウト時には短い再試行があるため、1 回の計算が遅かっただけで注文が失敗することは
ありません。

## そもそも注文に税が計算されないのはなぜですか？

税の取り決めは、アカウント単位ではなく**国単位**で保持されているためです。1 つ持っていても、
すべてが得られるわけではありません。

取り決めのない国での注文には、計算の基礎となるものが存在しないため、計算はダウングレード可能な
失敗を報告し、注文は非課税のまま進みます。これは設定ミスではなく、通常の意図された経路です。

国単位モデルのさらに 2 つの性質が、それ以外では不可解に見える挙動を説明します。

* **税を*計算*するために必要な入力と、税を*納付*するために必要な入力は別の集合であり**、
  国ごとに個別に定義されています。したがって、ある注文が税の計算に必要なものをすべて備えて
  いながら納付の目的では不完全である、あるいはその逆、ということが起こりえます。
  ある国がどのフィールドを必要とするかは、普遍的なリストではなく貴社の取り決めから来ます。
* **税を決定する国は、必ずしも税が納付される国ではありません。** どちらも取り決めごとに
  記録されており、両者は異なることがあります。

誰に税が請求され誰がそれを負担するのか、そして加盟店負担の税がチェックアウトで顧客に
表示されない理由は、[手数料と税の取り扱い](/docs/ja/support/fee-and-tax-treatment-faq)
で扱っています。

## 利用レコードがまだ `CREATED` のままなのはなぜですか？

そのレコードが属する注文がまだ最終状態に達していないためです。割引レコードは
**注文作成時に予約され、確定するのは後**です。つまり `CREATED` は進行中の注文にとって
正常な状態であり、レコードが詰まっているわけではありません。

レコードは注文の進行に合わせて進みます。

| 注文が… | レコードは | 利用枠への影響 |
| - | - | - |
| まだ進行中 | `CREATED` | 保持 — 予約済みで、消費はされていない |
| 決済に成功した | `COMPLETED` | 消費済み |
| 決済に成功しないままクローズされた | `VOIDED` | クーポンとコードに解放される |
| 記録される前、作成中に失敗した | `VOIDED` | 解放される |
| 確定後に返金された | `REVERSED` | 解放される。**ただし全額返金であることが条件** |

設計上織り込む価値のある帰結があります。

* **`CREATED` の予約は在庫を押さえます。** 放棄されたチェックアウトは、注文がクローズされる
  まで枠を保持します。上限付きクーポンが使い切られたように見えるのに、利用履歴の確定済み
  利用数が上限より少ない場合、その差はたいていクローズされていない予約です。
* **カウントされるのは `COMPLETED` だけです。** 分析は確定済みの利用を数えるため、
  それ以外の状態のレコードは割引レポートに現れません。
* **注文が一度も存在しないままレコードが無効化されることがあります。** 割引が予約された後、
  注文が永続化される前に注文作成が失敗した場合でも、予約は解放されます。背後に注文のない
  `VOIDED` レコードが見えることになります。これは幻の注文ではなく、後片付けです。

## 返金すると利用枠は戻りますか？

**全額**返金の場合のみ、しかもアカウントの戻し処理の方針に従う場合に限ります。部分返金では
レコードは `COMPLETED` のままで、枠も消費されたままです。

その理由は、部分返金は購入を取り消してはいないため、割引はやはり使われた、というものです。
実務上の帰結として、`ONCE` のクーポンで購入して部分返金を受けた顧客は、そのクーポンを
取り戻せません。

方針の設定、金額ゼロのサブスクリプション試用が枠に与える影響、そして戻し処理がカウンターを
マイナスにできない理由は、いずれも
[クーポンとプロモーションコード](/docs/ja/support/coupons-and-promotion-codes-faq)
で扱っています。

## 顧客は 1 件の注文で 2 つの割引を併用できますか？

いいえ。**1 件の注文が持つ割引は 1 つです。** どちらの方向にも積み重ねはできません。
すでに割引のある注文に 2 つ目の割引を適用することはできませんし、貴社がすでに割引した注文に
顧客が割引を追加することもできません。

3 つの別々のルールがそれを強制しており、メッセージも 3 種類に分かれます。

| 行った操作 | メッセージ |
| - | - |
| 同じ注文にプロモーションコードとクーポン ID の両方を送信した | `promotionCode and couponId are mutually exclusive` |
| すでに別の割引がある注文に割引を適用しようとした | `order already has a different promotion applied` |
| 指定したクーポンに属さないプロモーションコードを送信した | コードは見つからない、または無効として拒否されます |

3 つとも `A0003` として返され、具体的なメッセージはレスポンスに含まれます。`A0003` の詳細の
書式については
[決済手段の設定の読み方](/docs/ja/support/payment-method-config-and-limits-faq)
を参照してください。

商業的に「2 つのオファーを同時に」必要とするなら、それは 1 件の注文に 2 つのクーポンではなく、
合算した値で設定された 1 つのクーポンです。

## 「discount calculation result has expired」とはどういう意味ですか？

提示された割引額には**時間制限**があり、古くなったものを使って注文を作成しようとしたという
意味です。

割引の計算と注文の作成は 2 つのステップです。計算は顧客が支払う額を返し、注文作成はその結果を
参照します。両者の間に時間が経ちすぎると — 顧客がページを開いたまま離れた、チェックアウト
フローがセッションをまたいで見積もりを保持した — 参照された結果は受け付けられなくなり、
再計算するよう促すメッセージとともに注文が拒否されます。

修正方法は再計算であり、それは自動であるべきです。このエラーが出たら、割引の計算を再実行し、
新しい結果に対して注文を作成してください。クーポンの問題として扱わないでください。
顧客に割引の失敗を表示しないでください。クーポンは問題なく、古くなったのは見積もりだけです。
なお、適格性が再チェックされるため、再計算後の金額が異なる可能性に備えてください。
その間に利用上限に達したコードは、今度は完全に拒否されます。

## どの割引エラーが、顧客ではなく私の設定の問題だと示していますか？

以下は注文作成時に返され、すべて `A0003` の下にあります。この区別が重要なのは、半分は貴社が
修正すべきもので、半分は単にオファーが設定どおりに機能しているだけだからです。

| メッセージ | 誰の問題か |
| - | - |
| `coupon feature is not enabled for this merchant` | **貴社** — アカウント単位のマスタースイッチがオフです。オンにするまでどのクーポンも適用されません |
| `promotionCode and couponId are mutually exclusive` | **貴社** — 連携のバグです |
| `order already has a different promotion applied` | **貴社** — リクエストが積み重ねを試みています |
| `discount calculation result has expired, please recalculate` | **貴社** — 再計算して再試行してください |
| `promotion code not found or invalid` | どちらもありえる — 打ち間違いか、発行されたことのないコード |
| `promotion code has expired` | オファーが設定どおりに機能している |
| `coupon has expired or been archived` | オファーが設定どおりに機能している |
| `promotion code redemption limit has been reached` | オファーが設定どおりに機能している |
| `order amount does not meet the minimum requirement for this promotion` | 顧客のカートが小さすぎる |

最も時間を浪費するのは 1 行目です。クーポンの問題に見えるからです。作成したすべてのクーポンが
Portal 上では有効に見えるのに、注文作成で拒否されます。**何も**割引されない場合は、
クーポンを調べる前にマスタースイッチを確認してください。

顧客識別子の送信に依存する顧客単位のルールや初回限定のルールを含む、適格性の判定順序の全体は
[クーポンとプロモーションコード](/docs/ja/support/coupons-and-promotion-codes-faq)
にあります。

## 未払いの Point Topup 注文は、どれくらいの間在庫を確保しますか？

無期限ではありません。Point Topup 注文を作成すると必要な在庫が**予約**され、その注文が
支払われないままだと、既定の保持期間の後にその予約は自動的に解放されます
（これは契約条件ではなく運用上の設定です。カウントダウンを作り込まないでください）。

帰結が 2 つあります。

* **未払いの注文は、当てにできる確保ではありません。** 支払いに先立って注文を用意している
  場合や、顧客が後から支払いに戻ってくることを許している場合、そのときには商品がもう
  利用できなくなっている可能性があります。在庫の確保が重要なら、早めに注文を作成するのでは
  なく、速やかに支払ってください。
* **解放された在庫は注文を復活させません。** 注文は元の状態のまま残ります。予約の解放は
  他の購入者のために商品を空けるだけで、貴社側で何かをキャンセルしたり価格を変更したりする
  ものではありません。

注文が完全に失敗した場合、すでに引き落とされた金額は残高に戻されます。
[Point Topup リセラー API](/docs/ja/support/point-topup-reseller-api-faq) を参照してください。

## 1 件の Point Topup 注文に複数の商品を含められますか？

いいえ。Point Topup 注文が持つのはちょうど **1 つの SKU、数量 1** です。それ以外の数量は
作成時に拒否されます。

複数の商品を購入するには、複数の注文を作成してください。それぞれが独自の冪等性キー、
独自の予約、独自の結果を持ちます。これはたいていの場合いずれにせよ望ましいことです。
1 つの商品が失敗しても、他を巻き込みません。

また、そうした注文の `PAY_SUCCESS` というステータスは、決済が成功したこと、そして
**履行は貴社が完了させるもの**であることを意味する点にも注意してください。Waffo はその SKU を
配送しません。`PAY_SUCCESS` を「顧客が商品を受け取った」と読まないでください。フィールドの
リファレンスとその他のステータスは
[Point Topup リセラー API](/docs/ja/support/point-topup-reseller-api-faq) にあります。

## 次はどこを見ればよいですか？

| 質問 | ページ |
| - | - |
| 誰が税を負担するのか、税が精算にどう現れるのか | [手数料と税の取り扱い](/docs/ja/support/fee-and-tax-treatment-faq) |
| クーポンの定義、コードの発行、利用のレポーティング | [クーポンとプロモーションコード](/docs/ja/support/coupons-and-promotion-codes-faq) |
| リセラーのエンドポイント、カタログ、ステータス、通知 | [Point Topup リセラー API](/docs/ja/support/point-topup-reseller-api-faq) |
| 部分返金、返金の前提条件、異種通貨の返金額 | [返金 FAQ](/docs/ja/support/refund-faq) |
| `A0003` がどのフィールドの誤りを報告するか | [決済手段の設定の読み方](/docs/ja/support/payment-method-config-and-limits-faq) |
| 決済手段がどの住所フィールドを必要とするか | [条件付きフィールドと必須フィールド](/docs/ja/support/conditional-required-fields-faq) |


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