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

# どの金額・通貨フィールドを確認すればよいですか？

> 注文には複数の金額（orderAmount、originalAmount、finalDealAmount、ユーザーが実際に支払った金額、ユーザー手数料）が最大 3 つの通貨で含まれます。このページでは、注文を検証する際にどのフィールドを比較すべきか、どのフィールドを基準に商品を出荷すべきか、finalDealAmount が orderAmount と正当に異なる理由、そしてどの通貨で注文を作成すべきかを説明します。

金額に関する質問の多くは、結局同じ質問に帰着します：\*注文には複数の金額があり、どれが自分のものか分からない。\*このページは、そのフィールドごとの回答です。
隣接する 2 つのページが関連する領域をカバーしており、そのトピックについてはより早く読めます：

| ページ | 用途 |
| - | - |
| [金額と通貨](/docs/ja/developer-docs/core-concepts/currency) | 通貨ごとの小数桁ルール、および同一通貨とクロスカレンシーの定義 |
| [注文金額、限度額、拒否](/docs/ja/support/order-amount-precision-and-decline-faq) | 注文作成時に金額が**拒否**された場合：精度、丸め、限度額 |
| [決済と精算における為替レート](/docs/ja/support/exchange-rates-faq) | どのレートが使われるか、いつ確定するか、どこで確認できるか |
| **このページ** | どの金額フィールドが何を意味し、どれを比較すべきか |

## 注文にはどの金額フィールドが含まれますか？

| フィールド | 表示される場所 | 内容 |
| - | - | - |
| `orderAmount` | 作成時に送信。照会時と決済通知でエコーバック | **貴社が要求した金額**（`orderCurrency` 建て） |
| `orderCurrency` | 同上 | 貴社が価格設定した通貨 |
| `originalAmount` | 照会 / 通知 | 割引適用**前**の注文金額。割引が適用されていない場合は存在しません |
| `finalDealAmount` | 照会 / 通知 | ユーザーが支払った最終金額。`orderAmount` と異なる理由は下記参照 |
| `userCurrency` | 作成時は任意。エコーバック | `orderCurrency` と異なる場合の、ユーザーの支払通貨 |
| `payMethodResponse.userPaymentAmount` | 照会 / 通知（`paymentInfo.payMethodResponse` 内） | **決済手段側で**ユーザーが実際に支払った金額 |
| `payMethodResponse.userPaymentCurrency` | 同上 | その支払いの通貨 |
| `orderAction.actionData.paymentAmount` / `paymentCurrency` | 注文作成レスポンスのみ | 独自のチェックアウトを描画する加盟店向けに、ユーザーに支払いを求めている金額 |
| `orderAction.actionData.userFeeAmount` / `userFeeCurrency` | 注文作成レスポンスのみ | 貴社の金額に上乗せして**支払者**に課される手数料（明細表示） |
| `remainingRefundAmount` | 返金レスポンス / 返金照会 | その注文でまだ返金できる金額 |

すべての金額は数値ではなく**文字列**です。公開されている理由は浮動小数点の精度です：`0.1 + 0.2` は `0.3` になりません。これは金額としては許容できません。小数（decimal）としてパースしてください。

## 注文が自分の作成したものであることをどのように検証すればよいですか？

貴社自身の `paymentRequestId` または `merchantOrderId` をキーにして、**`orderAmount` + `orderCurrency`** を送信した値と比較してください。この 2 つのフィールドは貴社自身の入力がエコーバックされたものなので、要求したものと等しいことが保証されている唯一のペアです。

`finalDealAmount` を期待金額と比較して検証しては**いけません**。これは設計上異なる量であり、まったく正常な 2 つの状況によって異なる値になります。それが次の質問です。

> [!WARNING]
>
> `orderAmount` に対して検証してください。ただし、貴社サイトへのリダイレクトを結果として扱わないでください。
> 金額が何を示していても、権威ある結果は Webhook または[注文照会](/docs/ja/support/payment-results-faq)です。

## `finalDealAmount` が `orderAmount` と異なるのはなぜですか？

API 契約は 2 つの理由を挙げており、どちらも正常です：

1. **注文通貨がユーザーの支払通貨ではない。** クロスカレンシー注文は、貴社が一方の通貨で価格設定し、ユーザーが別の通貨で支払うため、2 つの数値は異なる単位であり一致しません。
2. **ユーザーが追加のサービス手数料を支払った。** 決済手段が支払者に手数料を課す場合、その手数料は `finalDealAmount` に含まれるため、貴社の金額より大きくなります。

つまり `finalDealAmount` は\*「これはユーザーにいくらかかったか」*に答え、`orderAmount` は*「自分はいくら請求したか」\*に答えます。商品の出荷と業務上の検証は `orderAmount` に基づいて行い、`finalDealAmount` はユーザーに支払額を表示したい場合にのみ使用してください。

## `orderCurrency` と `userCurrency` は本当に異なることがありますか？

はい。それこそがクロスカレンシー注文です：貴社は自身の通貨で価格設定し、ユーザーは自身の通貨で支払います。これはエラー状態ではなく、特定の決済手段カテゴリーに限定されるものでもありません。公開されている定義とそれに伴うパラメーターは
[金額と通貨](/docs/ja/developer-docs/core-concepts/currency)にあります。注文作成の実務上のルールとして、`payMethodType` または `payMethodName` を固定していない場合、クロスカレンシー注文には `payMethodCountry` が必要ですが、`userCurrency` 自体は任意のままです。

貴社の照合処理が注文ごとに 1 通貨を前提としている場合は、最初から 3 つのフィールドを想定して構築してください：`orderCurrency`（貴社のもの）、`userCurrency` / `userPaymentCurrency`（ユーザーのもの）、そして貴社の精算通貨（[精算計算の解説](/docs/ja/support/settlement-calculation-explained)を参照）。
これらは 3 つの別々のものであり、注文時点で貴社が制御できるのは最初のものだけです。

## ユーザーは自身の通貨で正確にいくら支払いましたか？

`paymentInfo.payMethodResponse.userPaymentAmount` と
`paymentInfo.payMethodResponse.userPaymentCurrency` です。このブロックは決済手段自身の取引に対する見方であり、以下も含まれます：

| `payMethodResponse` 内のキー | 内容 |
| - | - |
| `payMethodRefId` | **ユーザー**が自身の支払履歴で見る参照番号。ユーザーが支払ったかどうかを争う場合はこれを提示してください |
| `exchangeRate` | ユーザーの支払い時に決済手段が使用したレート |
| `maskCardData` | カード決済成功時の、先頭 6 桁と末尾 4 桁 |
| `userOpenId` | その決済手段におけるユーザーの一意な ID |
| `userPaymentAmount` / `userPaymentCurrency` | 実際に支払われた金額と通貨 |

これは JSON 文字列であり、どのキーが存在するかは決済手段によって異なります。固定の形を想定するのではなく、防御的に読み取ってください。

## ユーザーの純支払額を `finalDealAmount` からユーザー手数料を引いて計算できますか？

いいえ。照会レスポンスからはできません。`userFeeAmount` と `userFeeCurrency` は**注文作成レスポンスの `orderAction.actionData`** で返され、注文照会や決済通知のトップレベルフィールドとしては返されません。したがって、照合を行っている時点では通常、差し引くための手数料を独立した数値として持っておらず、そもそも 2 つの通貨をまたいだ減算は誤りです。

代わりに以下を使用してください：

* **正しい金額が請求されたか？** → `orderAmount` + `orderCurrency`。
* **ユーザーは合計でいくら支払ったか？** → `finalDealAmount`、または決済手段側の数値としては `userPaymentAmount`。
* **手数料はいくらだったか？** → 後で必要な場合は、作成時に `actionData.userFeeAmount` を取得して保存してください。

## ユーザー手数料は店頭（over-the-counter）決済でのみ課されますか？

API はそのような範囲設定をしていません。`userFeeAmount` / `userFeeCurrency` は `orderAction.actionData` にあり、これは独自のチェックアウトを構築する加盟店向けのブロックであり、契約上これらを 1 つの `payMethodType` に限定するものは何もありません。手段のカテゴリーで判断するのではなく、支払者手数料はどの手段でも*発生し得る*ものとして扱い、フィールドを読み取ってください。`finalDealAmount` と同じ助言です：読み取ること、推測しないこと。

Waffo のチェックアウトページを使用している場合、ユーザーはチェックアウト上で手数料を確認します。貴社が描画する必要はありません。

## `originalAmount` とは何ですか？割引はどの金額に対して検証すればよいですか？

`originalAmount` は割引適用**前**の注文金額です。プロモーションコードまたはクーポンが使用された場合、`orderAmount` は割引後の支払うべき金額であり、`originalAmount` は貴社が価格設定した割引前の数値です。

したがって、業務上のチェック（権利付与、履行、「この SKU に対して十分に支払ったか」）には `orderAmount` を使用してください。それが実際に請求された金額だからです。`originalAmount` は表示用または割引の影響を測定するためだけに使用してください。返金時の割引の扱いを含むクーポンとプロモーションコードの仕組みは、
[クーポンとプロモーションコード](/docs/ja/support/coupons-and-promotion-codes-faq)にあります。

## 財務はどの金額に対して照合すればよいですか？

`orderAmount` も `finalDealAmount` も単独では不適切です。これらは注文レベルのフィールドであり、手数料前、精算換算前のものです。資金の照合には、金額、手数料、精算通貨をまとめて含む精算レポートを使用してください：
[精算レポート](/docs/ja/support/settlement-reports-faq)と
[精算計算の解説](/docs/ja/support/settlement-calculation-explained)。

注文レベルのフィールドは*注文*の照合のためのものです。つまり、作成した注文が支払われた注文であることを証明するためのものです。この 2 つの作業は分けてください。それが「あなたの数字と私の数字が一致しない」の最もよくある原因です。

## 注文は現地通貨で作成しなければなりませんか？

いいえ。`orderCurrency` は**貴社の価格設定通貨**であり、クロスカレンシー注文（貴社が一方の通貨で価格設定し、ユーザーが別の通貨で支払う）はサポートされている第一級のフローです。特定の決済手段が特定の注文通貨に対応できるかどうかは、貴社のアカウントの契約に依存します。これは推測ではなく、参照によって確認します：

| 確認場所 | 分かること |
| - | - |
| `/api/v1/paymethodconfig/inquiry` | 貴社のアカウントで有効な決済手段契約ごとに 1 エントリ。それぞれに `currency` と `orderAmountMin` / `orderAmountMax` が含まれます |
| Portal → Payin | 同じ契約を、読み取りとフィルタリングができる画面として表示。[Payin 契約と取引限度額](/docs/ja/support/payin-agreements-and-limits-faq)を参照 |
| [決済手段](/docs/ja/essentials/payment-methods) | 国、タイプ、支払通貨でフィルタリングできる公開リスト |

そのレスポンスは**契約**をキーにしているため、1 つの決済手段が通貨ごとに複数回表示されることがあります。`payMethodName` は一意なキーではありません。詳細は
[決済手段の設定と限度額](/docs/ja/support/payment-method-config-and-limits-faq)にあります。

## ある決済手段が 1 つの通貨で掲載されています。それでも別の通貨で価格設定できますか？

2 つの通貨を分けて読み取ってください：

* **支払通貨** — ユーザーに請求される通貨。ローカル決済手段の場合、これは事実上その手段自体によって固定されます。
* **注文通貨** — 貴社が価格設定し、貴社への請求と精算の基準となる通貨。

支払通貨が単一の現地通貨である手段でも、貴社が別の通貨で価格設定した注文に対応できます。これがクロスカレンシーのケースであり、その換算のために為替レートがあります。できないのは、それを前提とすることです：送信しようとする組み合わせについて契約エントリを確認し、その組み合わせが設定されていない場合の拒否コードを処理してください。それは通貨固有のエラーではなく、契約不一致コードである `A0018` として返されます。
[限度額、通貨、設定エラー](/docs/ja/support/error-codes-and-limits-supplement)をご覧ください。

## クロスカレンシー注文の為替レートはどこで確認できますか？

2 つの異なるレート、2 つの異なるフィールドがあります：

| フィールド | 意味 |
| - | - |
| `orderAction.actionData.exchangeRate` | 契約上 `paymentAmount / orderAmount` と定義され、`orderCurrency` が `paymentCurrency` と異なる場合に存在します |
| `payMethodResponse.exchangeRate` | ユーザーが支払った際に決済手段自身が使用したレート |

これらは異なる質問に答えるものであり、異なる値になることがあります。レートがいつ確定するか、どれだけの期間有効か、返金にどのレートが使われるかはすべて
[決済と精算における為替レート](/docs/ja/support/exchange-rates-faq)にあります。

## 小数は何桁まで送信できますか？通貨によって異なりますか？

はい、通貨によって異なり、同一通貨注文とクロスカレンシー注文でルールが異なります。公開されているルール：ほとんどの通貨は ISO 4217 に従って小数 2 桁を取り、一部の通貨は同一通貨注文では小数を**まったく**含めてはならず、クロスカレンシー注文ではすべての通貨が例外なく ISO 4217 の精度に従わなければなりません。完全なリストと拒否時の動作は
[金額と通貨](/docs/ja/developer-docs/core-concepts/currency)と
[注文金額、限度額、拒否](/docs/ja/support/order-amount-precision-and-decline-faq)にあります。

決済手段ごとの金額範囲は精度とは別のチェックです。これらは契約上の `orderAmountMin` / `orderAmountMax` から来るため、エラーコードから限度額を知るのではなく、注文を作成する前にそれらに対して検証してください。

## 返金にはどの金額フィールドが含まれますか？

| フィールド | 意味 |
| - | - |
| `refundAmount` | 貴社が返金を要求した金額（注文通貨建て） |
| `finalDealAmount` | **ユーザーが受け取る**金額。ユーザーが当初支払ったサービス手数料や税手数料を除く場合があるため、対応する注文金額より小さくなることがあります |
| `remainingRefundAmount` | この返金の後、その注文でまだ返金可能な金額 |
| `userCurrency` | 注文通貨がユーザーの支払通貨と異なる場合に存在 |

`remainingRefundAmount` は、貴社の記録から再計算するのではなく、「まだ返金できるか」という貴社自身のロジックを駆動するためのフィールドです。貴社自身が開始していないものも含め、その注文のすべての返金がすでに考慮されています。返金ルール自体は
[返金 FAQ](/docs/ja/support/refund-faq)と
[決済手段別の返金制限](/docs/ja/support/payment-method-refund-limits-faq)にあります。

***

どのフィールドを比較すべきかまだ分からない場合は、`paymentRequestId` と一致しない 2 つの数値を添えて[サポートにお問い合わせください](mailto:support@waffo.com)。


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