コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン
概要構築済みのシステムをアップグレード
オンライン決済
概要ユースケースを見つける
支払い方法
支払いインターフェイス
決済シナリオ
店頭支払い
他の Stripe プロダクト

注

このページはまだ日本語ではご利用いただけません。より多くの言語で文書が閲覧できるように現在取り組んでいます。準備が整い次第、翻訳版を提供いたしますので、もう少しお待ちください。

消費税、GST、VAT 用の Tax API

Stripe Tax API を使用して、カスタムのシステムに税額計算を実装します。

ページをコピー

注

このガイドでは、Stripe Tax を PaymentIntents などのカスタム決済フローと連携させる方法を説明します。また、ノーコードまたはローコードの設定で、Payment Links、Checkout、Billing、および Invoicing と連携させることもできます。

Stripe Tax API を使用すると、カスタム決済フローで税金を計算できます。顧客が決済を完了した後で、取引を記録して Stripe Tax のレポートに表示されるようにします。このガイドの例では Stripe の Payment API を使用していますが、任意の決済代行業者や複数の決済代行業者で Tax API を使用することもできます。

デモ動画を見て始める

この短い動画では、PaymentIntents と Payment Element を使用する Stripe Tax API の導入手順を説明しています。

動画コンテンツの読み込み中...

登録を追加する

Stripe Tax では、税金の徴収が登録されている管轄区域の税金のみが計算されるため、ダッシュボードで登録の追加が必要です。

税金を計算
サーバー側

税金を計算する時期と頻度を選択します。たとえば、以下を選択できます。

  • 顧客が決済フローに入ったときに顧客の IP アドレスに基づく税金の見積もりを表示する
  • 顧客が請求先住所または配送先住所を入力するときに税金を再計算する
  • 顧客が住所の入力を完了したときに、徴収する最終的な税額を計算する

Stripe は税金計算の API コールごとに手数料を請求します。税金計算の API コールを抑制して、コストを管理できます。

下記の例は、さまざまなシナリオで税金を計算する方法を示しています。Stripe Tax では、税金の徴収を登録した管轄区域の税金のみを計算し、ダッシュボードでの登録の追加が必要です。

この例では、アメリカの配送先住所の税金を計算します。ラインアイテムの価格は 10 USD で、アカウントの事前設定の税コードを使用しています。

Command Line
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=shipping

計算の応答には、顧客に表示し、支払いを受けるのに使用できる金額が含まれます。

属性説明
amount_total税金の計算後の総計。これを使用して、顧客に請求する PaymentIntent の amount を設定します。
tax_amount_exclusiveラインアイテムの金額と配送料金に追加される税金の金額。この税額は amount_total を増額します。これを使用して、取引の小計に追加される税額を顧客に示します。
tax_amount_inclusiveラインアイテムの金額と配送料金に含まれている税金の金額 (内税価格を使用している場合)。この税額は amount_total を増額しません。これを使用して、支払い金額の合計に含まれている税金を顧客に示します。
tax_breakdown国や州の税率ごとに分類された税額のリスト。これを使用して、徴収している特定の税金を顧客に示します。

顧客の場所のエラーを処理する

顧客の住所が無効な場合や、税金の計算に使用できるほど精度が高くない場合は、計算で customer_tax_location_invalid エラーが返されます。

{
  "error": {
    "doc_url": "https://docs.stripe.com/error-codes#customer-tax-location-invalid",
    "code": "customer_tax_location_invalid",
    "message": "We could not determine the customer's tax location based on the provided customer address.",
    "param": "customer_details[address]",
    "type": "invalid_request_error"
  }
}

このエラーを受け取った場合は、顧客に入力した住所を確認して誤りを修正するように求めます。

税取引を作成する
サーバー側

税取引を作成すると顧客から徴収した税金が記録されるので、後からエクスポート結果をダウンロードしてレポートを生成し、納税申告に役立てることができます。計算の作成後 90 日の expires_at タイムスタンプに達するまでは、取引を作成できます。この時刻以降に使用しようとすると、エラーが返されます。

注

取引は create_from_calculation が呼び出された日付に有効であると見なされ、税額は再計算されません。

税取引を作成する際は、税取引とラインアイテムごとの一意の reference を指定する必要があります。この参照番号は、税金のエクスポート結果に表示され、徴収した税金をシステムの注文と照合するのに役立ちます。

たとえば、税取引の参照番号が pi_123456789、ラインアイテムの参照番号が L1 と L2、配送料金がある場合、項目別の税金のエクスポートは次のようになります。

IDline_item_idタイプ通貨transaction_date…
pi_123456789L1externalUSD2023-02-23 17:01:16…
pi_123456789L2externalUSD2023-02-23 17:01:16…
pi_123456789配送externalUSD2023-02-23 17:01:16…

顧客が支払う際に、計算 ID を使用して徴収した税金を記録します。これを行うには 2 つの方法があります。

  • 顧客が注文を送信するエンドポイントがサーバーにある場合は、注文が正常に送信された後で税取引を作成できます。
  • payment_intent.succeeded Webhook イベントをリッスンします。PaymentIntent metadata から計算 ID を取得します。

以下の例では、取引を作成して、PaymentIntent ID を一意の参照番号として使用します。

Command Line
curl https://api.stripe.com/v1/tax/transactions/create_from_calculation \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d calculation={{TAX_CALCULATION}} \
  -d reference=
{{PAYMENT_INTENT_ID}}
 \
  -d "expand[]"=line_items

後で返金を記録できるように、税取引 ID を保存します。取引 ID はデータベースまたは PaymentIntent のメタデータに保存できます。

Command Line
curl https://api.stripe.com/v1/payment_intents/
{{PAYMENT_INTENT_ID}}
 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "metadata[tax_transaction]"={{TAX_TRANSACTION}}

返金を記録する
サーバー側

顧客への売上を記録するために税取引を作成した後で、返金の記録が必要になる場合があります。これらは、type=reversal の税取引としても表されます。差戻し取引は、逆の符合の金額を指定することで前の取引を相殺します。たとえば、50 USD の売上を記録した取引に、後から -50 USD の全額差戻しを指定できます。

返金を発行 (Stripe を使用、または Stripe の外部で) する際には、一意の reference を指定して税の差戻し取引を作成する必要があります。一般的には以下のような方法があります。

  • 元の参照番号にサフィックスを追加します。たとえば、元の取引の参照番号が pi_123456789 の場合は、参照番号 pi_123456789-refund の差戻し取引を作成します。
  • Stripe refund (返金) の ID、またはご使用のシステムの返金 ID を使用します (re_3MoslRBUZ691iUZ41bsYVkOg や myRefund_456 など)。

顧客の注文を税金のエクスポートと照合するための最適な方法を選択します。

売上を全額返金する

システムで売上を全額返金するには、mode=full を指定して差戻し取引を作成します。

以下の例の tax_1MEFAAI6rIcR421eB1YOzACZ は、顧客への売上を記録する税取引です。

Command Line
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=full \
  -d original_transaction=tax_1MEFAAI6rIcR421eB1YOzACZ \
  -d reference=pi_123456789-cancel \
  -d "expand[]"=line_items

これにより、作成された全額差戻し取引が返されます。

{
  "id": "tax_1MEFtXI6rIcR421e0KTGXvCK",
  "object": "tax.transaction",
  "created": 1670866467,
  "currency": "eur",
  "customer": null,
  "customer_details": {
    "address": {
      "city": null,
      "country": "IE",

取引を全額差戻しても以前の一部差戻しに影響はありません。全額差戻しを記録するときは、返金の重複を避けるために、同じ取引への以前の一部差戻しがすべて完了していることを確認します。

売上を一部返金する

顧客に返金を発行したら、mode=partial を指定して税の差戻し取引を作成します。これにより、返金されたラインアイテムの金額を指定して一部返金を記録できます。売上ごとに最大 30 件の一部差戻しを作成できます。徴収した税額より多く差戻すと、エラーが返されます。

以下の例では、元の取引の最初のラインアイテムのみの返金が記録されます。

Command Line
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=partial \
  -d original_transaction=tax_1MEFAAI6rIcR421eB1YOzACZ \
  -d reference=pi_123456789-refund_1 \
  -d "line_items[0][original_line_item]"=tax_li_MyBXPByrSUwm6r \
  -d "line_items[0][reference]"=L1 \
  -d "line_items[0][amount]"=-4999 \
  -d "line_items[0][amount_tax]"=-1150 \
  -d "metadata[refund]"=
{{REFUND_ID}}
 \
  --data-urlencode "metadata[refund_reason]"="Refunded line 1 of pi_123456789 (customer was unhappy)" \
  -d "expand[0]"=line_items

これにより、作成された一部差戻し取引が返されます。

{
  "id": "tax_1MEFACI6rIcR421eHrjXCSmD",
  "object": "tax.transaction",
  "created": 1670863656,
  "currency": "eur",
  ...
  "line_items": {
    "object": "list",
    "data": [
      {

差戻されるラインアイテムのそれぞれについて、差戻される amount と amount_tax を指定する必要があります。元の計算のラインアイテムが内税だった場合、amount は内税になります。

amount と amount_tax は以下のように状況によって決定されます。

  • 取引のラインアイテムが常に 1 件のみの場合は、代わりに全額差戻しを使用します。
  • 常にラインアイテム全体を返金する場合は、マイナス記号を指定して元の取引ラインアイテムの amount と amount_tax を使用します。
  • ラインアイテムの一部を返金する場合は、返金額を計算する必要があります。たとえば、amount=5000 と amount_tax=500 の販売取引では、ラインアイテムの半分を返金した後で、amount=-2500 と amount_tax=-250 のラインアイテムで一部差戻しを作成します。

売上を定率で一部返金する

また、税額適用後に返金する定率を指定して、mode=partial を設定した差戻しを作成することもできます。金額は、それぞれに対する返金の残額に応じて、各ラインアイテムと配送料金に比例配分されます。

下記の例の取引には 2 つのラインアイテムがあります。1 つは 10 USD のアイテムで、もう 1 つは 20 USD のアイテムで、いずれも税率 10% で課税されています。取引の合計額は 33.00 USD です。定率の 16.50 USD の返金が記録されています。

Command Line
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=partial \
  -d original_transaction=tax_1NVcKqBUZ691iUZ4xMZtcGYt \
  -d reference=pi_234567890-refund_1 \
  -d flat_amount=-1650 \
  -d "metadata[refund]"=
{{REFUND_ID}}
 \
  --data-urlencode "metadata[refund_reason]"="Refunded $16.50 of pi_234567890 (customer was unhappy)" \
  -d "expand[]"=line_items

これにより、作成された一部差戻し取引が返されます。

{
  "id": "tax_1NVcQYBUZ691iUZ4SBPukGa6",
  "object": "tax.transaction",
  "created": 1689780994,
  "currency": "usd",
  ...
  "line_items": {
    "object": "list",
    "data": [
      {

元の取引の各ラインアイテムと配送料に対して、返金額と税金が以下のように計算されます。

  1. まず、返金に利用できる取引の残額の合計を計算します。この取引には他に差戻しが記録されていないため、合計金額は 33.00 USD です。
  2. 次に、各アイテムに対する返金額の合計を計算します。この計算は返金に利用できる額と取引の残額合計の比率を基準にします。たとえば、10 USD のアイテムは、返金対象の残額合計が 11.00 USD であり、取引の残額合計の 33.33% に相当するため、返金される合計金額は -16.50 USD * 33.33% = -5.50 USD となります。
  3. 最後に、返金対象の合計金額が amount と amount_tax に分割されます。これについても、ラインアイテムでと返金対象の残額合計を比較して返金に利用できる税額に応じて比例的に計算されます。10 USD のアイテムを例にすると、税金 (1.00 USD) は返金対象の残額合計 (11.00 USD) の 9.09% に相当するので、amount_tax は -5.50 USD * 9.09% = -0.50 USD となります。

最初に記録されていた額ではなく、取引の返金対象の「残額」に応じて一定率の金額が配分されます。たとえば、定率の金額 16.50 USD の返金を記録するのではなく、まず 10 USD のアイテムの合計額の部分差戻しを記録する場合を考えてみましょう。

Command Line
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=partial \
  -d original_transaction=tax_1NVcKqBUZ691iUZ4xMZtcGYt \
  -d reference=pi_234567890-refund_1 \
  -d "line_items[0][original_line_item]"=tax_li_OICmRXkFuWr8Df \
  -d "line_items[0][reference]"=partial_refund_l1 \
  -d "line_items[0][amount]"=-1000 \
  -d "line_items[0][amount_tax]"=-100 \
  -d "metadata[refund]"=
{{REFUND_ID}}
 \
  --data-urlencode "metadata[refund_reason]"="Refunded line 1 of pi_234567890 (customer was unhappy)" \
  -d "expand[0]"=line_items

この後に、16.50 USD の定率の金額の差戻しを記録します。

Command Line
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=partial \
  -d original_transaction=tax_1NVcKqBUZ691iUZ4xMZtcGYt \
  -d reference=pi_234567890-refund_2 \
  -d flat_amount=-1650 \
  -d "metadata[refund]"=
{{REFUND_ID}}
 \
  --data-urlencode "metadata[refund_reason]"="Refunded $16.50 of pi_234567890 (customer was still unhappy)" \
  -d "expand[]"=line_items

これで部分差戻し取引が返されます。

{
  "id": "tax_1NVxFIBUZ691iUZ4saOIloxB",
  "object": "tax.transaction",
  "created": 1689861020,
  "currency": "usd",
  ...
  "line_items": {
    "object": "list",
    "data": [
      {

取引で残っている金額の合計が 22.00 USD であり、10 USD のアイテムが全額返金されているため、16.50 USD の全体が 20 USD のアイテムに配分されます。次に、16.50 USD がステップ 3 のロジックを使用して、amount = -15.00 USD と amount_tax = -1.50 USD に配分されます。一方、取引の 10 USD のアイテムには 0 USD の返金が記録されます。

一部返金を取り消す

税取引は変更不可能ですが、その全額差戻しを作成して、一部返金を相殺することはできます。

この処理が必要になる状況を以下に示します。

  • 支払いの返金に失敗し、顧客に商品やサービスを提供していない場合
  • 誤った注文が返金されたか、誤った金額が返金された場合
  • 元の売上が全額返金され、一部返金が無効になった場合

以下の例の tax_1MEFACI6rIcR421eHrjXCSmD は一部返金を表す取引です。

Command Line
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=full \
  -d original_transaction=tax_1MEFACI6rIcR421eHrjXCSmD \
  -d reference=pi_123456789-refund_1-cancel \
  -d "metadata[refund_reason]"="User called to cancel because they picked the wrong item" \
  -d "expand[]"=line_items

これにより、作成された全額差戻し取引が返されます。

{
  "id": "tax_1MEFADI6rIcR421e94fNTOCK",
  "object": "tax.transaction",
  "created": 1670863657,
  "currency": "eur",
  ...
  "line_items": {
    "object": "list",
    "data": [
      {

テスト

サンドボックスのレスポンス構造は本番環境と同じであるため、本番環境に移行する前にシステムが正しく機能していることを確認できます。

警告

テスト環境での計算で、最新の課税結果が返されることは保証できません。

You’re limited to 1,000 tax calculations per day. If you need a higher limit, contact Stripe support.

For guidance on automated testing and strategies to avoid rate limits in testing environments, see Automated testing.

ダッシュボードで税取引を表示する

You can view all tax transactions for your account on the Tax Transactions page in the Dashboard. Click an individual transaction to see a detailed breakdown of calculated tax by jurisdiction, and by the individual products included in the transaction.

注

このページには_取引_のみが表示され、_計算_は表示されません。計算が表示されるはずなのにこのページにない場合は、計算によって正常に税取引が作成されているかご確認ください。

参照情報

このページはお役に立ちましたか。
はいいいえ
お困りのことがございましたら 、サポートにお問い合わせください。
早期アクセスプログラムにご参加ください。
変更ログをご覧ください。
ご不明な点がございましたら、お問い合わせください。
LLM ですか？llms.txt を読んでください。
Powered by Markdoc