消費税、GST、VAT 用の Tax API

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

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

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

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

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

curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_09l3shTSTKHYCzzZZsiLl2vA
:" \
  -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

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

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

顧客の住所が無効な場合や、税金の計算に使用できるほど精度が高くない場合は、計算で 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 タイムスタンプに達するまでは、取引を作成できます。この時刻以降に使用しようとすると、エラーが返されます。

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

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

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

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

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

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

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

curl https://api.stripe.com/v1/payment_intents/
{{PAYMENT_INTENT_ID}} \
  -u "
sk_test_09l3shTSTKHYCzzZZsiLl2vA
:" \
  -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 は、顧客への売上を記録する税取引です。

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_09l3shTSTKHYCzzZZsiLl2vA
:" \
  -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 件の一部差戻しを作成できます。徴収した税額より多く差戻すと、エラーが返されます。

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

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_09l3shTSTKHYCzzZZsiLl2vA
:" \
  -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 の返金が記録されています。

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_09l3shTSTKHYCzzZZsiLl2vA
:" \
  -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 のアイテムの合計額の部分差戻しを記録する場合を考えてみましょう。

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_09l3shTSTKHYCzzZZsiLl2vA
:" \
  -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 の定率の金額の差戻しを記録します。

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_09l3shTSTKHYCzzZZsiLl2vA
:" \
  -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 は一部返金を表す取引です。

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "
sk_test_09l3shTSTKHYCzzZZsiLl2vA
:" \
  -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": [
      {

テスト環境の応答構造は本番環境と同じなので、本番環境へ移行する前に実装内容が正しく機能するか確認できます。