Integration mit der Invoicing API

Erfahren Sie, wie Sie mithilfe von Code eine Rechnung erstellen und senden.

Am häufigsten werden Rechnungen über das Dashboard 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.

Notiz

Sie müssen keine Integration mit der Payments API vornehmen, um eine Integration mit der Invoicing API vorzunehmen.

Stripe einrichten

Nutzen Sie unsere offiziellen Bibliotheken für den Zugriff auf die Stripe-API:

Produkt erstellen

Geben Sie den Namen eines Produkts ein, um es zu erstellen:

Preis erstellen

Anhand von Preisen 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).

Notiz

Wenn Sie keinen Preis für Ihr Produkt erstellen müssen, können Sie alternativ den Parameter 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:

Kundin/Kunde erstellen

Das Customer-Objekt stellt den Kunden/die Kundin, der/die Ihr Produkt kauft, und ist für die Erstellung einer Rechnung erforderlich. Um einen Kunden/eine Kundin mit name, email und description zu erstellen, fügen Sie den folgenden Code hinzu und ersetzen Sie die Werte durch Ihre eigenen:

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.

Notiz

Zusätzliche Parameter finden Sie unter Kundin/Kunden erstellen.

Rechnung erstellen

Legen Sie das Attribut collection_method auf send_invoice fest. Damit Stripe eine Rechnung als überfällig kennzeichnet, müssen Sie den Parameter days_until_due hinzufügen. Wenn Sie eine Rechnung senden, sendet Stripe die Rechnung per E-Mail mit Zahlungsanweisungen an den Kunden/die Kundin.

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.

Wenn Sie auto_advance auf false festlegen, können Sie die Rechnung bis zu ihrer Finalisierung 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 API verwenden:

Notiz

Wenn Sie die Rechnung versehentlich erstellt haben, stornieren Sie sie. Sie können eine Rechnung auch als uneinbringlich kennzeichnen.

Rechnungszahlung akzeptieren

Wenn die Rechnung finalisiert ist, wird ein PaymentIntent erzeugt und mit der Rechnung verknüpft. Verwenden Sie Stripe Elements, um Zahlungsdetails zu erfassen und den PaymentIntent der Rechnung zu bestätigen.

Notiz

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-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.

Das Payment Element erfasst sicher alle notwendigen Zahlungsdaten für eine Vielzahl von Zahlungsmethoden. Unter Zahlungsmethoden und Produktsupport 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 des PaymentIntent, um den Zahlungsvorgang sicher abzuschließen. Rufen Sie das Client-Geheimnis der Rechnung ab, indem Sie das Attribut confirmation_secret erweitern, wenn Sie die Rechnung finalisieren oder wenn Sie einen weiteren API-Aufruf, z. B. Abrufen oder Aktualisieren 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.

Nachdem die Rechnung zurückgegeben wurde, greifen Sie über das erweiterte Feld confirmation_secret auf das Client-Geheimnis zu.

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.

pay-invoice.html
<head>
  <title>Pay Invoice</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Erstellen Sie auf Ihrer Bezahlseite eine Instanz von Stripe mit dem folgenden JavaScript:

pay-invoice.js
// 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('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

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.

pay-invoice.html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Pay</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

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.

pay-invoice.js
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 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 (SCA) erforderlich ist, führt das Payment Element das Authentifizierungsverfahren durch, bevor der Payment Intent bestätigt wird.

Stellen Sie eine 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.

pay-invoice.js
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 des `PaymentIntent`-Objekts. Bei Abonnementintegrationen wird dieses client_secret auch über `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.

Vorsicht

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, 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.

status.js
// Initialize Stripe.js using your publishable key
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

// 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;
  }
});

Ereignisse nach Zahlung verarbeiten

Stripe sendet ein Ereignis des Typs 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 mit einer einzigen Integration akzeptieren.

Notiz

Erfolgreiche Rechnungszahlungen lösen das Ereignis invoice.paid und das Ereignis 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 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 oder folgen Sie dem QuickStart für Webhooks, 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	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	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.

Integration mit der Invoicing API

Erfahren Sie, wie Sie mithilfe von Code eine Rechnung erstellen und senden.

Notiz

Stripe einrichten

Produkt erstellen

Preis erstellen

Notiz

Kundin/Kunde erstellen

Notiz

Rechnung erstellen

Notiz

Rechnungszahlung akzeptieren

Notiz

Das Client-Geheimnis an das Frontend übergeben

Stripe Elements

Payment Element zu Ihrer Seite hinzufügen

Zahlung abschließen

Vorsicht

Ereignisse nach Zahlung verarbeiten

Notiz

OptionalEine Rechnung anpassen

Siehe auch