Tax API für Verkaufssteuer, GST und Umsatzsteuer

Stripe Tax berechnet nur Steuern in Ländern, in denen Sie für den Steuereinzug registriert sind. Sie müssen dazu im Dashboard Ihre Registrierungen hinzufügen.

Sie entscheiden, wann und wie oft Sie Steuern berechnen. Zum Beispiel können Sie:

• Zeigen Sie eine Steuerschätzung basierend auf der IP-Adresse Ihres Kunden/Ihrer Kundin an, wenn Ihr Kunde/Ihre Kundin den Bezahlvorgang durchläuft.
• Neuberechnung der Steuer, wenn Ihr/e Kunde/Kundin seine/ihre Rechnungs- oder Lieferadresse eingibt
• Berechnen Sie den endgültigen Steuerbetrag, der zu erheben ist, wenn Ihr/e Kunde/Kundin die Eingabe seiner/ihrer Adresse abgeschlossen hat.

Stripe erhebt eine Gebühr pro API-Aufruf zur Steuerberechnung. Sie können die API-Aufrufe zur Steuerberechnung drosseln, um Ihre Kosten zu verwalten.

Die folgenden Beispiele zeigen, wie Steuern in verschiedenen Szenarien berechnet werden. Stripe Tax berechnet nur Steuern in Ländern, in denen Sie für den Steuereinzug registriert sind. Sie müssen dazu im Dashboard Ihre Registrierungen hinzufügen.

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

Die Berechnungsantwort enthält Beträge, die Sie Ihrem Kunden/Ihrer Kundin anzeigen und zur Zahlung verwenden können:

Umgang mit Fehlern beim Kundenstandort

Die Berechnung gibt den Fehlercode customer_tax_location_invalid zurück, wenn die Adresse Ihres Kunden/Ihrer Kundin ungültig oder nicht präzise genug ist, um die Steuer zu berechnen:

{
  "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"
  }
}

Wenn Sie diesen Fehler erhalten, fordern Sie Ihren Kunden/Ihre Kundin auf, die eingegebene Adresse zu überprüfen und mögliche Tippfehler zu korrigieren.

Bei der Erstellung einer Steuertransaktion wird die von Ihrem Kunden/Ihrer Kundin erhobene Steuer aufgezeichnet, sodass Sie später Exporte herunterladen und Berichte erstellen können, um Ihre Steuererklärung zu unterstützen. Sie können eine Transaktion aus einer Berechnung bis zum Zeitstempel expires_at, 90 Tage nach ihrer Einrichtung, erstellen. Der Versuch, sie nach diesem Zeitpunkt zu verwenden, führt zu einem Fehler.

Wenn Sie eine Steuertransaktion erstellen, müssen Sie eine eindeutige reference für die Steuertransaktion und jede Position angeben. Die Referenzen erscheinen in den Steuerexporten, um Ihnen zu helfen, die erhobene Steuer mit den Aufträgen in Ihrem System abzustimmen.

Eine Steuertransaktion mit der Referenz pi_123456789, den Positionsreferenzen L1 und L2 und den Versandkosten sieht in den Steuerexporten beispielsweise so aus:

Wenn Ihr Kunde/Ihre Kundin zahlt, verwenden Sie die Berechnungs-ID, um die eingezogene Steuer zu erfassen. Es gibt zwei Möglichkeiten, dies zu tun:

• Wenn Ihr Server über einen Endpunkt verfügt, an dem Ihr Kunde/Ihre Kundin seine/ihre Bestellung aufgibt, können Sie die Steuertransaktion erstellen, nachdem die Bestellung erfolgreich abgeschickt wurde.
• Warten Sie auf das Webhook-Ereignis payment_intent.succeeded. Rufen Sie die Berechnungs-ID aus den PaymentIntent-metadata ab.

Im folgenden Beispiel wird eine Transaktion erstellt und die PaymentIntent-ID als eindeutige Referenz verwendet:

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

Speichern Sie die Steuer-Transaktions-ID, damit Sie später Erstattungen erfassen können. Sie können die Transaktions-ID in Ihrer Datenbank oder in den Metadaten der PaymentIntent speichern:

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

Nachdem Sie eine Steuertransaktion erstellt haben, um einen Verkauf an Ihren Kunden/Ihre Kundin zu erfassen, müssen Sie möglicherweise Erstattungen erfassen. Diese werden ebenfalls als Steuertransaktionen mit type=reversal dargestellt. Stornotransaktionen gleichen eine frühere Transaktion aus, indem sie Beträge mit entgegengesetztem Vorzeichen enthalten. Eine Transaktion, bei der beispielsweise ein Verkauf für 50 USD verbucht wurde, kann später eine vollständige Stornierung von -50 USD aufweisen.

Wenn Sie eine Rückerstattung ausstellen (mit Stripe oder außerhalb von Stripe), müssen Sie eine Steuerumkehr-Transaktion mit einer eindeutigen reference erstellen. Gängige Strategien umfassen:

• Hängen Sie ein Suffix an die ursprüngliche Referenz an. Wenn die ursprüngliche Transaktion beispielsweise die Referenz pi_123456789 hat, erstellen Sie die Stornierung mit der Referenz pi_123456789-refund
• Verwenden Sie die ID der Stripe-Erstattung oder eine Erstattungs-ID aus Ihrem System. Zum Beispiel re_3MoslRBUZ691iUZ41bsYVkOg oder myRefund_456.

Wählen Sie die Vorgehensweise, die für die Abstimmung Ihrer Kundenaufträge mit Ihren Steuerexporten am besten geeignet ist.

Vollständige Rückerstattung eines Verkaufs

Wenn Sie einen Verkauf in Ihrem System vollständig zurückerstatten, erstellen Sie eine Rückerstattung mit mode=full.

Im folgenden Beispiel ist tax_1MEFAAI6rIcR421eB1YOzACZ die Steuertransaktion, die den Verkauf an Ihren/ihre Kunden/in erfasst:

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

Dadurch wird die erstellte vollständige Stornotransaktion zurückgegeben:

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

Die vollständige Stornierung einer Transaktion hat keine Auswirkungen auf vorherige Teilstornierungen. Wenn Sie eine vollständige Stornierung erfassen, stellen Sie sicher, dass Sie alle vorherigen Teilstornierungen für dieselbe Transaktion vollständig stornieren, um doppelte Erstattungen zu vermeiden.

Teilweise Rückerstattung eines Verkaufs

After issuing a refund to your customer, create a reversal tax transaction with mode=partial. This allows you to record a partial refund by providing the line item amounts refunded. You can create up to 30 partial reversals for each sale. Reversing more than the amount of tax you collected returns an error.

Im folgenden Beispiel wird nur eine Rückerstattung des ersten Postens der ursprünglichen Transaktion aufgezeichnet:

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

Dadurch wird die erstellte Teilstornotransaktion zurückgegeben:

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

Für jeden stornierten Posten müssen Sie den amount und den amount_tax angeben, die storniert wurden. Der amount ist einschließlich Steuern, wenn die ursprüngliche Berechnungsposition einschließlich Steuern war.

Wie amount und amount_tax ermittelt werden, hängt von Ihrer Situation ab:

• Wenn Ihre Transaktionen immer nur eine einzige Position enthalten, verwenden Sie stattdessen vollständige Stornierungen.
• Wenn Sie immer ganze Positionen erstatten, verwenden Sie die ursprünglichen Transaktionspositionenamount und amount_tax, jedoch mit negativen Vorzeichen.
• Wenn Sie Teile von Einzelposten zurückerstatten, müssen Sie die zurückerstatteten Beträge berechnen. Bei einer Transaktion mit amount=5000 und amount_tax=500 würden Sie nach der Hälfte der Posten einen teilweisen Storno mit dem Posten amount=-2500 und amount_tax=-250 erstellen.

Teilweise Rückerstattung eines Verkaufs durch einen Pauschalbetrag

Alternativ können Sie einen Storno mit mode=partial erstellen. Hierfür geben Sie für den Betrag (inkl. Steuer) einen pauschalen Rückerstattungsbetrag an. Der Betrag wird anteilsmäßig auf die einzelnen Posten und die Versandkosten aufgeteilt, wobei auf den zu erstattenden Betrag eines jeden Artikels geachtet wird.

Die Transaktion im folgenden Beispiel besteht aus zwei Posten: einem Posten im Wert von 10 USD und einem Posten im Wert von 20 USD, beide werden mit 10 % besteuert. Der Gesamtbetrag der Transaktion beträgt 33,00 USD. Es wird eine Pauschalrückerstattung über 16,50 USD erfasst:

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

Dadurch wird die erstellte Teilstornotransaktion zurückgegeben:

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

Die Rückerstattungsbeträge und Steuer werden wie folgt pro Posten und Versandkosten der ursprünglichen Transaktion berechnet:

1. Zunächst berechnen wir das gesamte verbleibende Guthaben der Transaktion, das zurückerstattet werden kann. Da für diese Transaktion keine weiteren Stornos verzeichnet wurden, beträgt der Gesamtbetrag 33,00 USD.
2. Als Nächstes berechnen wir den zu erstattenden Gesamtbetrag pro Posten. Diesen Betrag ermitteln wir anhand des Anteils des verfügbaren Gesamtbetrags des zu erstattenden Artikels und des verbleibenden Gesamtbetrags der Transaktion. Das kann z. B. so aussehen: Der Artikel in Höhe von 10 USD, für den eine Rückerstattung von 11,00 USD verbleibt, entspricht 33,33 % des verbleibenden Gesamtbetrags der Transaktion. Der zurückzuerstattende Gesamtbetrag beträgt demnach -16.50 USD * 33.33% = -5.50 USD.
3. Abschließend wird der zu erstattende Gesamtbetrag auf amount und amount_tax aufgeteilt. Auch dies geschieht anteilsmäßig, abhängig davon, welcher Steuerbetrag für den Posten im Vergleich zum insgesamt zu erstattenden Betrag zurückerstattet werden kann. Für einen beispielhaften Posten in Höhe von 10 USD entspricht die Steuer (1,00 USD) 9,09 % des verbleibenden zu erstattenden Gesamtbetrags (11,00 USD). Der amount_tax ist also -5.50 USD * 9.09% = -0.50 USD.

Der Pauschalbetrag wird entsprechend des übrigen Rückerstattungsbetrags (what’s left to) der Transaktion aufgeteilt, nicht entsprechend des ursprünglich verbuchten Betrags. Hier ein Beispiel: Anstatt eine Pauschalrückerstattung über 16,50 USD zu erfassen, erfassen Sie zunächst einen teilweisen Storno über den Gesamtbetrag des Postens in Höhe von 10 USD:

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

Anschließend erfassen Sie einen pauschalen Stornobetrag über 16,50 USD:

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

Dies gibt die teilweise Stornotransaktion zurück:

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

Da der verbleibende Gesamtbetrag der Transaktion jetzt 22,00 USD beträgt und der Artikel in Höhe von 10 USD vollständig zurückerstattet wird, werden die 16,50 USD vollständig auf den Artikel über 20 USD aufgeteilt. Die 16,50 USD werden dann gemäß der Logik aus Schritt 3 auf amount = -15.00 USD und amount_tax = -1.50 USD aufgeteilt. In der Zwischenzeit wird für den 10-USD-Posten der Transaktion eine Rückerstattung von 0 USD erfasst.

Eine teilweise Rückerstattung rückgängig machen

Steuertransaktionen sind unveränderlich, aber Sie können eine Teilerstattung aufheben, indem Sie eine vollständige Rückerstattung davon erstellen.

Dies kann in folgenden Fällen erforderlich sein:

• Die Zahlung Rückerstattung schlägt fehl und Sie haben die Ware oder Dienstleistung nicht an Ihre/n Kunden/in bereitgestellt
• Die falsche Bestellung oder die falschen Beträge werden zurückerstattet
• Der ursprüngliche Verkauf wird vollständig zurückerstattet und die teilweisen Rückerstattungen sind nicht mehr gültig

Im folgenden Beispiel ist tax_1MEFACI6rIcR421eHrjXCSmD die Transaktion, die die Teilrückerstattung darstellt:

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

Dadurch wird die erstellte vollständige Stornotransaktion zurückgegeben:

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

Die Antwortstruktur im Test-Modus ist mit der im Live-Modus identisch. Sie können also vor der Live-Schaltung überprüfen, ob Ihre Integration funktioniert.