# Steuern einziehen
Verwenden Sie Stripe Tax APIs, um Steuerberechnungen in Ihrer benutzerdefinierten Integration zu implementieren.
Mit den Stripe Tax APIs können Sie Steuern in nutzerdefinierten Zahlungsabläufen berechnen. Nachdem Ihr Kunde/Ihre Kundin die Zahlung abgeschlossen hat, zeichnen Sie die Transaktion auf, damit sie im Stripe Tax-Bericht angezeigt wird. In den Beispielen in diesem Leitfaden werden Stripe-APIs für Zahlungen verwendet. Sie können jedoch die Tax API mit jedem beliebigen Zahlungsdienstleister oder mehreren Zahlungsdienstleistern verwenden.
> #### Wählen Sie die richtige Integration für Steuern
>
> Stripe bietet zwei Möglichkeiten, Steuern in nutzerdefinierten Zahlungsabläufen zu verwalten. Treffen Sie Ihre Auswahl je nachdem, wie viel Kontrolle Sie über die Steuerumkehr benötigen:
>
> - Verwenden Sie die [Payment-Intents-Integration](https://docs.stripe.com/tax/payment-intent.md), wenn Sie möchten, dass Stripe Steuertransaktionen und Umkehrungen der Steuerschuldnerschaft automatisch verarbeitet und dass Pauschal-Rückerstattungen bei Steuerumkehrungen Ihren Anforderungen entsprechen.
- Verwenden Sie die **Custom Tax API**, wenn Sie Kontrolle über Steuerumkehrungen auf Postenebene benötigen (z. B. die Rückerstattung bestimmter Posten), mit mehreren Zahlungsabwicklern zusammenarbeiten oder die volle Kontrolle darüber benötigen, wann Transaktionen erfasst werden.
Wir bieten auch eine Funktion zur öffentlichen Vorschau, mit der Sie das [Steueridentifikationsnummernelement](https://docs.stripe.com/elements/tax-id-element.md) verwenden können, um Steueridentifikationsnummern von Kundinnen/Kunden einzuziehen. Weitere Informationen finden Sie unten unter [Steueridentifikationsnummern von Kundinnen/Kunden einziehen](https://docs.stripe.com/tax/custom.md#collect-customer-tax-ids).
Alternativ können Sie Stripe Tax mit [Payment Links](https://docs.stripe.com/tax/payment-links.md), [Checkout](https://docs.stripe.com/tax/checkout.md), [Billing](https://docs.stripe.com/tax/subscriptions.md) und [Invoicing](https://docs.stripe.com/tax/invoicing.md) ohne Code oder mit Low-Code integrieren.
Ein Diagramm, das eine allgemeine Übersicht über die Integration der Tax API bietet (See full diagram at https://docs.stripe.com/tax/custom)
Dieses Video führt Sie durch die Integration der Stripe Tax API, die die Payment Intents API und das Payment Element verwendet.
[Watch on YouTube](https://www.youtube.com/watch?v=OfHJiC9Iek0)
## Registrierungen hinzufügen
Stripe Tax berechnet Steuern nur in Ländern, in denen Sie für den Einzug von Steuern registriert sind. Sie müssen [Ihre Registrierungen im Dashboard hinzufügen](https://docs.stripe.com/tax/registering.md#add-a-registration).
## Optional: Kundenadresse erfassen [Clientseitig]
Die von Ihnen erhobene Steuer hängt in der Regel vom Standort Ihrer Kundin oder Ihres Kunden ab. Um die Steuer möglichst genau zu berechnen, erfassen Sie die vollständige Adresse Ihrer Kundin oder Ihres Kunden. Bevor Sie eine Adresse erfassen, können Sie Ihrer Kundin oder Ihrem Kunden eine Schätzung auf der Grundlage der jeweiligen [IP-Adresse](https://docs.stripe.com/tax/custom.md#ip-address) anzeigen.
> Die folgenden Beispiele verwenden das [Address Element](https://docs.stripe.com/elements/address-element.md), um Kundenadressen mit Autovervollständigungs- und Lokalisierungsfunktionen zu erfassen. Wenn Sie nur [eine minimale Steuerdatenerhebung](https://docs.stripe.com/tax/customer-locations.md#supported-formats) benötigen, können Sie alternativ ein einfaches benutzerdefiniertes Adressformular verwenden.
Im folgenden Beispiel wird ein vollständiges Rechnungsadressformular mit dem Address Element eingebunden:
```html
```
Sie können die Adresse wie folgt an Ihren Server-Endpoint übergeben:
```js
const elements = stripe.elements();
const addressElement = elements.create('address', {mode: 'billing'});
addressElement.mount('#address-element');
document.getElementById('address-form').addEventListener('submit', function(event) {
event.preventDefault();
addressElement.getValue().then(function(result) {
if (!result.complete) {
return;
}
var response = fetch('/preview-cart', {
method: 'POST',
body: JSON.stringify({address: result.value.address}),
headers: {'Content-Type': 'application/json'},
}).then(function(response) {
return response.json();
}).then(function(responseJson) {
// Handle errors, or display calculated tax to your customer.
});
});
});
```
Die für die Steuerberechnung erforderlichen Adressdaten [variieren je nach Land der Kundin oder des Kunden](https://docs.stripe.com/tax/customer-locations.md#supported-formats):
- **Vereinigte Staaten**: Wir benötigen mindestens die Postleitzahl Ihrer Kundinnen und Kunden. Für eine möglichst genaue Steuerberechnung empfehlen wir die Angabe einer vollständigen Adresse.
- **Kanada**: Wir benötigen die Postleitzahl oder die Provinz Ihrer Kundin oder Ihres Kunden.
- **Andere Länder**: Wir benötigen nur den Ländercode Ihrer Kundin oder Ihres Kunden.
## Steuer berechnen [Serverseitig]
Sie entscheiden, wann und wie oft Sie [Steuern berechnen](https://docs.stripe.com/api/tax/calculations/create.md). Zum Beispiel können Sie Folgendes tun:
- Zeigen Sie eine Steuerschätzung [basierend auf der IP-Adresse Ihrer Kundin oder Ihres Kunden](https://docs.stripe.com/tax/custom.md#ip-address) an, wenn Ihre Kundin oder Ihr Kunde den Bezahlvorgang beginnt.
- 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](https://stripe.com/tax/pricing) 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 Zuständigkeitsbereichen, in denen Sie für den Steuereinzug registriert sind. Sie müssen dazu im Dashboard [Ihre Registrierungen hinzufügen](https://docs.stripe.com/tax/registering.md#add-a-registration).
#### Beispiel - Vereinigte Staaten: Steuerausschließlichkeitsposten
In diesem Beispiel wird die Steuer für eine US-Versandadresse berechnet. Der Posten hat einen Preis von 10 USD und verwendet den [voreingestellten Steuercode](https://docs.stripe.com/tax/set-up.md#preset-tax-code) Ihres Kontos.
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-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"
```
#### Beispiel - Vereinigte Staaten: mehrere Posten mit Versand
Dieses Beispiel enthält mehrere Posten ohne Steuern sowie Versandkosten in Höhe von 5 USD.
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=usd \
-d "line_items[0][amount]=1000" \
-d "line_items[0][reference]=L1" \
-d "line_items[0][tax_code]=txcd_99999999" \
-d "line_items[1][amount]=5000" \
-d "line_items[1][reference]=L2" \
-d "line_items[1][tax_code]=txcd_99999999" \
-d "line_items[2][amount]=9999" \
-d "line_items[2][reference]=L3" \
-d "line_items[2][tax_code]=txcd_99999999" \
-d "shipping_cost[amount]=500" \
-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"
```
#### Beispiel - Vereinigte Staaten: Posten mit Menge
In New York unterliegen Kleidungsstücke nicht der Verkaufssteuer, wenn jeder Artikel weniger als 110 USD kostet. In diesem Beispiel gibt es ein Kleidungsstück mit einem Gesamtpreis von 150 USD und einer Menge von 3. Das bedeutet, dass jedes Kleidungsstück 50 USD kostet und von der Umsatzsteuer befreit ist.
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=usd \
-d "line_items[0][amount]=15000" \
-d "line_items[0][quantity]=3" \
-d "line_items[0][reference]=Clothing" \
-d "line_items[0][tax_code]=txcd_30011000" \
-d "shipping_cost[amount]=500" \
-d "customer_details[address][state]=NY" \
-d "customer_details[address][postal_code]=10001" \
-d "customer_details[address][country]=US" \
-d "customer_details[address_source]=shipping"
```
#### Beispiel - Europa: Posten inklusive Steuern
In diesem Beispiel wird die Steuer für eine Rechnungsadresse in Irland berechnet, wo die Steuer normalerweise in den Preisen für Nicht-Geschäftskundinnen und -kunden enthalten ist. Der Posten hat einen Preis von 29,99 EUR und verwendet das Steuerkennzeichen `txcd_10302000` (ebook).
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=eur \
-d "line_items[0][amount]=2999" \
-d "line_items[0][reference]=L1" \
-d "line_items[0][tax_behavior]=inclusive" \
-d "line_items[0][tax_code]=txcd_10302000" \
-d "customer_details[address][country]=IE" \
-d "customer_details[address_source]=billing"
```
#### Beispiel - Europa: mehrere Posten mit Versand
In diesem Beispiel wird die Steuer für eine Versandadresse in Irland berechnet, wo die Steuer in der Regel in den Preisen für Nicht-Geschäftskundinnen und -kunden enthalten ist. Der zu versendende Artikel hat einen Preis von 59,99 EUR und die Versandkosten betragen 5 EUR. Da beide Beträge inklusive Steuern sind, zahlt die Kundin oder der Kunde immer 64,99 EUR.
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=eur \
-d "line_items[0][amount]=5999" \
-d "line_items[0][reference]=L1" \
-d "line_items[0][tax_behavior]=inclusive" \
-d "line_items[0][tax_code]=txcd_99999999" \
-d "shipping_cost[amount]=500" \
-d "shipping_cost[tax_behavior]=inclusive" \
-d "customer_details[address][line1]=123 Some House" \
-d "customer_details[address][city]=Dublin" \
-d "customer_details[address][country]=IE" \
-d "customer_details[address_source]=shipping"
```
#### Beispiel - Absenderadresse
Mit dieser Beta-Funktion werden Steuern auf Grundlage der Absenderadresse erhoben, wenn Sie in bestimmten Bundesstaaten (z. B. Illinois) eine Absenderadresse angeben und die Sendung physische Waren enthält. Enthält die Sendung sowohl physische Waren als auch Dienstleistungen, werden die Steuern für beides auf Basis der Absenderadresse berechnet.
In diesem Beispiel wird die Steuer auf der Grundlage des Versandorts in Naperville, Illinois, berechnet, anstatt des Unternehmensstandorts (außerhalb von Illinois) und der Lieferadresse in Springfield, Illinois.
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=usd \
-d "line_items[0][amount]=1000" \
-d "line_items[0][reference]=L1" \
-d "line_items[0][tax_behavior]=exclusive" \
-d "line_items[0][tax_code]=txcd_99999999" \
-d "shipping_cost[amount]=500" \
-d "shipping_cost[tax_behavior]=exclusive" \
-d "customer_details[address][city]=Springfield" \
-d "customer_details[address][state]=IL" \
-d "customer_details[address][postal_code]=62704" \
-d "customer_details[address][country]=US" \
-d "customer_details[address_source]=billing" \
-d "ship_from_details[address][city]=Naperville" \
-d "ship_from_details[address][state]=IL" \
-d "ship_from_details[address][postal_code]=60540" \
-d "ship_from_details[address][country]=US"
```
Die [Berechnungsantwort](https://docs.stripe.com/api/tax/calculations/object.md) enthält Beträge, die Sie Ihren Kundinnen und Kunden anzeigen und zur Zahlung verwenden können:
| Attribut | Beschreibung |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [amount_total](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-amount_total) | Die Gesamtsumme nach Berechnung der Steuer. Verwenden Sie diesen Wert, um den PaymentIntent-[Betrag](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount) festzulegen, der Ihrer Kundin oder Ihrem Kunden in Rechnung gestellt werden soll. |
| [tax_amount_exclusive](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-tax_amount_exclusive) | Der Steuerbetrag, der zu den Beträgen Ihrer Posten und den Versandkosten hinzukommt. Dieser Steuerbetrag erhöht den `amount_total`. Verwenden Sie dies, um Ihrem Kunden/Ihrer Kundin den Steuerbetrag anzuzeigen, der zur Zwischensumme der Transaktion hinzugefügt wurde. |
| [tax_amount_inclusive](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-tax_amount_inclusive) | Der Steuerbetrag, der in den Beträgen Ihrer Posten und den Versandkosten enthalten ist (wenn Sie Preise ohne Steuer verwenden). Dieser Steuerbetrag erhöht nicht den `amount_total`. Verwenden Sie dies, um Ihren Kundinnen und Kunden die in der Gesamtsumme enthaltene Steuer anzuzeigen. |
| [tax_breakdown](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-tax_breakdown) | Eine Liste der Steuerbeträge, aufgeschlüsselt nach nationalen und bundesstaatlichen Steuersätzen. Damit können Sie Ihrer Kundschaft zeigen, welche Steuern Sie erheben. |
### Fehler bei Kundenstandorten behandeln
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:
```json
{
"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, bitten Sie Ihre Kundin oder Ihren Kunden, die eingegebene Adresse zu überprüfen und mögliche Tippfehler zu korrigieren.
### Berechnung mit einem anderen Abwickler verwenden
Wenn Sie Transaktionen außerhalb von Stripe abwickeln, können Sie die folgenden Schritte überspringen und die Berechnung auf Ihre extern verarbeiteten Transaktionen anwenden.
## Steuertransaktion erstellen [Serverseitig]
Bei der Erstellung einer Steuertransaktion wird die von Ihrer Kundin oder Ihrem Kunden erhobene Steuer aufgezeichnet, sodass Sie später [Exporte herunterladen und Berichte erstellen](https://docs.stripe.com/tax/reports.md), um Ihre Steuererklärung zu unterstützen. Sie können eine [Transaktion](https://docs.stripe.com/api/tax/transactions/create_from_calculation.md) aus einer Berechnung bis zum Zeitstempel [expires_at](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-expires_at), 90 Tage nach ihrer Einrichtung, erstellen. Verwendungsversuche nach diesem Zeitpunkt führen zu einem Fehler.
> Die Transaktion gilt an dem Tag als wirksam, an dem `create_from_calculation` aufgerufen wird, und die Steuerbeträge werden nicht neu berechnet.
Wenn Sie eine Steuertransaktion erstellen, müssen Sie eine eindeutige `reference` für die Steuertransaktion und jeden Posten angeben. Die Referenzen erscheinen in den Steuerexporten, um Ihnen zu helfen, die erhobene Steuer mit den Bestellungen in Ihrem System abzugleichen.
Eine Steuertransaktion mit der Referenz `pi_123456789`, den Postenreferenzen `L1` und `L2` sowie den Versandkosten sieht in den Steuerexporten beispielsweise so aus:
| ID | line_item_id | Typ | Währung | transaction_date |
| ------------ | ------------ | ------ | ------- | ------------------- |
| pi_123456789 | L1 | extern | usd | 2023-02-23 17:01:16 |
| pi_123456789 | L2 | extern | usd | 2023-02-23 17:01:16 |
| pi_123456789 | Versand | extern | usd | 2023-02-23 17:01:16 |
Wenn Ihre Kundin oder Ihr Kunde zahlt, verwenden Sie die Berechnungs-ID, um die erhobene Steuer zu erfassen. Das können Sie auf zwei Arten tun:
- Wenn Ihr Server über einen Endpunkt verfügt, an dem Ihre Kundin oder Ihr Kunde die Bestellung aufgibt, können Sie die Steuertransaktion erstellen, nachdem die Bestellung erfolgreich abgeschickt wurde.
- Warten Sie auf das Webhook-Ereignis [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-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
curl https://api.stripe.com/v1/tax/transactions/create_from_calculation \
-u "<>:" \
-d calculation={{TAX_CALCULATION}} \
-d "reference={{PAYMENTINTENT_ID}}" \
-d "expand[]=line_items"
```
Speichern Sie die [Steuertransaktions-ID](https://docs.stripe.com/api/tax/transactions/object.md#tax_transaction_object-id), um Rückerstattungen später zu dokumentieren. Sie können die Transaktions-ID in Ihrer Datenbank oder in den Metadaten des PaymentIntent speichern:
```curl
curl https://api.stripe.com/v1/payment_intents/{{PAYMENTINTENT_ID}} \
-u "<>:" \
-d "metadata[tax_transaction]={{TAX_TRANSACTION}}"
```
## Rückerstattungen aufzeichnen [Serverseitig]
Nachdem Sie eine Steuertransaktion erstellt haben, um einen Verkauf an eine Kundin oder einen Kunden 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-Rückerstattung](https://docs.stripe.com/api/refunds/object.md) oder eine Rückerstattungs-ID aus Ihrem System. Zum Beispiel `re_3MoslRBUZ691iUZ41bsYVkOg` oder `myRefund_456`.
Wählen Sie die Vorgehensweise, die zum Abgleichen Ihrer Kundenbestellungen mit Ihren [Steuerexporten](https://docs.stripe.com/tax/reports.md) 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 Ihre Kundin oder Ihren Kunden erfasst:
```curl
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
-u "<>:" \
-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:
```json
{
"id": "tax_1MEFtXI6rIcR421e0KTGXvCK",
"object": "tax.transaction",
"created": 1670866467,
"currency": "eur",
"customer": null,
"customer_details": {
"address": {
"city": null,
"country": "IE",
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"address_source": "billing",
"ip_address": null,
"tax_ids": [],
"taxability_override": "none"
},
"line_items": {
"object": "list",
"data": [
{
"id": "tax_li_MyCIgTuP9F9mEU",
"object": "tax.transaction_line_item",
"amount": -4999,
"amount_tax": -1150,
"livemode": false,
"metadata": {
},
"quantity": 1,
"reference": "L1",
"reversal": {
"original_line_item": "tax_li_MyBXPByrSUwm6r"
},
"tax_behavior": "exclusive",
"tax_code": "txcd_10000000",
"type": "reversal"
},
{
"id": "tax_li_MyCIUNXExXmJKU",
"object": "tax.transaction_line_item",
"amount": -1090,
"amount_tax": -90,
"livemode": false,
"metadata": {
},
"quantity": 1,
"reference": "L2",
"reversal": {
"original_line_item": "tax_li_MyBX3Wu3qd2mXj"
},
"tax_behavior": "exclusive",
"tax_code": "txcd_10000000",
"type": "reversal"
}
],
"has_more": false,
"total_count": 2,
"url": "/v1/tax/transactions/tax_1MEFtXI6rIcR421e0KTGXvCK/line_items"
},
"livemode": false,
"metadata": {
},
"reference": "pi_123456789-cancel",
"reversal": {
"original_transaction": "tax_1MEFAAI6rIcR421eB1YOzACZ"
},
"shipping_cost": null,
"tax_date": 1670863654,
"type": "reversal"
}
```
Das vollständige Stornieren einer Transaktion hat keine Auswirkungen auf vorherige Teilstornierungen. Vergewissern Sie sich beim Erfassen einer vollständigen Stornierung, dass Sie alle vorherigen Teilstornierungen für dieselbe Transaktion [vollständig stornieren](https://docs.stripe.com/tax/custom.md#reversals-void-refund), um doppelte Erstattungen zu vermeiden.
### Teilweise Rückerstattung eines Verkaufs
Nach dem [Ausstellen einer Rückerstattung](https://docs.stripe.com/api/refunds/create.md) an Ihre Kundin oder Ihren Kunden, erstellen Sie eine Storno-Steuertransaktion mit `mode=partial`. Damit können Sie eine Teilerstattung erfassen, indem Sie die erstatteten Beträge der einzelnen Posten angeben. Sie können bis zu 30 Teilrückbuchungen für jeden Verkauf erstellen. Wenn Sie mehr als den von Ihnen erhobenen Steuerbetrag stornieren, wird ein Fehler zurückgegeben.
Im folgenden Beispiel wird nur eine Rückerstattung des ersten Postens der ursprünglichen Transaktion aufgezeichnet:
```curl
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
-u "<>:" \
-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:
```json
{
"id": "tax_1MEFACI6rIcR421eHrjXCSmD",
"object": "tax.transaction",
"created": 1670863656,
"currency": "eur",
...
"line_items": {
"object": "list",
"data": [
{
"id": "tax_li_MyBXC98AhtaR37",
"object": "tax.transaction_line_item",
"amount": -4999,
"amount_tax": -1150,
"livemode": false,
"metadata": {
},
"quantity": 1,
"reference": "L1",
"reversal": {
"original_line_item": "tax_li_MyBXPByrSUwm6r"
},
"tax_behavior": "exclusive",
"tax_code": "txcd_10000000",
"type": "reversal"
}
],
"has_more": false,
"total_count": 1,
"url": "/v1/tax/transactions/tax_1MEFACI6rIcR421eHrjXCSmD/line_items"
},
"livemode": false,
"metadata": {
"refund": "{{REFUND_ID}}",
"description": "Refunding pi_123456789 (customer was unhappy)"
},
"reference": "pi_123456789-refund_1",
"reversal": {
"original_transaction": "tax_1MEFAAI6rIcR421eB1YOzACZ"
},
"shipping_cost": null,
"tax_date": 1670863654,
"type": "reversal"
}
```
Für jeden stornierten Posten müssen Sie den stornierten `amount` und `amount_tax` angeben. Der `amount` ist inklusive Steuern, wenn die ursprüngliche Berechnung des Postens inklusive Steuern war.
Wie `amount` und `amount_tax` ermittelt werden, hängt von Ihrer Situation ab:
- Wenn Ihre Transaktionen immer nur einen einzigen Posten enthalten, verwenden Sie stattdessen [vollständige Stornierungen](https://docs.stripe.com/tax/custom.md#reversals-full).
- Wenn Sie immer ganze Posten erstatten, verwenden Sie die ursprünglichen Transaktionsposten `amount` und `amount_tax`, jedoch mit negativen Vorzeichen.
- Wenn Sie Teile von Einzelposten zurückerstatten, müssen Sie die zurückerstatteten Beträge berechnen. Zum Beispiel: Bei einer Verkaufstransaktion mit `amount=5000` und `amount_tax=500` erstellen Sie nach der Rückerstattung der Hälfte des Postens eine Teilrückbuchung mit Posten `amount=-2500` und `amount_tax=-250`.
#### Steuerberichte mit teilweisen Rückerstattungen
Wenn Sie einen Steuerbetrag so zurückerstatten, dass die gesamte Steuer nicht mehr proportional zur Zwischensumme ist, kann das Ihre Steuerberichterstattung unzuverlässig machen. Die steuerpflichtigen und nicht steuerpflichtigen Beträge werden nicht automatisch angepasst und der Grund für die Stornierung der Steuer (z. B. Produkt ausgenommen, Kunde/Kundin ausgenommen oder Umkehrung der Steuerschuld) wird nicht widergespiegelt. Wir empfehlen, keine Steuerbeträge für Teilposten zurückzuerstatten. Stornieren Sie stattdessen die Transaktion vollständig und erstellen Sie eine neue mit entsprechenden Eingaben für eine genaue Steuerberechnung.
### 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
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
-u "<>:" \
-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 USD of pi_234567890 (customer was unhappy)" \
-d "expand[]=line_items"
```
Dadurch wird die erstellte Teilstornotransaktion zurückgegeben:
```json
{
"id": "tax_1NVcQYBUZ691iUZ4SBPukGa6",
"object": "tax.transaction",
"created": 1689780994,
"currency": "usd",
...
"line_items": {
"object": "list",
"data": [
{
"id": "tax_li_OICqymcWjlbevq",
"object": "tax.transaction_line_item",
"amount": -500,
"amount_tax": -50,
"livemode": false,
"metadata": {},
"product": null,
"quantity": 1,
"reference": "refund_li_1",
"reversal": {
"original_line_item": "tax_li_OICmRXkFuWr8Df"
},
"tax_behavior": "exclusive",
"tax_code": "txcd_10103000",
"type": "reversal"
},
{
"id": "tax_li_OICq2H1qHjwyzX",
"object": "tax.transaction_line_item",
"amount": -1000,
"amount_tax": -100,
"livemode": false,
"metadata": {},
"product": null,
"quantity": 1,
"reference": "refund_li_2",
"reversal": {
"original_line_item": "tax_li_OICmxhnSJxF7rY"
},
"tax_behavior": "exclusive",
"tax_code": "txcd_10103000",
"type": "reversal"
}
],
"has_more": false,
"total_count": 2,
"url": "/v1/tax/transactions/tax_1NVcQYBUZ691iUZ4SBPukGa6/line_items"
},
"livemode": false,
"metadata": {
"refund": "{{REFUND_ID}}",
"description": "Refunding pi_234567890 (customer was unhappy)"
},
"reference": "pi_234567890-refund_1",
"reversal": {
"original_transaction": "tax_1NVcKqBUZ691iUZ4xMZtcGYt"
},
"shipping_cost": null,
"tax_date": 1670863654,
"type": "reversal"
}
```
Rückerstattungsbeträge und Steuern 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.
1. 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 Postens und des verbleibenden Gesamtbetrags der Transaktion. Das kann z. B. so aussehen: Der Posten 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`.
1. Abschließend wird der zu erstattende Gesamtbetrag auf `amount` und `amount_tax` aufgeteilt. Auch das 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 dem für die Transaktion *noch zu erstattenden* Betrag aufgeteilt, nicht entsprechend dem ursprünglich erfassten Betrag. Anstatt beispielsweise eine Erstattung in Höhe von pauschal 16,50 USD zu erfassen, erfassen Sie zunächst eine Teilstornierung für den Gesamtbetrag des Postens im Wert von 10 USD:
```curl
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
-u "<>:" \
-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
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
-u "<>:" \
-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 USD of pi_234567890 (customer was still unhappy)" \
-d "expand[]=line_items"
```
Das gibt die teilweise Stornotransaktion zurück:
```json
{
"id": "tax_1NVxFIBUZ691iUZ4saOIloxB",
"object": "tax.transaction",
"created": 1689861020,
"currency": "usd",
...
"line_items": {
"object": "list",
"data": [
{
"id": "tax_li_OIYM8xd8BzrATd",
"object": "tax.transaction_line_item",
"amount": 0,
"amount_tax": 0,
"livemode": false,
"metadata": {},
"product": null,
"quantity": 1,
"reference": "refund_li_1",
"reversal": {
"original_line_item": "tax_li_OICmRXkFuWr8Df"
},
"tax_behavior": "exclusive",
"tax_code": "txcd_10103000",
"type": "reversal"
},
{
"id": "tax_li_OIYMNBH6s8oQj9",
"object": "tax.transaction_line_item",
"amount": -1500,
"amount_tax": -150,
"livemode": false,
"metadata": {},
"product": null,
"quantity": 1,
"reference": "refund_li_2",
"reversal": {
"original_line_item": "tax_li_OICmxhnSJxF7rY"
},
"tax_behavior": "exclusive",
"tax_code": "txcd_10103000",
"type": "reversal"
}
],
"has_more": false,
"total_count": 2,
"url": "/v1/tax/transactions/tax_1NVxFIBUZ691iUZ4saOIloxB/line_items"
},
"livemode": false,
"metadata": {},
"reference": "pi_234567890-refund_2",
"reversal": {
"original_transaction": "tax_1NVcKqBUZ691iUZ4xMZtcGYt"
},
"shipping_cost": null,
"tax_date": 1670863654,
"type": "reversal"
}
```
Da der verbleibende Gesamtbetrag der Transaktion jetzt 22,00 USD beträgt und der Posten in Höhe von 10 USD vollständig zurückerstattet wird, werden die 16,50 USD vollständig auf den Posten ü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 Teilrückerstattung stornieren, indem Sie eine [vollständige Stornierung](https://docs.stripe.com/api/tax/transactions/create_reversal.md#tax_transaction_create_reversal-mode) erstellen.
Dies kann in folgenden Fällen erforderlich sein:
- Die [Rückerstattung der Zahlung schlägt fehl](https://docs.stripe.com/refunds.md#failed-refunds) und Sie haben die Ware oder Dienstleistung Ihrer Kundin oder Ihrem Kunden nicht bereitgestellt
- Die falsche Bestellung oder die falschen Beträge werden zurückerstattet
- Der ursprüngliche Verkauf wird vollständig zurückerstattet und die Teilrückerstattungen sind nicht mehr gültig
Im folgenden Beispiel ist `tax_1MEFACI6rIcR421eHrjXCSmD` die Transaktion, die die Teilrückerstattung darstellt:
```curl
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
-u "<>:" \
-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 selected the wrong item" \
-d "expand[]=line_items"
```
Dadurch wird die erstellte vollständige Stornotransaktion zurückgegeben:
```json
{
"id": "tax_1MEFADI6rIcR421e94fNTOCK",
"object": "tax.transaction",
"created": 1670863657,
"currency": "eur",
...
"line_items": {
"object": "list",
"data": [
{
"id": "tax_li_MyBXMOlwenCyFB",
"object": "tax.transaction_line_item",
"amount": 4999,
"amount_tax": 1150,
"livemode": false,
"metadata": {
},
"quantity": 1,
"reference": "L1",
"reversal": {
"original_line_item": "tax_li_MyBXC98AhtaR37"
},
"tax_behavior": "exclusive",
"tax_code": "txcd_10000000",
"type": "reversal"
}
],
"has_more": false,
"total_count": 1,
"url": "/v1/tax/transactions/tax_1MEFADI6rIcR421e94fNTOCK/line_items"
},
"livemode": false,
"metadata": {
"refund_reason": "User called to cancel because they picked the wrong item"
},
"reference": "pi_123456789-refund_1-cancel",
"reversal": {
"original_transaction": "tax_1MEFACI6rIcR421eHrjXCSmD"
},
"shipping_cost": null,
"tax_date": 1670863654,
"type": "reversal"
}
```
## Testen
Verwenden Sie *Sandboxes* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes), deren Antwortstruktur mit dem Live-Modus identisch ist, um sicherzustellen, dass Ihre Integration korrekt funktioniert, bevor Sie live gehen.
> In Testumgebungen ist nicht garantiert, dass die Berechnungen aktuelle Steuerergebnisse liefern. Sie sind auf 1.000 Steuerberechnungen pro Tag beschränkt. Wenn Sie ein höheres Limit benötigen, wenden Sie sich bitte an den [Stripe-Support](https://support.stripe.com/contact). Hinweise zu automatisierten Tests und Strategien zur Umgehung von Begrenzungen in Testumgebungen finden Sie unter [Automatisierte Tests](https://docs.stripe.com/automated-testing.md).
## Steuertransaktionen anzeigen
Sie können alle Steuertransaktionen für Ihr Konto auf der Seite [Steuertransaktionen](https://dashboard.stripe.com/test/tax/transactions) im Dashboard einsehen. Klicken Sie auf eine einzelne Transaktion, um eine detaillierte Aufschlüsselung der berechneten Steuern nach Zuständigkeitsbereich und nach einzelnen Produkten anzuzeigen, die in der Transaktion enthalten sind.
> Die Steuertransaktionsseite enthält nur *Transaktionen* und keine *Berechnungen*. Wenn Sie eine Berechnung erwarten und sie auf dieser Seite nicht finden können, überprüfen Sie, ob Sie aus der Berechnung [erfolgreich eine Steuertransaktion erstellt haben](https://docs.stripe.com/tax/custom.md#tax-transaction).
## Optional: Integrationsbeispiele
Sie können Steuern für Ihre Kundin oder Ihren Kunden berechnen, bevor Sie Zahlungsmethode erfassen und [einen PaymentIntent erstellen](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=paymentintents#web-create-intent). Beispielsweise können Sie den Gesamtbetrag des Warenkorbs anzeigen, wenn die Kundin oder der Kunde die Postleitzahl angibt.
Im folgenden Beispiel definiert Ihr Server einen Endpoint `/preview-cart`, an den die Kundenadresse von Ihrem clientseitigen Formular gesendet wird. Der Server kombiniert die Posten des Warenkorbs mit der Kundenadresse, um die Steuer zu berechnen.
#### Node.js
```javascript
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = require('stripe')('<>');
const express = require('express');
const app = express();
// Parse the request body as JSON.
app.use(express.json());
app.post('/preview-cart', async (req, res) => {
const cart = ...; // Load the cart/order from your system
// Convert each cart item to a Stripe line item object
const lineItems = cart.items.map(
cartItem => ({
reference: cartItem.id,
amount: cartItem.unitPrice * cartItem.quantity,
quantity: cartItem.quantity
})
);
// Get the customer's address from the request body
const address = req.body.address;
// Create a tax calculation using the Stripe API
const calculation = await stripe.tax.calculations.create({
currency: cart.currency,
line_items: lineItems,
customer_details: {
address: {
line1: address.line1,
city: address.city,
state: address.state,
postal_code: address.postal_code,
country: address.country,
},
address_source: "billing"
},
expand: ['line_items.data.tax_breakdown']
});
// Return the tax amount as a JSON response
res.json({
tax_amount: calculation.tax_amount_exclusive
});
});
app.listen(4242, () => {
console.log('Running on port 4242');
});
```
Wenn Sie bereit sind, Zahlungen entgegenzunehmen, erstellen Sie einen PaymentIntent aus dem Ergebnis der Steuerberechnung. Speichern Sie die Steuerberechnungs-ID in den [Metadaten](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-metadata) des PaymentIntent oder in Ihrer eigenen Datenbank, damit Sie eine Steuertransaktion erstellen können, wenn Ihre Kundin oder Ihr Kunde die Zahlung abschließt.
Das folgende Beispiel zeigt einen Server-Endpunkt, der die Steuer berechnet, einen PaymentIntent erstellt (oder aktualisiert) und das Ergebnis an den Client zurückgibt. Sie können dann die Steuer für Ihre Kundin oder Ihren Kunden anzeigen. Verwenden Sie das `client_secret`, um [die Zahlung anzunehmen](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=paymentintents#web-collect-payment-details).
#### Node.js
```javascript
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = require('stripe')('<>');
const express = require('express');
const app = express();
// Parse the request body as JSON.
app.use(express.json());
app.post('/calculate-cart', async (req, res) => {
const cart = ...; // Load the cart/order from your system
// Create a tax calculation using the Stripe API
const calculation = await stripe.tax.calculations.create(...);
let paymentIntent;
// Update the PaymentIntent if one already exists for this cart.
if (cart.paymentIntent) {
paymentIntent = await stripe.paymentIntents.update(cart.paymentIntent, {
amount: calculation.amount_total,
metadata: {tax_calculation: calculation.id},
});
} else {
paymentIntent = await stripe.paymentIntents.create({
currency: cart.currency,
amount: calculation.amount_total,
metadata: {tax_calculation: calculation.id},
// In the latest version of the API, specifying the `automatic_payment_methods` parameter is optional because Stripe enables its functionality by default.
automatic_payment_methods: {enabled: true},
});
}
// Store PaymentIntent ID in cart or customer session.
cart.paymentIntent = paymentIntent.id;
// Return calculated amounts and PaymentIntent secret to the client.
res.json({
total: calculation.amount_total,
tax_amount: calculation.tax_amount_exclusive,
client_secret: paymentIntent.client_secret
});
});
app.listen(4242, () => {
console.log('Running on port 4242');
});
```
Wenn Ihre Integration das Payment Element verwendet, [rufen Sie Updates vom Server ab](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=paymentintents#fetch-updates), nachdem Sie den PaymentIntent aktualisiert haben.
## Optional: Berechnung der Steuer auf die Versandkosten [Serverseitig]
Verwenden Sie den Parameter `shipping_cost`, um die Steuer auf die Versandkosten zu berechnen:
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-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" \
-d "shipping_cost[amount]=500" \
-d "shipping_cost[tax_code]=txcd_92010001"
```
Übergeben Sie die ID einer vorhandenen [ShippingRate](https://docs.stripe.com/api/shipping_rates/object.md), um dessen `amount`, `tax_code` und `tax_behavior` zu verwenden:
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-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" \
-d "shipping_cost[shipping_rate]=shr_1Mlh8YI6rIcR421eUr9SJzAD"
```
## Optional: Steuern mit einer IP-Adresse schätzen [Serverseitig]
Wenn Sie die [IP-Adresse](https://docs.stripe.com/api/tax/calculations/create.md#calculate_tax-customer_details-ip_address) Ihrer Kundinnen und Kunden angeben, wird sie geolokalisiert und als Kundenstandort verwendet. Auf diese Weise können Sie Kundinnen und Kunden eine Steuerschätzung anzeigen, bevor sie ihre Postanschrift angeben.
> Da der Standort einer IP-Adresse möglicherweise weit vom tatsächlichen Standort der Kundin oder des Kunden entfernt ist, raten wir davon ab, eine IP-Adresse zur Ermittlung des *endgültigen* Steuerbetrags zu verwenden.
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=usd \
-d "line_items[0][amount]=1000" \
-d "line_items[0][reference]=L1" \
-d "customer_details[ip_address]=127.0.0.1"
```
## Optional: Steueridentifikationsnummern von Kundinnen und Kunden erfassen [Serverseitig]
In einigen Fällen, wie etwa bei grenzüberschreitenden Dienstleistungen, muss Ihre Kundin oder Ihr Kunde die Steuer möglicherweise auf [Reverse-Charge](https://docs.stripe.com/tax/zero-tax.md#reverse-charges)-Basis abrechnen. Anstatt die Steuer einzuziehen, müssen Sie eine Rechnung mit dem Text „Steuer vom Leistungsempfänger zu zahlen“ ausstellen. Dies informiert Ihre Kundin oder Ihren Kunden darüber, dass sie oder er für die Steuer auf den Kauf verantwortlich ist.
Geben Sie die [Steueridentifikationsnummern](https://docs.stripe.com/api/tax/calculations/create.md#calculate_tax-customer_details-tax_ids) Ihrer Kundinnen und Kunden an, um automatisch zu bestimmen, wann die Umkehrung der Steuerschuld (Reverse Charge) angewendet wird:
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=usd \
-d "line_items[0][amount]=1000" \
-d "line_items[0][reference]=L1" \
-d "customer_details[address][country]=IE" \
-d "customer_details[address_source]=billing" \
-d "customer_details[tax_ids][0][type]=eu_vat" \
-d "customer_details[tax_ids][0][value]=DE123456789"
```
Wenn Sie eine Steueridentifikationsnummer mit einem ungültigen Format angeben, gibt die Berechnung den Fehlercode `tax_id_invalid` zurück:
```json
{
"error": {
"code": "tax_id_invalid",
"doc_url": "https://docs.stripe.com/error-codes#tax-id-invalid",
"message": "Invalid value for eu_vat.",
"param": "customer_details[tax_ids][0][value]",
"type": "invalid_request_error"
}
}
```
Die Tax API validiert Steueridentifikationsnummern nicht automatisch gegen staatliche Datenbanken. Um eine Steueridentifikationsnummer vor der Steuerberechnung zu validieren, müssen Sie die [Validierung der Kunden-Steueridentifikationsnummer](https://docs.stripe.com/billing/customer/tax-ids.md#validation) verwenden.
## Optional: Preisangaben inklusive Steuern [Serverseitig]
Standardmäßig wird die Steuer zusätzlich zu den von Ihnen angegebenen Beträgen für Einzelposten und Versandkosten berechnet. Um die in Ihren Preisen enthaltene Steuer zu berechnen, setzen Sie `tax_behavior` für den [Einzelposten](https://docs.stripe.com/api/tax/calculations/create.md#calculate_tax-line_items-tax_behavior) oder die [Versandkosten](https://docs.stripe.com/api/tax/calculations/create.md#calculate_tax-shipping_cost-tax_behavior) auf `inklusive`.
Im folgenden Beispiel zahlt die Kundin oder der immer 100 EUR:
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=eur \
-d "line_items[0][amount]=10000" \
-d "line_items[0][reference]=L1" \
-d "line_items[0][tax_behavior]=inclusive" \
-d "line_items[0][tax_code]=txcd_10103000" \
-d "customer_details[address][country]=IE" \
-d "customer_details[address_source]=billing"
```
Die Antwort gibt die enthaltene Steuer zurück:
```json
{
...
"amount_total": 10000,
...
"tax_amount_exclusive": 0,"tax_amount_inclusive": 1870,
"tax_breakdown": [
{
"amount": 1870,
"inclusive": true,
"tax_rate_details": {
"country": "IE",
"percentage_decimal": "23.0",
"state": null,
"tax_type": "vat"
},
"taxability_reason": "standard_rated",
"taxable_amount": 8130
}
],
...
}
```
## Optional: Ein vorhandenes Produktobjekt verwenden [Serverseitig]
Sie können für jeden Posten ein [Produktobjekt](https://docs.stripe.com/api/products/object.md) angeben. Wenn das Produkt einen [tax_code](https://docs.stripe.com/api/products/object.md#product_object-tax_code) hat, verwenden wir diesen als `tax_code` – sofern er nicht bereits ausgefüllt ist. Andere Produktwerte einschließlich `tax_behavior` und `Preis` werden bei der Steuerberechnung nicht berücksichtigt.
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=usd \
-d "line_items[0][amount]=1000" \
-d "line_items[0][reference]=L1" \
-d "line_items[0][product]={{PRODUCT_ID}}" \
-d "customer_details[address][country]=IE" \
-d "customer_details[address_source]=billing"
```
## Optional: Bestehendes Konto oder bestehende/n Kundin/Kunden verwenden [Serverseitig]
Bei der Steuer-Berechnung werden automatisch die entsprechende Adresse und Steueridentifikationsnummern [der Kundin/des Kunden](https://docs.stripe.com/api/customers/object.md) entsprechend der Verfügbarkeit der Kundendaten verwendet:
- Die Versandadresse der Kundin/des Kunden wird im Feld `customer_details.address` der Berechnung eingepflegt.
- Andernfalls wird im Feld `customer_details.address` der Berechnung die Adresse der Kundin/des Kunden eingepflegt.
- Die IP-Adresse der Kundin/des Kunden wird im Feld `customer_details.ip_address` der Berechnung eingepflegt.
- Wenn für die Kundin/den Kunden eine Steuerbefreiung gilt, wird der Wert im Feld `customer_details.taxability_override` der Berechnung eingepflegt.
- Die Steuer-IDs der Kundin/des Kunden werden im Feld `customer_details.tax_ids` der Berechnung eingepflegt.
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=usd \
-d "line_items[0][amount]=1000" \
-d "line_items[0][reference]=L1" \
-d "customer={{CUSTOMER_ID}}"
```
## Optional: Kundensteuerbarkeit aufheben [Serverseitig]
In bestimmten Fällen müssen Sie keine Steuer erheben, z. B. wenn Ihre Kundin oder Ihr Kunde steuerbefreit ist. Sie können die Steuerbefreiung über den Parameter [taxability_override](https://docs.stripe.com/api/tax/calculations/create.md#calculate_tax-customer_details-taxability_override) an Stripe Tax übermitteln.
So geben Sie die Überschreibung der Kundensteuerpflicht in Ihren Berechnungen an:
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-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]=billing" \
-d "customer_details[taxability_override]=customer_exempt"
```
### Umkehrung der Steuerschuld
In einigen Regionen, wie z. B. in der Europäischen Union, gilt ein „Reverse-Charge“-System, bei dem Kundinnen und Kunden für die Abrechnung der Steuern verantwortlich ist, wenn sie als Unternehmen einkaufen. Damit Stripe Tax die korrekte steuerliche Behandlung anwendet, empfehlen wir Ihnen, [Steueridentifikationsnummern](https://docs.stripe.com/tax/custom.md#tax-ids) von Ihren Kundinnen und Kunden zu erfassen. Manchmal liegen Ihnen die Steueridentifikationsnummern Ihrer Kundinnen und Kunden nicht vor oder Sie haben separat festgelegt, dass die Umkehrung der Steuerschuld gilt. In solchen Fällen können Sie `taxability_override` verwenden, um Stripe Tax zu zwingen, das Reverse-Charge-Verfahren anzuwenden.
So geben Sie die Überschreibung der Kundensteuerpflicht in Ihren Berechnungen an:
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=eur \
-d "line_items[0][amount]=1000" \
-d "line_items[0][reference]=L1" \
-d "customer_details[address][country]=IE" \
-d "customer_details[address_source]=billing" \
-d "customer_details[taxability_override]=reverse_charge"
```
## Optional: Einen Absenderort angeben [Serverseitig]
Wenn Sie Waren von einem anderen Standort als Ihrem Hauptgeschäftssitz aus versenden, können Sie diese Adresse für die Steuerberechnungen angeben.
Verwenden Sie den Parameter `ship_from_details`, um einen Absenderort anzugeben. In diesem Beispiel ist der/die Nutzer/in in Florida ansässig, der Kunde/die Kundin ist in Springfield, IL und der/die Nutzer/in versendet die Waren aus Naperville, IL:
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=usd \
-d "line_items[0][amount]=1000" \
-d "line_items[0][reference]=L1" \
-d "line_items[0][tax_behavior]=exclusive" \
-d "line_items[0][tax_code]=txcd_99999999" \
-d "customer_details[address][city]=Springfield" \
-d "customer_details[address][state]=IL" \
-d "customer_details[address][postal_code]=62704" \
-d "customer_details[address][country]=US" \
-d "customer_details[address_source]=billing" \
-d "ship_from_details[address][city]=Naperville" \
-d "ship_from_details[address][state]=IL" \
-d "ship_from_details[address][postal_code]=60540" \
-d "ship_from_details[address][country]=US"
```
Die Antwort gibt die berechnete Steuer basierend auf dem Versandort der Bestellung (Naperville, IL) zurück, anstatt auf dem Bestimmungsort (Springfield, IL) oder dem Geschäftssitz der Verkäuferin oder des Verkäufers:
```json
{
...
"amount_total": 1078,
...
"tax_amount_exclusive": 78,
...
"tax_breakdown": [
{
"amount": 78,
"inclusive": true,"tax_rate_details": {
"country": "US",
"percentage_decimal": "7.75",
"state": "IL",
"tax_type": "sales_tax"
},
"taxability_reason": "standard_rated",
"taxable_amount": 1000
}
],
...
}
```
Weitere Informationen zur Berechnung von Steuern in diesen Szenarien finden Sie in der [Dokumentation zu Stripe Tax](https://docs.stripe.com/tax/calculating.md).
## Optional: Einzelhandelsliefergebühr berechnen [Serverseitig]
Stripe Tax unterstützt die Berechnung der Liefergebühr für Einzelhändler/innen in Minnesota und Colorado.
Nachdem Sie in den unterstützten Bundesstaaten eine Steuerregistrierung vom Typ `state_retail_delivery_fee` hinzugefügt haben, wird die Liefergebühr für Einzelhändler/innen anhand von Steuerberechnungen berechnet.
```curl
curl https://api.stripe.com/v1/tax/registrations \
-u "<>:" \
-d country=US \
-d "country_options[us][state]=CO" \
-d "country_options[us][type]=state_retail_delivery_fee" \
-d active_from=now
```
Um die Liefergebühr für Einzelhändler/innen zu berechnen, rufen Sie die Tax Calculations API unter Verwendung eines [Steuercodes für physische Posten](https://docs.stripe.com/tax/tax-codes.md?type=physical) auf, z. B. `txcd_30011000`, der für Kleidung und Schuhe steht.
Nicht alle physischen Artikel lösen die Berechnung der Liefergebühr für Einzelhändler/innen aus. Informationen dazu, wann die Steuer anfällt, finden Sie in der Dokumentation des jeweiligen Bundesstaats:
- [Einzelhandelsliefergebühr – Colorado](https://docs.stripe.com/tax/supported-countries/united-states/collect-tax.md?tax-jurisdiction-united-states=colorado#other-taxes)
- [Einzelhandelsliefergebühr – Minnesota](https://docs.stripe.com/tax/supported-countries/united-states/collect-tax.md?tax-jurisdiction-united-states=minnesota#other-taxes)
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=usd \
-d "line_items[0][amount]=1000" \
-d "line_items[0][reference]=L1" \
-d "line_items[0][tax_behavior]=exclusive" \
-d "line_items[0][tax_code]=txcd_30011000" \
-d "shipping_cost[amount]=400" \
-d "customer_details[address][line1]=1437 Bannock St Room 451" \
-d "customer_details[address][city]=Springfield" \
-d "customer_details[address][state]=CO" \
-d "customer_details[address][postal_code]=80202" \
-d "customer_details[address][country]=US" \
-d "customer_details[address_source]=shipping"
```
Die Antwort gibt die berechnete Steuer mit der Liefergebühr für Einzelhändler/innen für Colorado zurück. Diese erscheint als zusätzlicher Eintrag im `tax_breakdown-`Objekt, wobei `tax_breakdown.tax_rate_details.rate_type` auf `flat_amount` gesetzt ist:
```json
{
...
"amount_total": 2165,
...
"tax_amount_exclusive": 165,
...
"tax_breakdown": [
{
"amount": 88,
"inclusive": false,
"tax_rate_details": {
"percentage_decimal": "8.81",
"rate_type": "percentage",
"tax_type": "sales_tax",
...
},
"taxability_reason": "standard_rated",
"taxable_amount": 1000
},
...
{
"amount": 29,
"inclusive": false,"tax_rate_details": {
"flat_amount": {
"amount": 29,
"currency": "usd"
},
"percentage_decimal": "0.0",
"rate_type": "flat_amount",
"tax_type": "retail_delivery_fee",
...
},
"taxability_reason": "standard_rated",
"taxable_amount": 1000
}
],
...
}
```
## Optional: Detaillierte Aufschlüsselung der Steuern nach Posten [Serverseitig]
Die übergeordnete [tax_breakdown](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-tax_breakdown) wird immer zurückgegeben und bietet eine einfache Aufschlüsselung, die sich für die Anzeige einer Liste von Steuern beim Bezahlvorgang oder auf einem Zahlungsbeleg eignet.
Sie können den [taxability_reason](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-line_items-data-tax_breakdown-taxability_reason) verwenden, um zu verstehen, warum während der Integration keine Steuer angewendet wird. Zum Beispiel bedeutet `not_collecting`, dass in dem Land oder Bundesstaat, in dem die Steuer fällig wäre, keine Steuer erhoben wird. Durch das Hinzufügen von [Steuerregistrierungen](https://docs.stripe.com/tax/set-up.md#add-registrations) zu Ihren Kontoeinstellungen geben Sie Stripe an, wo Sie Steuern erheben. Wenn Sie eine Registrierung für Washington hinzugefügt haben, wird in Ihrem Ergebnis als Steuerpflichtgrund `standard_rated` angezeigt, was darauf hinweist, dass das Produkt zum Standardsatz besteuert wird.
Erweitern Sie das Attribut [tax_breakdown](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-line_items-data-tax_breakdown) des Postens, um eine detaillierte Aufschlüsselung einschließlich lokaler Steuern und Attribute zu erhalten, die den Grund für die einzelnen Steuern erklären.
- Das Feld `tax_type` aus [tax_rate_details](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-line_items-data-tax_breakdown-tax_rate_details) ist eine übergeordnete Angabe zum Steuertyp, die möglicherweise nicht immer mit dem in Berichten und Transaktionen zurückgegebenen Typ übereinstimmt. Beispielsweise wird nicht zwischen US-amerikanischer Sales Tax und Use Tax unterschieden.
- Verwenden Sie das Feld `display_name` aus [tax_rate_details](https://docs.stripe.com/api/tax/calculations/object.md#tax_calculation_object-line_items-data-tax_breakdown-tax_rate_details) in Ihrem Bezahlvorgang, um alle Steuern anzuzeigen. Die Steuern werden basierend auf dem Standort der Kundin oder des Kunden und den Steuerinformationen des Produkts lokalisiert. Wenn beispielsweise für Deutschland die Umsatzsteuer (USt.) angewendet wird, weil sich die Kundin oder der Kunde in Deutschland befindet und das Produkt am Bestimmungsort besteuert wird – etwa [txcd_10103001: Software as a service (SaaS) for business use](https://docs.stripe.com/tax/tax-codes.md?tax_code=txcd_10103001) –, wird `Umsatzsteuer (USt)` angezeigt, also die deutsche Bezeichnung für VAT. Wenn dagegen für Frankreich Umsatzsteuer (VAT) angewendet wird, weil die Firmenadresse in Frankreich liegt und das Produkt am Ursprungsort besteuert wird – etwa [txcd_20030000: General – Services](https://docs.stripe.com/tax/tax-codes.md?tax_code=txcd_20030000) –, wird `Taxe sur la valeur ajoutée (TVA)` angezeigt, also die französische Bezeichnung für VAT.
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-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" \
-d "expand[0]=line_items.data.tax_breakdown"
```
```json
{
...
"tax_breakdown": [
{
"amount": 103,
"inclusive": false,
"tax_rate_details": {
"country": "US",
"percentage_decimal": "10.25",
"state": "WA",
"tax_type": "sales_tax"
},"taxability_reason": "standard_rated",
"taxable_amount": 1000
}
],
"line_items": {
"object": "list",
"data": [
{
"id": "tax_li_O84jA8hvV7ZyAa",
"object": "tax.calculation_line_item",
"amount": 1000,
"amount_tax": 103,
"product": null,
"quantity": 1,
"reference": "L1",
"tax_behavior": "exclusive",
"tax_breakdown": [
{
"amount": 65,
"jurisdiction": {
"country": "US",
"display_name": "Washington",
"level": "state",
"state": "WA"
},
"sourcing": "destination",
"tax_rate_details": {
"display_name": "Retail Sales and Use Tax",
"percentage_decimal": "6.5",
"tax_type": "sales_tax"
},"taxability_reason": "standard_rated",
"taxable_amount": 1000
},
{
"amount": 0,
"jurisdiction": {
"country": "US",
"display_name": "KING",
"level": "county",
"state": "WA"
},
"sourcing": "destination",
"tax_rate_details": null,"taxability_reason": "not_subject_to_tax",
"taxable_amount": 0
},
{
"amount": 22,
"jurisdiction": {
"country": "US",
"display_name": "SEATTLE",
"level": "city",
"state": "WA"
},
"sourcing": "destination",
"tax_rate_details": {
"display_name": "Local Sales and Use Tax",
"percentage_decimal": "2.2",
"tax_type": "sales_tax"
},"taxability_reason": "standard_rated",
"taxable_amount": 1000
},
{
"amount": 14,
"jurisdiction": {
"country": "US",
"display_name": "REGIONAL TRANSIT AUTHORITY",
"level": "district",
"state": "WA"
},
"sourcing": "destination",
"tax_rate_details": {
"display_name": "Local Sales and Use Tax",
"percentage_decimal": "1.4",
"tax_type": "sales_tax"
},"taxability_reason": "standard_rated",
"taxable_amount": 1000
},
{
"amount": 2,
"jurisdiction": {
"country": "US",
"display_name": "SEATTLE TRANSPORTATION BENEFIT DISTRICT",
"level": "district",
"state": "WA"
},
"sourcing": "destination",
"tax_rate_details": {
"display_name": "Local Sales and Use Tax",
"percentage_decimal": "0.15",
"tax_type": "sales_tax"
},"taxability_reason": "standard_rated",
"taxable_amount": 1000
}
],
"tax_code": "txcd_10000000"
}
],
"has_more": false,
"total_count": 1,
"url": "/v1/tax/calculations/taxcalc_1NLoZvBUZ691iUZ4z4cTW6tQ/line_items"
},
...
}
```
## Optional: Häufige Fehler beheben [Serverseitig]
Befolgen Sie die folgenden Schritte, um Fehler in Ihrer Steuerintegration zu beheben.
### Fehler wegen ungültiger Steuercodes beheben
Wenn Sie einen `Ungültiger Steuercode`-Fehler erhalten, können Sie in den [Produktsteuercodes](https://docs.stripe.com/tax/tax-codes.md) eine Liste der verfügbaren Steuercodes einsehen. Gehen Sie dann wie folgt vor, um das Problem zu beheben:
1. **Prüfen Sie den Steuercode**: Stellen Sie sicher, dass Sie einen gültigen Steuercode aus der [Liste der verfügbaren Steuercodes](https://docs.stripe.com/tax/tax-codes.md) verwenden. Häufige Fehler sind:
- Leere Zeichenfolge oder `null` als Steuercode verwenden
- Falsch geschriebener Steuercode
- Verwenden eines nicht vorhandenen Steuercodes
1. **Aktualisieren Sie Ihren Code**: Achten Sie darauf, beim Erstellen einer `TaxCalculation` einen gültigen Steuercode zu übergeben. Zum Beispiel:
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=usd \
-d "line_items[0][amount]=1000" \
-d "line_items[0][reference]=L1" \
-d "line_items[0][tax_code]=txcd_10000000" \
-d "customer_details[address][line1]=354 Oyster Point Blvd" \
-d "customer_details[address][city]=South San Francisco" \
-d "customer_details[address][state]=CA" \
-d "customer_details[address][postal_code]=94080" \
-d "customer_details[address][country]=US" \
-d "customer_details[address_source]=shipping"
```
1. **Verwenden Sie den Standard-Steuercode**: Stripe Tax verwendet einen Standard-Steuercode für Berechnungen, wenn kein spezifischer Steuercode für ein Produkt oder in einer Steuerberechnungsanfrage angegeben ist. Den Standardwert können Sie in Ihren Steuereinstellungen einsehen und aktualisieren.
Verwenden Sie die API, um den Standard-Steuercode zu aktualisieren:
```curl
curl https://api.stripe.com/v1/tax/settings \
-u "<>:" \
-d "defaults[tax_code]=txcd_10000000"
```
1. **Überprüfen Sie Ihren Produktkatalog**: Wenn Sie Steuercodes verwenden, die mit Produkten in Ihrem Stripe-Produktkatalog verknüpft sind, stellen Sie sicher, dass die Steuercodes Ihren Produkten korrekt zugeordnet sind.
1. **Überprüfen Sie die Daten auf Inkonsistenzen**: Stellen Sie sicher, dass der Steuercode korrekt aus Ihrer Datenbank oder Ihrem Frontend an Ihren serverseitigen Code übergeben wird, der den API-Aufruf an Stripe ausführt.
Verwenden Sie für genauere Steuerberechnungen den spezifischsten Steuercode, der für Ihr Produkt oder Ihre Dienstleistung gilt. Wenn Sie sich nicht sicher sind, welchen Steuercode Sie verwenden sollen, lesen Sie die [Dokumentation zu Steuercodes](https://docs.stripe.com/tax/tax-codes.md).
Wenn weiterhin Probleme auftreten, prüfen Sie die [Dokumentation zur Tax Settings API](https://docs.stripe.com/api/tax/settings.md).
## Steueridentifikationsnummern von Kundinnen und Kunden erfassen
Die Anzeige der Steueridentifikationsnummer und des rechtlichen Unternehmensnamens einer Kundin/eines Kunden auf *Rechnungen* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) ist eine gängige Anforderung. Sie können das [Steueridentifikationsnummern-Element](https://docs.stripe.com/elements/tax-id-element.md) verwenden, um diese Informationen zu erfassen. Diese Funktion befindet sich in der [öffentlichen Vorschau](https://docs.stripe.com/release-phases.md).
> #### Haftungsausschluss
>
> Die Payment Intents API wurde entwickelt, um Steueridentifikationsnummern von Unternehmen zu erfassen, die in bestimmten Zuständigkeitsbereichen ähnliche Formate wie persönliche Steueridentifikationsnummern haben können. Sie müssen sicherstellen, dass bei der Verwendung dieser Funktion nur Steueridentifikationsnummern von Unternehmen angegeben werden, wie für dieses Feld vorgesehen.
### Beta aktivieren
Für das Steueridentifikationsnummernelement mit der Payment Intents API müssen Sie die Beta `elements_tax_id_1` aktivieren. Fügen Sie Beta zu Ihrer Stripe.js-Initialisierung hinzu:
```javascript
const stripe = Stripe('<>', {
betas: ['elements_tax_id_1'],
});
```
### Erstellen Sie eine CustomerSession (optional)
Um Steueridentifikationsnummern zu speichern und für wiederkehrende Kundinnen und Kunden erneut anzuzeigen, erstellen Sie eine [CustomerSession](https://docs.stripe.com/api/customer_sessions.md), die einen sicheren, vorübergehenden Zugriff auf die Kundendaten bietet, ohne Ihren geheimen API-Schlüssel dem Client gegenüber offenzulegen.
Wenn Sie die `CustomerSession` nicht verwenden, funktioniert das Tax ID Element weiterhin, jedoch ohne Speicher- und Wiederanzeigefunktionen. Sie können [getValue](https://docs.stripe.com/js/elements_object/get_value_tax_id_element) verwenden, um die Werte der Steueridentifikationsnummern aus dem Element auszulesen und manuell zu verarbeiten.
#### Customer v1
Erstellen oder Abrufen einer/eines *Kundin/Kunden* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments):
```curl
curl https://api.stripe.com/v1/customers \
-u "<>:" \
--data-urlencode "email=customer@example.com" \
-d "name=Jenny Rosen"
```
Erstellen einer `CustomerSession` mit aktivierter Komponente des Tax ID Elements:
```curl
curl https://api.stripe.com/v1/customer_sessions \
-u "<>:" \
-H "Stripe-Version: 2026-04-22.preview" \
-d "customer={{CUSTOMER_ID}}" \
-d "components[tax_id_element][enabled]=true" \
-d "components[tax_id_element][features][tax_id_redisplay]=enabled" \
-d "components[tax_id_element][features][tax_id_save]=enabled"
```
Die `CustomerSession` gibt ein `client_secret` zurück, das Sie an den Client übergeben.
### PaymentIntent oder SetupIntent erstellen
Erstellen Sie einen [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) oder einen [SetupIntent](https://docs.stripe.com/api/setup_intents.md) auf Ihrem Server. Fügen Sie bei Verwendung der `CustomerSession` den Kunden-Referenzparameter ein, um die Speicherung der Steueridentifikationsnummer zu aktivieren und die Funktionalität erneut anzuzeigen:
#### Customer v1
```curl
curl https://api.stripe.com/v1/payment_intents \
-u "<>:" \
-d amount=1099 \
-d currency=usd \
-d "customer={{CUSTOMER_ID}}"
```
> Sie müssen beim Erstellen des Payment Intents oder des Setup Intents keine für die Steueridentifikationsnummer spezifischen Parameter angeben. Das Tax ID Element übernimmt automatisch die Erfassung der Steueridentifikationsnummer und speichert sie für die/den *Kundin/Kunden* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments), wenn eine Kundensitzung mit den entsprechenden Berechtigungen vorhanden ist.
### Initialisieren Sie Elements
Erstellen Sie eine Elements-Instanz mit dem `clientSecret` aus Ihrem PaymentIntent oder SetupIntent.
Um Steueridentifikationsnummern für eine Kundin/einen Kunden zu speichern und für wiederkehrende Kundinnen/Kunden erneut anzuzeigen, fügen Sie das `customerSessionClientSecret` ein:
```javascript
const stripe = Stripe('<>', {
betas: ['elements_tax_id_1'],
});
// Fetch the clientSecret from your server
const {clientSecret} = await fetch('/create-payment-intent', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
}).then((res) => res.json());
// Fetch the customerSessionClientSecret from your server
const {customerSessionClientSecret} = await fetch('/create-customer-session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
}).then((res) => res.json());
const elements = stripe.elements({
clientSecret,customerSessionClientSecret,
appearance: { /* ... */ }
});
```
### Steueridentifikationsnummernelement erstellen und verbinden
Erstellen Sie eine Instanz des Steueridentifikationsnummernelements und binden Sie sie in Ihre Seite ein:
```html
```
```javascript
const taxIdElement = elements.create('taxId', {
visibility: 'auto', // 'auto' | 'always' | 'never'
});
taxIdElement.mount('#tax-id-element');
```
Sie können das Steueridentifikationsnummer-Element mit Optionen wie `visibility`, `fields` und `validation` anpassen. Weitere Informationen finden Sie unter [Erstellen eines Steueridentifikationsnummer-Elements](https://docs.stripe.com/js/elements_object/create_tax_id_element).
### Verwendung mit dem Adresselement (optional)
Wenn Sie das Steueridentifikationsnummernelement zusammen mit dem [Adresselement](https://docs.stripe.com/elements/address-element.md) verwenden, ermittelt Stripe automatisch die Art der Steueridentifikationsnummer und das Element anhand der Adresse der Kundin/des Kunden.
### Zahlung abschließen
Wenn die Kundin/der Kunde das Zahlungsformular absendet, rufen Sie [confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) oder [confirmSetup](https://docs.stripe.com/js/setup_intents/confirm_setup) auf. Stripe übernimmt automatisch die Steueridentifikationsnummer und speichert sie bei erfolgreicher Zahlung für die Kundin/den Kunden:
```javascript
const form = document.getElementById('payment-form');
form.addEventListener('submit', async (event) => {
event.preventDefault();
const {error} = await stripe.confirmPayment({
elements,
confirmParams: {
return_url: 'https://example.com/order/complete',
},
});
if (error) {
// Handle error
console.error(error.message);
}
// Customer gets redirected to return_url if successful
});
```
Sie können [getValue](https://docs.stripe.com/js/elements_object/get_value_tax_id_element) auch auf Client-Seite verwenden, um die Steueridentifikationsnummern vor der Übermittlung der Zahlung zu lesen.
### Ihre Integration testen
In Testumgebungen können Sie jede alphanumerische Zeichenfolge eingeben, die das korrekte Format eines unterstützten Steuer-ID-Typs (z. B. `DE123456789` für `eu_vat`) aufweist. Eine vollständige Liste beispielhafter Steuer-IDs finden Sie im [Leitfaden zur Kundensteuer-ID](https://docs.stripe.com/billing/customer/tax-ids.md#supported-tax-id). Sie können auch unsere [Test-Steuer-IDs](https://docs.stripe.com/connect/testing.md#test-business-tax-ids) verwenden, um verschiedene Verifizierungsabläufe zu testen.
### Asynchrone Validierung der Steueridentifikationsnummer
Während der Zahlung oder Einrichtungsbestätigung verifiziert Stripe, dass die angegebenen Steueridentifikationsnummern korrekt formatiert sind, jedoch nicht deren Gültigkeit wird. Sie sind dafür verantwortlich, die Gültigkeit der Kundendaten sicherzustellen. Zur Unterstützung führt Stripe automatisch eine asynchrone Validierung mit staatlichen Datenbanken für [australische Unternehmensnummern (ABNs)](https://docs.stripe.com/tax/invoicing/tax-ids.md#australian-business-numbers-abn), [EU-Umsatzsteuer-Identifikationsnummern](https://docs.stripe.com/tax/invoicing/tax-ids.md#european-value-added-tax-eu-vat-numbers) (EU-USt.) und [Umsatzsteuer-Identifikationsnummern](https://docs.stripe.com/tax/invoicing/tax-ids.md#united-kingdom-value-added-tax-gb-vat-numbers) im Vereinigten Königreich (GB-USt.) durch. Erfahren Sie mehr über die von [uns durchgeführte Validierung](https://docs.stripe.com/tax/invoicing/tax-ids.md#validation) und wie Sie den Status dieser Prüfungen aufrufen können.
### Validierung der Steueridentifikationsnummer in Echtzeit (Preview)
Zusätzlich zu der oben beschriebenen asynchronen Validierung können Sie die synchrone Echtzeit-Verifizierung der Steueridentifikationsnummer direkt im Element „Steueridentifikationsnummer“ aktivieren. Wenn Sie diese aktivieren, verifiziert Stripe Steueridentifikationsnummern anhand staatlicher Datenbanken, während Ihre Kundin/Ihr Kunde Eingaben macht und das Ergebnis inline anzeigt, bevor sie/er die Zahlung übermitteln. Stripe unterstützt derzeit die Echtzeit-Verifizierung für [australische Unternehmensnummern (ABNs)](https://docs.stripe.com/tax/invoicing/tax-ids.md#australian-business-numbers-abn), die [europäische Umsatzsteuer (EU VAT) ](https://docs.stripe.com/tax/invoicing/tax-ids.md#european-value-added-tax-eu-vat-numbers)und [USt.-Steuernummern des Vereinigten Königreichs](https://docs.stripe.com/tax/invoicing/tax-ids.md#united-kingdom-value-added-tax-gb-vat-numbers). Wenn eine staatliche Datenbank nicht verfügbar ist, greift Stripe auf die synchrone Formatvalidierung zurück und führt die vollständige Verifizierung asynchron durch. Diese Funktion befindet sich in der [öffentlichen Vorschau](https://docs.stripe.com/release-phases.md) und erfordert die `elements_tax_id_verification_1`-Betaversion.
```javascript
const taxIdElement = elements.create('taxId', {
...
verification: {
taxId: {
mode: 'if_supported',
},
},
});
```
Wenn Sie die Verifizierung aktivieren, enthält das `change`-Ereignis das Feld `verification.taxId.status`. Sein Wert kann `pending`, `verified`, `unverified` oder `unavailable` sein. Der Status `complete` des Elements spiegelt das Verifizierungsergebnis wider. Weitere Informationen finden Sie unter [Ein Steueridentifikationsnummer-Element erstellen](https://docs.stripe.com/js/elements_object/create_tax_id_element#tax_id_element_create-options-verification) und [Steueridentifikationsnummer-Element in der Änderung](https://docs.stripe.com/js/element/events/on_change?type=taxIdElement#element_on_change-handler-verification).
### Unterstützte Steuer-ID-Typen
Das Steueridentifikationsnummernelement unterstützt die Erfassung von Steueridentifikationsnummern in den folgenden Ländern und Regionen:
| Country | Enum | Description | Example | Impact in Tax Calculation* |
| ------- | ---------- | --------------------------------------------------------------------------- | -------------------- | -------------------------- |
| AE | ae_trn | United Arab Emirates TRN | 123456789012345 | Yes |
| AL | al_tin | Albania Tax Identification Number | J12345678N | Yes |
| AM | am_tin | Armenia Tax Identification Number | 02538904 | Yes |
| AO | ao_tin | Angola Tax Identification Number | 5123456789 | No |
| AT | eu_vat | European VAT number | ATU12345678 | Yes |
| AU | au_abn | Australian Business Number (AU ABN) | 12345678912 | Yes |
| AW | aw_tin | Aruba Tax Identification Number | 12345678 | Yes |
| AZ | az_tin | Azerbaijan Tax Identification Number | 0123456789 | Yes |
| BA | ba_tin | Bosnia and Herzegovina Tax Identification Number | 123456789012 | Yes |
| BB | bb_tin | Barbados Tax Identification Number | 1123456789012 | No |
| BD | bd_bin | Bangladesh Business Identification Number | 123456789-0123 | Yes |
| BE | eu_vat | European VAT number | BE0123456789 | Yes |
| BF | bf_ifu | Burkina Faso Tax Identification Number (Numéro d'Identifiant Fiscal Unique) | 12345678A | Yes |
| BG | eu_vat | European VAT number | BG0123456789 | Yes |
| BH | bh_vat | Bahraini VAT Number | 123456789012345 | Yes |
| BJ | bj_ifu | Benin Tax Identification Number (Identifiant Fiscal Unique) | 1234567890123 | Yes |
| BS | bs_tin | Bahamas Tax Identification Number | 123.456.789 | No |
| BY | by_tin | Belarus TIN Number | 123456789 | Yes |
| CA | ca_bn | Canadian BN | 123456789 | No |
| CA | ca_gst_hst | Canadian GST/HST number | 123456789RT0002 | Yes |
| CA | ca_pst_bc | Canadian PST number (British Columbia) | PST-1234-5678 | No |
| CA | ca_pst_mb | Canadian PST number (Manitoba) | 123456-7 | No |
| CA | ca_pst_sk | Canadian PST number (Saskatchewan) | 1234567 | No |
| CA | ca_qst | Canadian QST number (Québec) | 1234567890TQ1234 | Yes |
| CD | cd_nif | Congo (DR) Tax Identification Number (Número de Identificação Fiscal) | A0123456M | No |
| CH | ch_vat | Switzerland VAT number | CHE-123.456.789 MWST | Yes |
| CL | cl_tin | Chilean TIN | 12.345.678-K | Yes |
| CM | cm_niu | Cameroon Tax Identification Number (Numéro d'Identifiant fiscal Unique) | M123456789000L | No |
| CR | cr_tin | Costa Rican tax ID | 1-234-567890 | No |
| CV | cv_nif | Cape Verde Tax Identification Number (Número de Identificação Fiscal) | 213456789 | No |
| CY | eu_vat | European VAT number | CY12345678Z | Yes |
| CZ | eu_vat | European VAT number | CZ1234567890 | Yes |
| DE | eu_vat | European VAT number | DE123456789 | Yes |
| DK | eu_vat | European VAT number | DK12345678 | Yes |
| EC | ec_ruc | Ecuadorian RUC number | 1234567890001 | No |
| EE | eu_vat | European VAT number | EE123456789 | Yes |
| EG | eg_tin | Egyptian Tax Identification Number | 123456789 | Yes |
| ES | es_cif | Spanish NIF number (previously Spanish CIF number) | A12345678 | No |
| ES | eu_vat | European VAT number | ESA1234567Z | Yes |
| ET | et_tin | Ethiopia Tax Identification Number | 1234567890 | Yes |
| FI | eu_vat | European VAT number | FI12345678 | Yes |
| FR | eu_vat | European VAT number | FRAB123456789 | Yes |
| GB | eu_vat | Northern Ireland VAT number | XI123456789 | Yes |
| GB | gb_vat | United Kingdom VAT number | GB123456789 | Yes |
| GE | ge_vat | Georgian VAT | 123456789 | Yes |
| GN | gn_nif | Guinea Tax Identification Number (Número de Identificação Fiscal) | 123456789 | Yes |
| GR | eu_vat | European VAT number | EL123456789 | Yes |
| HR | eu_vat | European VAT number | HR12345678912 | Yes |
| HU | eu_vat | European VAT number | HU12345678 | Yes |
| HU | hu_tin | Hungary tax number (adószám) | 12345678-1-23 | No |
| IE | eu_vat | European VAT number | IE1234567AB | Yes |
| IN | in_gst | Indian GST number | 12ABCDE3456FGZH | Yes |
| IS | is_vat | Icelandic VAT | 123456 | Yes |
| IT | eu_vat | European VAT number | IT12345678912 | Yes |
| KE | ke_pin | Kenya Revenue Authority Personal Identification Number | P000111111A | No |
| KG | kg_tin | Kyrgyzstan Tax Identification Number | 12345678901234 | No |
| KH | kh_tin | Cambodia Tax Identification Number | 1001-123456789 | Yes |
| KR | kr_brn | Korean BRN | 123-45-67890 | Yes |
| KZ | kz_bin | Kazakhstani Business Identification Number | 123456789012 | Yes |
| LA | la_tin | Laos Tax Identification Number | 123456789-000 | No |
| LI | li_vat | Liechtensteinian VAT number | 12345 | Yes |
| LK | lk_vat | Sri Lanka VAT number | 123456789-1234 | Yes |
| LT | eu_vat | European VAT number | LT123456789123 | Yes |
| LU | eu_vat | European VAT number | LU12345678 | Yes |
| LV | eu_vat | European VAT number | LV12345678912 | Yes |
| MA | ma_vat | Morocco VAT Number | 12345678 | Yes |
| MD | md_vat | Moldova VAT Number | 1234567 | Yes |
| ME | me_pib | Montenegro PIB Number | 12345678 | No |
| MK | mk_vat | North Macedonia VAT Number | MK1234567890123 | Yes |
| MR | mr_nif | Mauritania Tax Identification Number (Número de Identificação Fiscal) | 12345678 | No |
| MT | eu_vat | European VAT number | MT12345678 | Yes |
| MX | mx_rfc | Mexican RFC number | ABC010203AB9 | No |
| NG | ng_tin | Nigerian Tax Identification Number | 12345678-0001 | No |
| NL | eu_vat | European VAT number | NL123456789B12 | Yes |
| NO | no_vat | Norwegian VAT number | 123456789MVA | Yes |
| NP | np_pan | Nepal PAN Number | 123456789 | Yes |
| NZ | nz_gst | New Zealand GST number | 123456789 | Yes |
| OM | om_vat | Omani VAT Number | OM1234567890 | Yes |
| PE | pe_ruc | Peruvian RUC number | 12345678901 | Yes |
| PH | ph_tin | Philippines Tax Identification Number | 123456789012 | Yes |
| PL | eu_vat | European VAT number | PL1234567890 | Yes |
| PL | pl_nip | Polish NIP number | 1234567890 | No |
| PT | eu_vat | European VAT number | PT123456789 | Yes |
| RO | eu_vat | European VAT number | RO1234567891 | Yes |
| RS | rs_pib | Serbian PIB number | 123456789 | No |
| RU | ru_inn | Russian INN | 1234567891 | Yes |
| RU | ru_kpp | Russian KPP | 123456789 | Yes |
| SA | sa_vat | Saudi Arabia VAT | 123456789012345 | Yes |
| SE | eu_vat | European VAT number | SE123456789123 | Yes |
| SG | sg_gst | Singaporean GST | M12345678X | Yes |
| SI | eu_vat | European VAT number | SI12345678 | Yes |
| SK | eu_vat | European VAT number | SK1234567891 | Yes |
| SN | sn_ninea | Senegal NINEA Number | 12345672A2 | No |
| SR | sr_fin | Suriname FIN Number | 1234567890 | Yes |
| TH | th_vat | Thai VAT | 1234567891234 | Yes |
| TJ | tj_tin | Tajikistan Tax Identification Number | 123456789 | Yes |
| TR | tr_tin | Turkish Tax Identification Number | 0123456789 | Yes |
| TW | tw_vat | Taiwanese VAT | 12345678 | Yes |
| TZ | tz_vat | Tanzania VAT Number | 12345678A | Yes |
| UA | ua_vat | Ukrainian VAT | 123456789 | Yes |
| UG | ug_tin | Uganda Tax Identification Number | 1014751879 | Yes |
| UY | uy_ruc | Uruguayan RUC number | 123456789012 | Yes |
| UZ | uz_tin | Uzbekistan TIN Number | 123456789 | No |
| UZ | uz_vat | Uzbekistan VAT Number | 123456789012 | Yes |
| ZA | za_vat | South African VAT number | 4123456789 | Yes |
| ZM | zm_tin | Zambia Tax Identification Number | 1004751879 | No |
| ZW | zw_tin | Zimbabwe Tax Identification Number | 1234567890 | No |
\*Stripe Tax won't apply tax if this tax ID is provided, in line with the relevant laws.
### Steueridentifikationsnummer in Berechnungen verwenden (optional)
In einigen Fällen, wie etwa bei grenzüberschreitenden Dienstleistungen, muss Ihre Kundin/Ihr Kunde die Steuer möglicherweise auf [Reverse Charge](https://docs.stripe.com/tax/zero-tax.md#reverse-charges)-Basis abrechnen. Anstatt die Steuer einzuziehen, müssen Sie eine Rechnung mit dem Text „Umkehrung der Steuerschuld“ ausstellen.
Wenn Sie die [Steueridentifikationsnummern](https://docs.stripe.com/api/tax/calculations/create.md#calculate_tax-customer_details-tax_ids) Ihrer Kundin/Ihres Kunden an Stripe Tax übermitteln, ermitteln wir automatisch, wann die Umkehrung der Steuerschuld angewendet werden muss:
```curl
curl https://api.stripe.com/v1/tax/calculations \
-u "<>:" \
-d currency=usd \
-d "line_items[0][amount]=1000" \
-d "line_items[0][reference]=L1" \
-d "customer_details[address][country]=IE" \
-d "customer_details[address_source]=billing" \
-d "customer_details[tax_ids][0][type]=eu_vat" \
-d "customer_details[tax_ids][0][value]=DE123456789"
```
Wenn Sie eine Steueridentifikationsnummer mit einem ungültigen Format angeben, gibt die Berechnung den Fehlercode `tax_id_invalid` zurück.
## See also
- [Stripe Tax mit Connect verwenden](https://docs.stripe.com/tax/connect.md)