Steuer-IDs mit Checkout erfassen

Neue Kundinnen/Kunden

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

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d ui_mode=custom \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "tax_id_collection[enabled]"=true \
  -d mode=payment \
  --data-urlencode return_url="https://example.com/return"

Bestehende Kund/innen

Erstellen Sie eine Checkout-Sitzung mit einer bestehenden Kundin bzw. einem bestehenden Kunden, um diese mit allen während des Bezahlvorgangs erfassten Steuer-ID-Informationen zu aktualisieren. Die Checkout-Sitzung speichert den erfassten Unternehmensnamen als Name des Kunden/der Kundin und fügt die erfasste Steueridentifikationsnummer zu customer.tax_ids hinzu. Da durch die Erfassung eines Unternehmensnamens der Name des Kunden/der Kundin überschrieben werden kann, müssen Sie customer_update.name auf auto festlegen, wenn Sie die Checkout-Sitzung erstellen.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d ui_mode=custom \
  -d customer=
{{CUSTOMER_ID}} \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d mode=payment \
  --data-urlencode return_url="https://example.com/return"

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 festlegen. Um die während des Bezahlvorgangs eingegebene Rechnungsadresse zur Beurteilung des Kundenstandorts zu verwenden, legen Sie customer_update.address auf auto fest. Wenn Sie customer_update.address auf auto festlegen, werden alle zuvor für den Kunden/die Kundin gespeicherten Adressen durch die beim Bezahlvorgang eingegebene Adresse ersetzt.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d ui_mode=custom \
  -d customer=
{{CUSTOMER_ID}} \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d "customer_update[address]"=auto \
  -d mode=payment \
  --data-urlencode return_url="https://example.com/return"

Wenn Sie Versandadressen für bestehende Kundinnen/Kunden erfassen, muss deren Standort der während des Bezahlvorgangs eingegebenen Versandadresse entsprechen, indem Sie customer_update.shipping auf auto festlegen. Wenn Sie customer_update.shipping auf auto fetlegen, werden alle zuvor für den Kunden/die Kundin gespeicherten Versandadressen durch die beim Bezahlvorgang eingegebene Versandadresse ersetzt.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d ui_mode=custom \
  -d customer=
{{CUSTOMER_ID}} \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -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 return_url="https://example.com/return"

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.

Verwenden Sie das Steueridentifikationsnummer-Element von Stripe, um Steueridentifikationsnummern zu erheben.

import {useMemo} from 'react',
import {loadStripe} from '@stripe/stripe-js';
import {CheckoutProvider, TaxIdElement} from '@stripe/react-stripe-js';

const stripePromise = loadStripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx', {
  betas: [
    'custom_checkout_tax_id_1',
  ],
});

const App = () => {
  const fetchClientSecret = useMemo(() => {
    return fetch('/create-checkout-session', {method: 'POST'})
      .then((res) => res.json())
      .then((data) => data.clientSecret)
  }, []);

  return (
    <CheckoutProvider
      stripe={stripePromise}
      options={{
        fetchClientSecret: () => fetchClientSecret,
      }}
    >
      <TaxIdElement />
    <CheckoutProvider>
  );
};

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.