# Integration mit der Invoicing API Erfahren Sie, wie Sie mithilfe von Code eine Rechnung erstellen und senden. Am häufigsten werden [Rechnungen](https://docs.stripe.com/invoicing/dashboard.md#create-invoice) über das [Dashboard](https://dashboard.stripe.com/invoices) erstellt. Wenn Sie die Rechnungserstellung automatisieren möchten, können Sie die API integrieren. Erstellen Sie eine vollständige, funktionierende Invoicing-Integration mit unserer [Beispielintegration](https://docs.stripe.com/invoicing/integration/quickstart.md). ## Stripe einrichten Nutzen Sie unsere offiziellen Bibliotheken für den Zugriff auf die Stripe-API: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## Produkt erstellen Geben Sie den Namen eines Produkts ein, um es zu erstellen: ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ -d name="Gold Special" ``` ## Preis erstellen Anhand von [Preisen](https://docs.stripe.com/api.md#prices) wird festgelegt, wie viel und wie oft für Produkte bezahlt werden muss. Dies umfasst den Preis des Produkts, die zu verwendende Währung und das Abrechnungsintervall (wenn der Preis für ein Abonnement gilt). Wenn Sie nur einige wenige Preise haben, sollten Sie diese wie bei Produkten im Dashboard verwalten. Verwenden Sie den Betrag für Einheiten, um die Preise in der kleinsten Einheit der Währung auszudrücken – in diesem Fall in Cent (10 USD entsprechen 1.000 Cent, der Betrag für Einheiten ist also 1000). Wenn Sie keinen Preis für Ihr Produkt erstellen müssen, können Sie alternativ den Parameter [amount](https://docs.stripe.com/api/invoiceitems/create.md#create_invoiceitem-amount) bei der Erstellung des Rechnungspostens verwenden. Um einen Preis zu erstellen und ihn dem Produkt zuzuweisen, übermitteln Sie die Produkt-ID, den Betrag pro Einheit und die Währung. Im folgenden Beispiel beträgt der Preis für das Produkt „Gold Special“ 10 USD: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product="{{PRODUCT_ID}}" \ -d unit_amount=1000 \ -d currency=usd ``` ## Kundin/Kunde erstellen Das [Kundenobjekt](https://docs.stripe.com/api.md#customer_object) stellt die Kundin oder den Kunden dar, der/die Ihr Produkt kauft, und ist zum Erstellen einer Rechnung erforderlich. Um [eine Kundin oder einen Kunden](https://docs.stripe.com/api/customers/create.md) mit `name`, `email` und `description` zu erstellen, fügen Sie den folgenden Code hinzu und ersetzen Sie die Werte durch Ihre eigenen: ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d name="Jenny Rosen" \ --data-urlencode email="jenny.rosen@example.com" \ -d description="My first customer" ``` Speichern Sie nach dem Erstellen des/der Kund/in die `id` des/der Kund/in zur späteren Verwendung in Ihrer Datenbank. Im nächsten Schritt wird zum Beispiel die Kunden-ID zum Erstellen einer Rechnung verwendet. ## Rechnung erstellen Legen Sie das Attribut [collection_method](https://docs.stripe.com/api/invoices/object.md#invoice_object-collection_method) auf `send_invoice` fest. Damit Stripe eine Rechnung als überfällig kennzeichnet, müssen Sie den Parameter [days_until_due](https://docs.stripe.com/api/invoices/create.md#create_invoice-days_until_due) hinzufügen. Wenn Sie eine Rechnung senden, sendet Stripe die Rechnung per E-Mail mit Zahlungsanweisungen an den Kunden/die Kundin. ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d collection_method=send_invoice \ -d days_until_due=30 ``` Erstellen Sie dann einen Rechnungsposten, indem Sie die `id` des/der Kund/in, den `price` des Produkts und die Rechnungs-ID der `invoice` übergeben. Die maximale Anzahl von Rechnungsposten ist 250. ```curl curl https://api.stripe.com/v1/invoiceitems \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d "pricing[price]"="{{PRICE_ID}}" \ -d invoice="{{INVOICE_ID}}" ``` Wenn Sie `auto_advance` auf `false` festlegen, können Sie die Rechnung bis zu ihrer [Finalisierung](https://docs.stripe.com/invoicing/integration/workflow-transitions.md) weiter bearbeiten. Finalisieren Sie einen Rechnungsentwurf über das Dashboard, übermitteln Sie ihn an den Kunden/die Kundin oder begleichen Sie die Rechnung. Sie können auch die [Finalize](https://docs.stripe.com/api/invoices/finalize.md) API verwenden: ```curl curl -X POST https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/finalize \ -u "<>:" ``` Wenn Sie eine Rechnung irrtümlich erstellen, [stornieren](https://docs.stripe.com/invoicing/overview.md#void) Sie sie. Sie können eine Rechnung auch als [uneinbringlich](https://docs.stripe.com/invoicing/overview.md#uncollectible) markieren. ## Rechnungszahlung akzeptieren #### Rechnung senden Senden Sie die Rechnung an die mit dem Kunden/der Kundin verknüpfte E-Mail-Adresse. Stripe finalisiert die Rechnung, sobald Sie sie senden. In vielen Zuständigkeitsbereichen gelten finalisierte Rechnungen als rechtliches Dokument, sodass bestimmte Felder nicht geändert werden können. Wenn Sie Rechnungen versenden, die bereits bezahlt wurden, gibt es in der E-Mail keinen Hinweis auf die Zahlung. > Wenn Sie bereits bezahlte Rechnungen versenden, enthält die E-Mail keinen Hinweis auf die Zahlung. (Stripe sendet Rechnungen an die mit dem/der Kund/in verknüpfte E-Mail-Adresse.) ```curl curl -X POST https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/send \ -u "<>:" ``` #### Stripe Elements Wenn die Rechnung finalisiert ist, wird ein *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) erzeugt und mit der Rechnung verknüpft. Verwenden Sie [Stripe Elements](https://docs.stripe.com/payments/elements.md), um Zahlungsdetails zu erfassen und den PaymentIntent der Rechnung zu bestätigen. Nachdem eine Rechnung finalisiert wurde, können Sie Geldwerte oder den Parameter `collection_method` nicht mehr bearbeiten. Diese Einschränkung gilt auch für den PaymentIntent der finalisierten Rechnung. Wenn Sie den PaymentIntent einer Rechnung mit einem [update](https://docs.stripe.com/api/payment_intents/update.md)-Aufruf aktualisieren, können Sie nur die Parameter `setup_future_usage`, `metadata`, `payment_method`, `description`, `receipt_email`, `payment_method_data`, `payment_method_options` und `shipping` ändern. #### Payment Element (empfohlen) Das [Payment Element](https://docs.stripe.com/payments/payment-element.md) erfasst sicher alle notwendigen Zahlungsdaten für eine Vielzahl von Zahlungsmethoden. Unter [Zahlungsmethoden und Produktsupport](https://docs.stripe.com/payments/payment-methods/payment-method-support.md) erfahren Sie, ob Ihre konfigurierten Zahlungsmethoden sowohl von Invoicing als auch vom Payment Element unterstützt werden. ### Das Client-Geheimnis an das Frontend übergeben Stripe.js verwendet das [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) des PaymentIntent, um den Zahlungsvorgang sicher abzuschließen. Rufen Sie das Client-Geheimnis der Rechnung ab, indem Sie das Attribut [confirmation_secret](https://docs.stripe.com/api/invoices/object.md#invoice_object-confirmation_secret) [erweitern](https://docs.stripe.com/api/expanding_objects.md), wenn Sie die Rechnung [finalisieren](https://docs.stripe.com/api/invoices/finalize.md) oder wenn Sie einen weiteren API-Aufruf, z. B. [Abrufen](https://docs.stripe.com/api/invoices/retrieve.md) oder [Aktualisieren](https://docs.stripe.com/api/invoices/update.md) für die Rechnung durchführen, nachdem Sie sie finalisiert haben. Geben Sie das `client_secret` an das Frontend zurück, um die Zahlung abzuschließen. ```curl curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/finalize \ -u "<>:" \ -d "expand[]"=confirmation_secret ``` Nachdem die Rechnung zurückgegeben wurde, greifen Sie über das erweiterte Feld `confirmation_secret` auf das Client-Geheimnis zu. #### curl #### Stripe-CLI #### Ruby ```ruby client_secret = invoice.confirmation_secret.client_secret ``` #### Python ```python client_secret = invoice.confirmation_secret.client_secret ``` #### PHP ```php $client_secret = $invoice->confirmation_secret->client_secret; ``` #### Java ```java String clientSecret = invoice.getConfirmationSecret().getClientSecret(); ``` #### Node.js ```javascript const client_secret = invoice.confirmation_secret.client_secret; ``` #### Go ```go clientSecret := invoice.ConfirmationSecret.ClientSecret, ``` #### .NET ```csharp var clientSecret = invoice.ConfirmationSecret.ClientSecret; ``` ### Stripe Elements Das Payment Element ist ein Feature von Stripe.js und steht damit automatisch zur Verfügung. Fügen Sie das Stripe.js-Skript auf Ihrer Bezahlseite ein, indem Sie es in den `head` Ihrer HTML-Datei einbinden. Laden Sie Stripe.js immer direkt von js.stripe.com, um PCI-Konformität zu gewährleisten. Fügen Sie das Skript nicht in ein Paket ein und hosten Sie selbst keine Kopie davon. ```html Pay Invoice ``` Erstellen Sie auf Ihrer Bezahlseite eine Instanz von Stripe mit dem folgenden JavaScript: ```javascript // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe('<>'); ``` ### Payment Element zu Ihrer Seite hinzufügen Das Payment Element benötigt einen festen Platz auf Ihrer Zahlungsseite. Erstellen Sie einen leeren DOM-Knoten (Container) mit einer eindeutigen ID in Ihrem Zahlungsformular. ```html
``` Sobald das Formular geladen wurde, erstellen Sie eine Instanz des Payment Element und verbinden Sie es mit dem Container-DOM-Knoten. Übergeben Sie das Client-Geheimnis des PaymentIntent als Option, wenn Sie eine Instanz von Elements erstellen. ```javascript const options = { clientSecret: '{{CLIENT_SECRET}}', // Fully customizable with appearance API. appearance: {/*...*/}, }; // Set up Stripe.js and Elements to use in your checkout form, passing in the client secret. const elements = stripe.elements(options); // Create and mount the Payment Element const paymentElementOptions = { layout: 'accordion'}; const paymentElement = elements.create('payment', paymentElementOptions); paymentElement.mount('#payment-element'); ``` Das Payment Element rendert ein dynamisches Formular, mit dem Ihr/e Kund/in eine Zahlungsmethode auswählen kann. Das Formular erfasst automatisch alle notwendigen Zahlungsdetails für die vom Kunden/von der Kundin ausgewählte Zahlungsmethode. Sie können das Payment Element an das Design Ihrer Website anpassen, indem Sie beim Erstellen einer Instanz von Elements das [Appearance-Objekt](https://docs.stripe.com/elements/appearance-api.md) an `options` übergeben. ### Zahlung abschließen Verwenden Sie `stripe.confirmPayment`, um die Zahlung mit den Angaben aus dem Payment Element abzuschließen. Dadurch wird eine Zahlungsmethode erstellt und der Payment Intent der Rechnung bestätigt, wodurch eine Zahlung vorgenommen wird. Wenn für die Zahlung die *starke Kundenauthentifizierung* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase) (SCA) erforderlich ist, führt das Payment Element das Authentifizierungsverfahren durch, bevor der Payment Intent bestätigt wird. Stellen Sie eine [return_url](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-return_url) für die Funktion `confirmPayment` bereit, um anzugeben, wohin Stripe Nutzer/innen nach Abschluss der Zahlung weiterleitet. Ihre Nutzer/innen werden möglicherweise zuerst an eine Zwischenseite weitergeleitet, z. B. eine Bankautorisierungsseite, bevor sie zur `return_url` weitergeleitet werden. Kartenzahlungen werden bei erfolgreicher Zahlung sofort an die `return_url` weitergeleitet. ```javascript const form = document.getElementById('payment-form'); form.addEventListener('submit', async (event) => { event.preventDefault(); const {error} = await stripe.confirmPayment({ //`Elements` instance that was used to create the Payment Element elements, confirmParams: { return_url: "https://example.com/order/123/complete", } }); if (error) { // This point will only be reached if there is an immediate error when // confirming the payment. Show error to your customer (for example, payment // details incomplete) const messageContainer = document.querySelector('#error-message'); messageContainer.textContent = error.message; } else { // Your customer will be redirected to your `return_url`. For some payment // methods like iDEAL, your customer will be redirected to an intermediate // site first to authorize the payment, then redirected to the `return_url`. } }); ``` Wenn Ihr Kunde/Ihre Kundin eine Zahlung übermittelt, leitet Stripe ihn an die `return_url` weiter und fügt die folgenden URL-Abfrageparameter ein. Die Rückgabeseite kann diese nutzen, um den Status des PaymentIntent abzurufen, damit der Kunde/die Kundin den Zahlungsstatus anzeigen kann. Wenn Sie die `return_url` angeben, können Sie auch Ihre eigenen Abfrageparameter für die Verwendung auf der Rückgabeseite anhängen. | Parameter | Beschreibung | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `payment_intent` | Die eindeutige ID für den `PaymentIntent`. | | `payment_intent_client_secret` | Das [Client-Geheimnis](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) des `PaymentIntent`-Objekts. Bei Abonnementintegrationen wird dieses client_secret auch über [`confirmation_secret`](https://docs.stripe.com/api/invoices/object.md#invoice_object-confirmation_secret) im `Invoice`-Objekt sichtbar gemacht | Wenn Kundinnen und Kunden auf Ihre Seite weitergeleitet werden, können Sie `payment_intent_client_secret` nutzen, um den PaymentIntent abzufragen und Ihren Kundinnen und Kunden den Transaktionsstatus anzuzeigen. > Wenn Sie über Tools verfügen, die die Browser-Sitzung der Kund/innen verfolgen, müssen Sie möglicherweise die Domain `stripe.com` zur Referenz-Ausschlussliste hinzufügen. Weiterleitungen haben zur Folge, dass einige Tools neue Sitzungen erstellen. Dies wiederum hindert Sie daran, die gesamte Sitzung zu verfolgen. Verwenden Sie den Abfrageparameter `payment_intent_client_secret`, um den Payment Intent abzurufen. Überprüfen Sie den [Status des Payment Intent](https://docs.stripe.com/payments/paymentintents/lifecycle.md), um zu entscheiden, was Ihren Kundinnen/Kunden angezeigt werden soll. Sie können bei der Angabe der `return_url` auch Ihre eigenen Abfrageparameter anhängen, die während des Weiterleitungsvorgangs erhalten bleiben. ```javascript // Initialize Stripe.js using your publishable key const stripe = Stripe('<>'); // Retrieve the "payment_intent_client_secret" query parameter appended to // your return_url by Stripe.js const clientSecret = new URLSearchParams(window.location.search).get( 'payment_intent_client_secret' ); // Retrieve the PaymentIntent stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => { const message = document.querySelector('#message') // Inspect the PaymentIntent `status` to indicate the status of the payment // to your customer. // // Some payment methods will [immediately succeed or fail][0] upon // confirmation, while others will first enter a `processing` state. // // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification switch (paymentIntent.status) { case 'succeeded': message.innerText = 'Success! Payment received.'; break; case 'processing': message.innerText = "Payment processing. We'll update you when payment is received."; break; case 'requires_payment_method': message.innerText = 'Payment failed. Please try another payment method.'; // Redirect your user back to your payment page to attempt collecting // payment again break; default: message.innerText = 'Something went wrong.'; break; } }); ``` #### Card Element Das Card Element erfasst und validiert Kreditkartendaten von Ihrem/Ihrer Nutzer/in auf sichere Weise. ### Das Client-Geheimnis an das Frontend übergeben Stripe.js verwendet das [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) des PaymentIntent, um den Zahlungsvorgang sicher abzuschließen. Rufen Sie das Client-Geheimnis der Rechnung ab, indem Sie das Attribut [confirmation_secret](https://docs.stripe.com/api/invoices/object.md#invoice_object-confirmation_secret) [erweitern](https://docs.stripe.com/api/expanding_objects.md), wenn Sie die Rechnung [finalisieren](https://docs.stripe.com/api/invoices/finalize.md) oder wenn Sie einen weiteren API-Aufruf, z. B. [Abrufen](https://docs.stripe.com/api/invoices/retrieve.md) oder [Aktualisieren](https://docs.stripe.com/api/invoices/update.md) für die Rechnung durchführen, nachdem Sie sie finalisiert haben. Geben Sie das `client_secret` an das Frontend zurück, um die Zahlung abzuschließen. ```curl curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/finalize \ -u "<>:" \ -d "expand[]"=confirmation_secret ``` Nachdem die Rechnung zurückgegeben wurde, greifen Sie über das erweiterte Feld `confirmation_secret` auf das Client-Geheimnis zu. #### curl #### Stripe-CLI #### Ruby ```ruby client_secret = invoice.confirmation_secret.client_secret ``` #### Python ```python client_secret = invoice.confirmation_secret.client_secret ``` #### PHP ```php $client_secret = $invoice->confirmation_secret->client_secret; ``` #### Java ```java String clientSecret = invoice.getConfirmationSecret().getClientSecret(); ``` #### Node.js ```javascript const client_secret = invoice.confirmation_secret.client_secret; ``` #### Go ```go clientSecret := invoice.ConfirmationSecret.ClientSecret, ``` #### .NET ```csharp var clientSecret = invoice.ConfirmationSecret.ClientSecret; ``` ### Stripe Elements Stripe Elements wird zusammen mit Stripe.js eingebunden. Binden Sie das Stripe.js-Skript in Ihre Zahlungsseite ein, indem Sie es im `head` Ihrer HTML-Datei einfügen. Laden Sie Stripe.js immer direkt von js.stripe.com, um die PCI-Compliance einzuhalten. Fügen Sie das Skript nicht in ein Paket ein und hosten Sie selbst keine Kopie davon. ```html Subscription prices ``` Erstellen Sie mit dem folgenden JavaScript eine Instanz von Elements: ```javascript // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys let stripe = Stripe('<>'); let elements = stripe.elements(); ``` ### Elements zu Ihrer Seite hinzufügen Weisen Sie Elements in Ihrem Zahlungsformular einen festen Platz zu. Erstellen Sie in Ihrem Zahlungsformular leere DOM-Nodes (Container) mit eindeutigen IDs und übergeben Sie diese IDs dann an Elements. ```html
``` Erstellen Sie eine Instanz eines Elements und verbinden Sie sie mit dem Element-Container: ```javascript let card = elements.create('card', { style: style }); card.mount('#card-element'); ``` Das `card`-Element vereinfacht das Zahlungsformular und minimiert durch ein einziges, flexibles Eingabefeld, mit dem alle notwendigen Kartenangaben sicher erfasst werden können, die Anzahl der Pflichtfelder. Eine vollständige Liste aller unterstützten Element-Typen finden Sie in unserer [Stripe.js-Referenz](https://docs.stripe.com/js.md#elements_create) Verwendne Sie die Testkartennummer **4242 4242 4242 4242**, eine beliebige CVC/Prüfziffer, ein beliebiges, in der Zukunft liegendes Ablaufdatum und eine beliebige fünfstellige Postleitzahl. Elements validiert Nutzereingaben bereits bei der Eingabe. Um Ihre Kundinnen und Kunden bei der Fehlererkennung zu unterstützen, überprüfen Sie das `card`-Element auf `Änderungs`-Ereignisse und zeigen Sie alle Fehler an: ```javascript card.on('change', function (event) { displayError(event); }); function displayError(event) { changeLoadingStatePrices(false); let displayError = document.getElementById('card-element-errors'); if (event.error) { displayError.textContent = event.error.message; } else { displayError.textContent = ''; } } ``` Die [Postleitzahlprüfung](https://docs.stripe.com/js.md#postal-code-formatting) hängt vom Abrechnungsland Ihrer Kundin/Ihres Kunden ab. Nutzen Sie unsere [internationalen Testkarten](https://docs.stripe.com/testing.md#international-cards), um andere Postleitzahlformate zu testen. ### Zahlung abschließen Wenn Ihre Kund/innen das Elements-Formular übermittelt, rufen Sie `stripe.confirmCardPayment` mit dem *Client-Geheimnis* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) auf, das Sie an Ihr Frontend übergeben haben. Dadurch wird eine Zahlungsmethode erstellt und der PaymentIntent der Rechnung, aufgrund dessen eine Zahlung ausgeführt werden soll, *wird bestätigt* (Confirming an intent indicates that the customer intends to use the current or provided payment method. Upon confirmation, the intent attempts to initiate the portions of the flow that have real-world side effects). Wenn die *starke Kundenauthentifizierung* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase) (SCA) für die Zahlung erforderlich ist, führt Elements den Authentifizierungsvorgang durch, bevor der PaymentIntent bestätigt wird. ```javascript const btn = document.querySelector('#submit-payment-btn'); btn.addEventListener('click', async (e) => { e.preventDefault(); const nameInput = document.getElementById('name'); // Create payment method and confirm PaymentIntent. stripe.confirmCardPayment(clientSecret, { payment_method: { card: cardElement, billing_details: { name: nameInput.value, }, } }).then((result) => { if(result.error) { alert(result.error.message); } else { // Successful invoice payment } }); }); ``` ## Ereignisse nach Zahlung verarbeiten Stripe sendet ein Ereignis des Typs [invoice.paid](https://docs.stripe.com/api/events/types.md?event_types-invoice.paid), wenn eine Rechnungszahlung abgeschlossen wird. Überwachen Sie dieses Ereignis, um eine zuverlässige Ausführung zu gewährleisten. Wenn sich Ihre Integration nur auf einen clientseitigen Callback stützt, könnte es bei Kundinnen/Kunden zu einer Unterbrechung der Verbindung kommen, bevor der Callback ausgeführt wird. Dies würde dazu führen, dass das Kundenkonto belastet wird, ohne dass Ihr Server benachrichtigt wird. Wenn Sie Ihre Integration so einrichten, dass sie asynchrone Ereignisse überwacht, können Sie auch [verschiedene Arten von Zahlungsmethoden](https://stripe.com/payments/payment-methods-guide) mit einer einzigen Integration akzeptieren. Erfolgreiche Rechnungszahlungen lösen das Ereignis [invoice.paid](https://docs.stripe.com/api/events/types.md?event_types-invoice.paid) und das Ereignis [invoice.payment_succeeded](https://docs.stripe.com/api/events/types.md?event_types-invoice.payment_succeeded) aus. Beide Ereignistypen enthalten die gleichen Rechnungsdaten. Es muss daher nur eines der Ereignisse überwacht werden, um über erfolgreiche Rechnungszahlungen informiert zu werden. Der Unterschied besteht darin, dass das Ereignis `invoice.payment_succeeded` für erfolgreiche Rechnungszahlungen gesendet wird, nicht jedoch, wenn Sie eine Rechnung als [paid_out_of_band](https://docs.stripe.com/api/invoices/pay.md#pay_invoice-paid_out_of_band) markieren. Ereignisse des Typs `invoice.paid` hingegen werden sowohl bei erfolgreichen Zahlungen als auch bei Out-of-Band-Zahlungen ausgelöst. Da `invoice.paid` beide Szenarien abdeckt, empfehlen wir in der Regel das Ereignis `invoice.paid` zu überwachen und nicht `invoice.payment_succeeded`. Verwenden Sie das [Webhook-Tool im Dashboard](https://dashboard.stripe.com/webhooks) oder folgen Sie dem [QuickStart für Webhooks](https://docs.stripe.com/webhooks/quickstart.md), um diese Ereignisse zu empfangen und Aktionen auszuführen. Dazu zählen beispielsweise der Versand von Bestellbestätigungen per E-Mail, das Protokollieren des Verkaufs in der Datenbank und die Einführung eines Versand-Workflows. Neben der Abwicklung des Ereignisses `invoice.paid` empfehlen wir die Abwicklung von zwei weiteren Ereignissen, wenn Sie Zahlungen mit dem Payment Element erfassen: | Ereignis | Beschreibung | Aktion | | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing) | Wird gesendet, wenn eine/e Kund/in eine Zahlung erfolgreich veranlasst hat, die Zahlung aber noch nicht abgeschlossen ist. Dieses Ereignis wird am häufigsten gesendet, wenn eine Bankabbuchung veranlasst wurde. In Zukunft folgt darauf das Ereignis `invoice.paid` oder `invoice.payment_failed`. | Senden Sie eine Bestellbestätigung an die Kund/innen, in der angegeben ist, dass die Zahlung noch aussteht. Bei digitalen Waren können Sie die Bestellung abwickeln, bevor Sie darauf warten, dass die Zahlung erfolgt. | | [invoice.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Wird gesendet, wenn Kund/innen versuchen, eine Zahlung für eine Rechnung durchzuführen, die Zahlung aber fehlgeschlagen ist. | Wenn eine Zahlung von `processing` zu `payment_failed` übergegangen ist, bieten Sie den Kund/innen einen weiteren Zahlungsversuch an. | ## Optional: Eine Rechnung anpassen Es gibt mehrere Möglichkeiten zur [Anpassung von Rechnungen](https://docs.stripe.com/invoicing/customize.md). Die Anpassungsoptionen von Stripe ermöglichen es Ihnen, Ihr eigenes Branding zu verwenden und Ihre Rechnungen an die Bestimmungen in den Ländern, in denen Sie tätig sind, anzupassen. ### Nutzerdefinierte Felder Fügen Sie benutzerdefinierte Felder hinzu, um Ihre Rechnungs-PDF-Dokumente zu verbessern und die Einhaltung Ihrer Geschäftspraktiken und steuerlichen Berichtspflichten zu unterstützen. Mit nutzerdefinierten Feldern können Sie bis zu vier Schlüssel-Wert-Paare angeben, die in der Rechnungskopfzeile angezeigt werden. Sie können bis zu vier Schlüssel-Wert-Paare für nutzerdefinierte Felder im [Rechnungs-Editor](https://dashboard.stripe.com/invoices/create), über die [Invoices API](https://docs.stripe.com/api/invoices/create.md#create_invoice-custom_fields) oder mit [Rechnungsvorlagen](https://docs.stripe.com/invoicing/invoice-rendering-template.md) festlegen. Gängige Beispiele für die Verwendung von nutzerdefinierten Feldern sind unter anderem: - Bestellnummern - Auftragnehmernummern - Steuerkonformität Nachfolgend finden Sie ein Beispiel für das Erstellen einer Rechnung mit einer Bestellnummer und einer Mehrwertsteuer (VAT) als benutzerdefinierte Felder: ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d "custom_fields[0][name]"="PO number" \ -d "custom_fields[0][value]"=12345 \ -d "custom_fields[1][name]"=VAT \ -d "custom_fields[1][value]"=123ABC ``` #### Nutzerdefinierte Felder übernehmen Sie können nutzerdefinierte Rechnungsfelder für das [Customer](https://docs.stripe.com/api/customers/object.md#customer_object-invoice_settings-custom_fields)-Objekt festlegen. Alle nutzerdefinierten Felder, die Sie auf Kundenebene festlegen, gelten für alle Rechnungsentwürfe, die Sie für diesen Kunden/diese Kundin erstellen. Sie können diese übernommenen nutzerdefinierten Felder jederzeit ändern, während die Rechnung noch ein Entwurf ist. Nachdem die Rechnung abgeschlossen wurde, können Sie die nutzerdefinierten Felder nicht mehr aktualisieren. Nachfolgend finden Sie ein Beispiel für das Hinzufügen von nutzerdefinierten Feldern auf Kundenebene, die für alle zukünftig generierten Rechnungsentwürfe gelten: ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode email="jenny.rosen@example.com" \ -d payment_method=pm_card_visa \ -d "invoice_settings[default_payment_method]"=pm_card_visa \ -d "invoice_settings[custom_fields][0][name]"="PO number" \ -d "invoice_settings[custom_fields][0][value]"=12345 \ -d "invoice_settings[custom_fields][1][name]"=VAT \ -d "invoice_settings[custom_fields][1][value]"=123ABC ``` ## See also - [Nach der Finalisierung](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#post-finalized) - [Verwenden Sie eingehende Webhooks, um Updates in Echtzeit zu erhalten](https://docs.stripe.com/webhooks.md)