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

# 税務連携

## 本章で得られること

本章を読むと、次のことができるようになります。

* 商品の価格設定方式と、自分で計算した税額を申告する必要があるかに基づいて、税抜価格設定、両価格の指定、税込価格設定のいずれかを選択できます。
* どの税項目を Waffo が設定する必要があるか、連携前にどの業務ルールを確認すべきかを把握できます。
* 支払いと返金のリクエストを正しく構築し、照会と Webhook における金額の変化、空値、エラーを処理できます。

一回限りの支払い（`ONE_TIME_PAYMENT`）は、税抜価格設定、両価格の指定、税込価格設定の 3 つの方式をサポートします。

以下の支払いリクエストの例では [`POST /api/v1/order/create`](/docs/api-reference/order-create/create-new-order) を使用し、結果は [`POST /api/v1/order/inquiry`](/docs/api-reference/order-inquiry/order-inquiry) で照会します。

Subscription は税抜価格設定のみをサポートし、両価格の指定と税込価格設定はサポートしません。リクエスト項目については、[Subscription 作成 API](/docs/api-reference/subscription-create/create-subscription)を参照してください。

## 金額の指定方法を選ぶ

まず商品価格がすでに税込かどうかを判断し、次に自分で計算した税額を Waffo に申告する必要があるかを判断します。3 つの方式はリクエストの金額項目の組み合わせで決まります。

| 業務上の要件 | 推奨する方式 | 選ぶ理由 |
| - | - | - |
| 税抜の商品価格を管理し、適用される設定と実際の支払い情報に基づいて Waffo に税を計算してほしい | 税抜価格設定 | 税抜金額のみを提供します。適用されるユーザー税は支払い金額に加算されます |
| 自社システムで税額を計算し、支払い前にユーザーへ税額と税込総額を提示したい | 両価格の指定 | 両価格と国を提出します。Waffo は設定に従って申告値を検証または受け入れ、後続の支払いフローで最終的な税額を計算します |
| 税込総額を管理し、Waffo に税抜価格と税額を分離してほしい | 税込価格設定 | 税込総額のみを提供し、分離は Waffo が行います。自分で先に税を分離する必要はありません |

自社で税額を計算する場合は、[自社で計算した税額の検証](#自社で計算した税額の検証)を確認してください。

税込価格を指定した後も、割引、為替換算、手数料がユーザーの最終的な実払額に影響することがあります。項目の組み合わせと例は後述の「連携の詳細」を参照してください。

## Waffo が設定する税項目

以下の税項目は Waffo が設定します。必要な取引の挙動を Waffo に伝え、Sandbox と Production の設定をそれぞれ確認してください。

| 設定項目 | 設定可能な内容 | 連携への影響 |
| - | - | - |
| 税サービスの範囲 | `Calculation Only` / `Full Tax Service` | Waffo が税の納付を担当するかどうかを決定します。具体的な分担は [税サービスオプションの違い](#税サービスオプションの違い)を参照してください |
| 商品税カテゴリのマッピングとデフォルト税カテゴリ | 商品名を税カテゴリにマッピングし、デフォルト税カテゴリを指定します。一致しない場合は取引を拒否するか、デフォルト税カテゴリを使用します | `goodsInfo.goodsName` のマッピングと、一致しない場合の処理を Waffo と確認してください。名称の変化が税計算に影響することがあります |
| 自社で計算した税額の検証 | `Strict` / `Loose`。詳細は[オプションの説明](#自社で計算した税額の検証)を参照してください | 両価格の指定にのみ適用され、申告税額の差異をどのように処理するかを決定します |

### 税サービスオプションの違い

* **`Calculation Only`**：Waffo は税額を計算し、支払い時にユーザーから徴収し、Settlement を通じて徴収した税をあなたに送金します。税務当局への納付はあなたが担当します。税の分離完了後、各税額は[注文照会 API](/docs/api-reference/order-inquiry/order-inquiry)の `orderTaxAmount` と対応する Webhook から読み取ることができます。
* **`Full Tax Service`**：Waffo が税額の計算、税の徴収および納付を担当します。連携前に、適用範囲と分担を Waffo に確認してください。

### 自社で計算した税額の検証

この設定は両価格の指定にのみ適用されます。税抜価格設定と税込価格設定では、この申告税額の検証は使用しません。

**Strict**

申告した税額と Waffo の計算値を比較します。一致しない場合、Waffo の設定により取引を拒否するか、Waffo の計算値で上書きすることができます。

**Loose**

申告した税額を受け入れ、Waffo の計算値とは比較しません。たとえば、税抜価格 `100.00`、税込価格 `110.00` の場合、申告税額は `10.00` です。`Loose` はこの申告値を受け入れつつ、金額の組み合わせ、税設定、必須パラメータを引き続きチェックします。

作成時に申告値を受け入れたことは、最終的な税額やユーザーの実払額が確定したことを意味しません。注文照会または Webhook を基準にしてください。

## 連携の詳細

### 連携の準備

税設定は Waffo が管理します。連携前に、Merchant ID、Sandbox または Production 環境、販売国、商品カテゴリを提供し、その環境に必要な税契約と支払い方法がすでに用意されていることを確認してください。

本ページの税込価格は、注文通貨での価格です。これは Merchant が税を負担することを意味するものではなく、為替換算、手数料、割引の処理を経た後にユーザーが実際に支払う金額と等しいことを保証するものでもありません。

### 注文作成時のパラメータ指定

金額はすべて文字列を使用し、通貨は `orderCurrency` を取得します。少なくとも 1 つの金額基準を指定してください。税込価格は 0 より大きい必要があり、通貨の精度要件を満たす必要があります。国コードは ISO 3166-1 alpha-3 を使用し、たとえば `PHL` です。詳細は[金額と通貨](/docs/ja/developer-docs/core-concepts/currency)を参照してください。

| 方式 | `orderAmount` | `taxInfo.orderAmountInclTax` | `taxInfo.taxCountry` | 処理の効果 |
| - | - | - | - | - |
| 税抜価格設定 | 税抜価格を指定 | 指定しない | 指定しない | Waffo は一致した設定に基づいて税を計算し、適用されるユーザー税は支払い金額に加算されます |
| 両価格の指定 | 税抜価格を指定 | 税込価格を指定（税抜価格以上） | 必須 | Waffo は設定に従って両価格の差額が表す申告税を処理し、実際の支払いフローに従って最終的な税額を計算します |
| 税込価格設定 | 指定しない | 税込総額を指定 | 指定しない | Waffo は税込金額から税を分離します。分離が完了すると、`orderAmount` は税抜金額になります |

税抜価格設定では、`taxInfo` 全体を省略してください。空のオブジェクト `{}` を指定した場合も、項目の組み合わせが不正なため `A0003` が返されます。`taxInfo` を省略することは免税を要求することを意味しません。

以下の JSON は、注文作成リクエストのうち税に関連する部分のみを示しています。Merchant、支払い方法、ユーザー、リクエスト識別子、時刻、署名などの共通パラメータは引き続き補完する必要があります。

3 つの方式を比較するため、注文通貨と支払い通貨がともに USD、適用税率が 10%、割引と追加手数料がないと仮定します。以下の税率と金額は計算の説明にのみ使用するものであり、`PHL` の実際の税率やお客様の税契約を表すものではありません。両価格の指定の結果は、実際の設定における申告検証ポリシーによって決まります。

**税抜価格設定**

```json theme={null}
{
  "orderCurrency": "USD",
  "orderAmount": "100.00"
}
```

上記の仮定では、税は `10.00` で、ユーザーは `110.00` を支払います。一致する課税設定がない場合、この例だけから必ず `10.00` が加算されると判断することはできません。

**両価格の指定**

```json theme={null}
{
  "orderCurrency": "USD",
  "orderAmount": "100.00",
  "taxInfo": {
    "taxCountry": "PHL",
    "orderAmountInclTax": "110.00"
  }
}
```

両価格の差額 `10.00` が申告する税額です。Waffo は税契約の申告検証ポリシーに従ってこの差額を処理し、利用可能な支払い方法を確認します。具体的な挙動は[自社で計算した税額の検証](#自社で計算した税額の検証)によって決まります。両価格を指定しても、税率設定は変更されません。

**税込価格設定**

```json theme={null}
{
  "orderCurrency": "USD",
  "taxInfo": {
    "orderAmountInclTax": "110.00"
  }
}
```

上記の仮定では、税の分離が完了すると税抜価格 `100.00` と税額 `10.00` が返され、`110.00` に対してさらに税が加算されることはありません。`orderAmount` または `taxCountry` を同時に指定しないでください。

### 支払い結果を読み取る

作成レスポンスは注文識別子、ステータス、次のアクションを返し、本節の税金額の項目は含みません。注文作成後に [`POST /api/v1/order/inquiry`](/docs/api-reference/order-inquiry/order-inquiry) でこれらの項目を取得してください。注文照会と `PAYMENT_NOTIFICATION` は、以下の表に示す税項目を返します。照会項目はレスポンスの `data` オブジェクトに含まれます。Webhook の外側の構造は、[イベントタイプの文書](/docs/ja/developer-docs/webhook/event-types)を参照してください。

| 項目 | 通貨または意味 | 連携上の注意点 |
| - | - | - |
| `orderCurrency` | 注文通貨 | `orderAmount`、`orderTaxAmount`、税込注文金額はすべてこの通貨として解釈します |
| `orderAmount` | 税の分離完了後の税抜注文金額 | 税込価格設定でまだ分離していない場合、一時的に税込金額になることがあります。作成時の途中値から最終的な税抜価格を推測しないでください |
| `orderTaxAmount` | 注文通貨での税額 | 空になることがあります。空はまだ分離していない、または税の結果がないことを意味し、確定したゼロ税額として直接扱うことはできません |
| `taxInfo.orderAmountInclTax` | 現在の最終的な割引後税込注文金額 | 両価格の指定または税込価格設定の場合のみ返されます。分離完了後は `orderAmount + orderTaxAmount` に等しく、割引前のリクエスト元の値ではありません |
| `taxInfo.taxCountry` | 作成時に申告した課税国 | 申告値があるのは両価格の指定の場合のみです。税込価格設定では空になることがあり、汎用的な最終請求国のエコーではありません |
| `finalDealAmount`、`userCurrency` | ユーザーの支払い金額とその通貨 | 支払い完了後にユーザーの実払額を照合するために使用します。注文通貨の税額を別通貨の金額に直接加算しないでください |

税抜価格設定のレスポンスは `orderTaxAmount` を持ちながら `taxInfo` を持たないことがあります。したがって、`taxInfo` の有無を課税の判断に使用することはできません。

税込価格設定の途中状態では、`orderAmount = "110.00"`、`orderTaxAmount` が空、`taxInfo.orderAmountInclTax = "110.00"` が同時に現れることもあります。この場合、再度税を減算または加算しないでください。リクエストの元の値を保存し、最終的な照会または Webhook のステータスと金額で結果を照合してください。

完全な項目とレスポンス例については、[注文照会 API](/docs/api-reference/order-inquiry/order-inquiry)を参照してください。

`orderTaxAmount` は税込総額の表現にすでに含まれているため、`finalDealAmount` に再度加算しないでください。支払いが完了していない場合、現在計算された金額をすでに引き落とされた金額として扱わないでください。Webhook の署名検証とステータス処理については、[Webhook の概要](/docs/ja/developer-docs/webhook/overview)を参照してください。

### 返金時の指定方法

返金金額も注文通貨を使用します。`refundAmount` は税抜返金金額を表します。`taxInfo.refundAmountInclTax` を指定できるかどうかは、元の支払い注文の指定方法によって決まります。

| 元の支払い注文の方式 | 許可される返金の指定方法 | 許可されない指定方法 |
| - | - | - |
| 税抜価格設定 | `refundAmount` のみを指定 | 税込返金金額を指定 |
| 両価格の指定 | `refundAmount` のみ、または `refundAmount` と `taxInfo.refundAmountInclTax` を同時に指定 | 税込返金金額のみを指定 |
| 税込価格設定 | `refundAmount` のみ、または `taxInfo.refundAmountInclTax` のみのいずれか | 両価格を同時に指定 |

以下は `POST /api/v1/order/refund` の部分的なリクエストです。元の注文番号、返金リクエスト識別子、理由などの共通パラメータは引き続き補完する必要があります。

**税抜金額のみ**

3 種類の元の支払い注文すべてに適用されます。`refundAmount` のみを指定し、対応する税の返金は Waffo が計算します。

```json theme={null}
{
  "refundAmount": "50.00"
}
```

**両価格を同時に指定**

両価格の指定を使用した元の支払い注文にのみ適用されます。税抜 `50.00`、税込 `55.00` を申告し、差額は引き続き設定済みの自社で計算した税額の検証ポリシーに従って処理されます。

```json theme={null}
{
  "refundAmount": "50.00",
  "taxInfo": {
    "refundAmountInclTax": "55.00"
  }
}
```

**税込金額のみ**

税込価格設定を使用した元の支払い注文にのみ適用されます。税込返金額のみを指定し、Waffo が税抜返金金額に換算します。

```json theme={null}
{
  "taxInfo": {
    "refundAmountInclTax": "55.00"
  }
}
```

上記の金額は前文の仮定を引き継いでいます。全額返金は元注文の最終金額と現在の返金可能残高に基づくべきであり、割引前のリクエスト元の値をそのまま流用しないでください。一部返金の税額は Waffo が計算し累計金額を検証します。注文比率で独自に端数処理した結果を権威ある返金税結果として扱わないでください。

返金照会 [`POST /api/v1/refund/inquiry`](/docs/api-reference/refund-inquiry/refund-inquiry) と `REFUND_NOTIFICATION` では、主に以下を読み取ります。

| 項目 | 連携上の注意点 |
| - | - |
| `refundAmount` | 正規化後の税抜返金金額で、元の注文通貨を使用します。税込の入力は異なる数値に換算されることがあります |
| `orderTaxAmount` | 今回の返金税額を注文通貨で表した金額で、支払い注文全体の元の税額ではありません。空になることがあり、ゼロ税の結果が `"0"` として明示的に返されることもあります |
| `taxInfo.refundAmountInclTax` | 返金税の結果があり、元注文が両価格または税込価格設定の場合に返され、今回の `refundAmount + orderTaxAmount` に等しくなります。すべての途中状態にこの項目があると仮定しないでください |
| `finalDealAmount`、`userCurrency` | ユーザーが実際に受け取る返金金額と通貨です。返金税や返金可能な手数料を含むことがあり、`refundAmount` だけで着金を照合することはできません |
| `remainingRefundAmount` | 元の注文通貨における残りの返金可能な税抜注文金額で、税込残高でもユーザー支払い通貨の残高でもありません |

返金が進行中または失敗した場合、返された計算金額はユーザーがすでに返金を受け取ったことを意味しません。最終的な成功ステータスとあわせて着金を照合してください。

同じ `paymentRequestId` または `refundRequestId` を再試行する場合は、元の金額、税込金額、指定方法を変更しないでください。不明な結果を先に照会してから次のステップを決めてください。詳細は[冪等性](/docs/ja/developer-docs/core-concepts/idempotency)を参照してください。

### よくあるエラー

| エラーコード | 意味と対処 |
| - | - |
| `A0003` | 金額形式、フィールドの組み合わせ、国などのパラメータを確認してください。税抜価格設定では `taxInfo` を省略してください（空のオブジェクト `{}` も指定できません）。税込価格設定では `taxCountry` を指定しないでください |
| `A0051` | 申告税額が Waffo に拒否されました。たとえば厳密比較後に拒否ポリシーで処理された場合です。両価格、国、税計算情報、契約ポリシーを確認し、冪等キーだけを変更して同じ誤った金額を再試行しないでください |
| `A0052` | この申告税額をサポートできる支払い方法がない、または税契約なしで `taxInfo` を指定しています。Waffo に連絡して設定とサポート範囲を確認してください |
| `A0053` | 申告税額の検証に必要な請求情報（郵便番号など）が不足しています。[注文作成 API](/docs/api-reference/order-create/create-new-order)に従って必須パラメータを補完してから再送信してください |

### 連携チェックリスト

* 対象環境で Waffo に税契約、商品情報、請求情報の要件を確認します。
* 1 つの価格設定方式でリクエストを構築し、非課税、課税、郵便番号不足、および申告が一致しない場合の各有効ポリシーの結果を検証します。
* リクエストの元の値、注文通貨の金額、ユーザー支払い通貨の金額をそれぞれ保存します。
* 税込価格設定の作成途中状態と支払い完了後で項目がどう変化するかを検証します。
* 元の支払い注文タイプごとに全額返金と一部返金を検証し、照会と Webhook を確認します。


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