Steuer-IDs mit Checkout erfassen

Wenn die Erfassung von Steuer-IDs aktiviert ist, wird das Formular zur Erfassung von Steuer-IDs je nach Standort Ihrer Kundin/Ihres Kunden in Checkout angezeigt oder verborgen. Unterstützt die Erfassung von Steuer-IDs den Standort Ihrer Kundin/Ihres Kunden, wird in Checkout ein entsprechendes Kontrollkästchen angezeigt, mit dem die Kundin/der Kunde angeben kann, dass der Kauf geschäftlich ist. Wird das Kontrollkästchen aktiviert, werden in Checkout Felder zur Eingabe der Steuer-ID und des rechtsgültigen Namens des Unternehmens angezeigt. Checkout verwendet zur Standortbestimmung die Versandadresse der Kundin/des Kunden (sofern vorhanden); andernfalls wird die Rechnungsadresse der Kundin/des Kunden verwendet. Kundinnen/Kunden können nur eine Steuer-ID eingeben.

Neue Kundinnen/Kunden

Um die Erfassung von Steuer-IDs für neue Kundinnen/Kunden zu aktivieren, legen Sie tax_id_collection[enabled] beim Erstellen einer Checkout-Sitzung auf true fest.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "tax_id_collection[enabled]"=true \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Mit diesem Beispiel wird eine Sitzung im payment-Modus mit aktivierter Erfassung der Steuer-ID erstellt. Nehmen Sie für Abonnements die gleichen Änderungen vor, wobei der Modus auf subscription festgelegt ist.

Sie können Checkout zusätzlich so konfigurieren, dass ein/e neue/r Kunde/Kundin für Sie mit customer_creation erstellt wird. Wenn Sie dies tun, speichert Checkout alle während einer Sitzung erfassten Steuer-ID-Informationen für diese/n neue/n Kunden/Kundin. Andernfalls sind die Steuerinformationen weiterhin unter customer_details.tax_ids verfügbar.

Bestehende Kundinnen/Kunden

Wenn Sie beim Erstellen einer Sitzung bestehende Kundinnen/Kunden übergeben, aktualisiert Checkout für die Kundinnen/Kunden alle während der Sitzung erfassten Steuer-ID-Angaben. Checkout speichert den erfassten Unternehmensnamen in der Eigenschaft Name der Kundin/des Kunden und fügt die erfasste Steuer-ID dem Array customer.tax_ids hinzu. Da die Erfassung eines Unternehmensnamens dazu führen könnte, dass der bestehende Name des Kunden/der Kundin überschrieben wird, müssen Sie customer_update.name beim Erstellen der Sitzung auf auto festlegen.

Bei der Erfassung von Steuer-IDs bestehender Kundinnen/Kunden können Sie deren Standort entweder anhand bestehender Adressen der Kundinnen/Kunden oder der beim Bezahlvorgang eingegebenen Adressen festlegen. Zur Standortbestimmung sucht Checkout standardmäßig nach bestehenden Adressen der Kundinnen/Kunden:

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Wenn Sie die Adressen Ihrer bestehenden Kundinnen/Kunden nicht gespeichert haben, können Sie deren Standort anhand der während des Bezahlvorgangs eingegebenen Rechnungs- oder Versandadresse ermitteln. Um anzugeben, dass Sie die beim Bezahlvorgang eingegebene Rechnungsadresse verwenden möchten, um den Standort des Kunden zu bestimmen, müssen Sie customer_update.address auf auto setzen. Wenn Sie customer_update.address auf auto setzen, ersetzt Checkout alle zuvor gespeicherten Adressen des Kunden/der Kunden durch die während der Sitzung eingegebene Adresse.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d "customer_update[address]"=auto \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Wenn Sie Versandadressen für bestehende Kundinnen/Kunden erfassen, muss deren Standort der beim Bezahlvorgang eingegebenen Versandadresse entsprechen. Legen Sie hierzu customer_update.shipping auf auto fest. Wenn customer_update.shipping auf auto festgelegt wird, ersetzt Checkout alle zuvor gespeicherten Versandadressen für den Kunden/die Kundin durch die während der Sitzung eingegebene Versandadresse.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=cus_HQmikpKnGHkNwW \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d "customer_update[shipping]"=auto \
  -d "shipping_address_collection[allowed_countries][0]"=DE \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Mit dem obigen Codebeispiel wird eine Sitzung im payment-Modus mit aktivierter Erfassung der Steuer-ID erstellt. Nehmen Sie für Abonnements die gleichen Änderungen vor, wobei der Modus auf subscription festgelegt ist.

Checkout fügt die angegebenen Steuer-IDs in das resultierende Session-Objekt ein. Nach jeder abgeschlossenen Sitzung gibt Checkout ein checkout.session.completed-Ereignis aus, das Sie in einem Webhook-Endpoint überwachen können. Wenn Sie die erfasste Steuer-ID aus dem Session-Objekt abrufen möchten, ist sie unter dem customer_details.tax_ids-Array der Sitzung verfügbar:

{
  "object": {
    "id": "cs_test_a1dJwt0TCJTBsDkbK7RcoyJ91vJxe2Y",
    "object": "checkout.session",
    ...
    "customer": "cus_id_of_new_customer",
    "customer_details": {
      ...
      "tax_ids": [
        {
          "type": "eu_vat",
          "value": "FRAB123456789"
        }
      ]
    },
    ...
    "tax_id_collection": {
      "enabled": true
    },
    ...
  }
}

Checkout speichert auch die erfassten Steueridentifikationsnummern und Unternehmensnamen im Kundenobjekt, wenn eines mit der Sitzung verknüpft ist. Auf eine während des Bezahlvorgangs erfasste Steueridentifikationsnummer kann unter dem customer.tax_ids-Array der Kundin/des Kunden zugegriffen werden. Sie können außerdem alle mit einer Kundin/einem Kunden verknüpften Steueridentifikationsnummern mit der Ressource Steuer-IDs abrufen, indem Sie den Parameter owner.type auf customer festlegen und für owner.customer die ID der Kundin/des Kunden angeben. Jede neue Steueridentifikationsnummer enthält einen zugehörigen rechtsgültigen Firmennamen, den Checkout in der Eigenschaft Name der Kundin/des Kunden speichert. Auf diese Weise ist der erfasste rechtsgültige Firmenname immer auf allen Abonnementrechnungen für diese Kundin/diesen Kunden sichtbar.

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. Sie können auch unsere Test-Steuer-IDs verwenden, um verschiedene Verifizierungsabläufe zu testen.