Eine Zahlung mehrmals erfassen

Erfassen Sie einen PaymentIntent mehrmals bis zum autorisierten Betrag.

Mit Multicapture können Sie eine PaymentIntent, die während des Bestätigungsschritts einer CheckoutSession erstellt wurde, mehrmals für eine einzelne Transaktion erfassen, bis zum vollständigen Betrag des PaymentIntent. Sie können ihn verwenden, wenn Sie Bestellungen mit mehreren Lieferungen haben und Gelder erfassen möchten, während Sie Teile der Bestellung abwickeln.

IC+-Funktion

Multicapture ist Teil der Funktionalität, von dem unsere Nutzer/innen beim Preismodell IC+ profitieren. Wenn Sie ein gemischtes Stripe-Preismodell anbieten und auf diese Funktion zugreifen möchten, wenden Sie sich an den Stripe Support.

Verfügbarkeit

Beachten Sie bei der Verwendung von Multicapture folgende Einschränkungen:

Es werden nur Online-Kartenzahlungen unterstützt
Verfügbar mit Amex, Visa, Discover, Mastercard, Cartes Bancaires, Diners Club, China UnionPay (CUP) und Japan Credit Bureau (JCB).
Geldbewegungen für separate Zahlungen und Überweisungen, die source_transaction verwenden, werden nicht unterstützt
Mit Stripe können Sie bis zu 50 Erfassungen für einen einzelnen PaymentIntent durchführen
Modus ist auf payment und capture_method in der CheckoutSession ist auf manual gesetzt.

CUP- und JCB-Unterstützung

CUP-Mehrfacherfassung ist nur in den USA verfügbar. JCB-Mehrfacherfassung ist nur in den USA, in Kanada, Australien und Neuseeland verfügbar.

Best Practices

Wenn Sie getrennte Sendungen für eine Bestellung versenden, benachrichtigen Sie Ihre Endkundinnen und -kunden proaktiv über die Details jeder Lieferung. Auf diese Weise werden Anfragen und Rückbuchungen von Kundinnen/Kunden vermieden, da sie verwirrt sind, weil sie mehrere Transaktionen auf ihren Kontoauszügen sehen. Verwenden Sie die folgenden Best Practices bei der Benachrichtigung von Kundinnen und Kunden:

Informieren Sie sie zum Zeitpunkt des Bezahlvorgangs vor dem Kauf über das geschätzte Lieferdatum und den Transaktionsbetrag für jede Lieferung.
Benachrichtigen Sie sie bei jeder Lieferung, zusammen mit dem Transaktionsbetrag.
Geben Sie Ihre vollständigen Rückerstattungs- und Stornorichtlinien an.

Sie können das Feld custom_text verwenden, wenn Sie eine neue CheckoutSession erstellen, um zusätzlichen Text auf der Bezahlseite anzuzeigen, um die Compliance-Anforderungen zu erfüllen.

Compliance

Sie sind bei Verwendung von Mehrfacherfassung für die Einhaltung aller geltenden Gesetze, Vorschriften und Netzwerkregeln verantwortlich. Informieren Sie sich über die Regeln der Kartennetze, mit denen Sie diese Funktion nutzen möchten, um sicherzustellen, dass Ihre Verkäufe allen geltenden Regeln entsprechen, die je nach Netzwerk unterschiedlich sind. Beispielsweise beschränken die meisten Kartennetzwerke die Nutzung von Mehrfacherfassung auf Transaktionen ohne Karte für den Verkauf von Waren, die separat versendet werden. Bestimmte Kartennetzwerke erlauben die Mehrfacherfassung für Unternehmen, basierend auf ihrer Branche (zum Beispiel Reisen), während andere die Mehrfacherfassung nicht für Ratenzahlungs- oder Einzahlungs-Workflows zulassen.

Die auf dieser Seite bereitgestellten Informationen im Zusammenhang mit der Einhaltung dieser Anforderungen dienen Ihrer allgemeinen Orientierung und stellen keine rechtliche, steuerliche, buchhalterische oder sonstige fachliche Beratung dar. Wenden Sie sich an eine Fachperson, wenn Sie sich bezüglich Ihrer Verpflichtungen unsicher sind.

Checkout-Sitzung erstellen

Erstellen Sie von Ihrem Server aus eine Checkout-Sitzung und setzen Sie den ui_mode-Endpoint auf embedded. Sie können die Checkout-Sitzung mit den aufzunehmenden Posten und Optionen wie Währung konfigurieren.

Um Kundinnen/Kunden zu einer nutzerdefinierten Seite zurückzuleiten, die Sie auf Ihrer Website hosten, geben Sie die URL dieser Seite im Parameter return_url an. Fügen Sie die Vorlagenvariable {CHECKOUT_SESSION_ID} in die URL ein, um den Status der Sitzung auf der Rückgabeseite abzurufen. Checkout ersetzt die Variable vor der Weiterleitung automatisch durch die Checkout-Sitzungs-ID.

Erfahren Sie mehr über das Konfigurieren der Rückgabeseite und andere Optionen zum Anpassen des Weiterleitungsverhaltens.

Nachdem Sie die Checkout-Sitzung erstellt haben, verwenden Sie das client_secret, das in der Antwort auf Checkout verbinden zurückgegeben wurde.

Um die Funktion zur Mehrfacherfassung zu aktivieren, setzen Sie request_multicapture auf if_available.

Zahlungsmethoden

Standardmäßig aktiviert Stripe Karten und andere gängige Zahlungsmethoden. Sie können einzelne Zahlungsmethoden im Stripe Dashboard aktivieren oder deaktivieren. In Checkout wertet Stripe die Währung und etwaige Einschränkungen aus und zeigt den Kundinnen/Kunden dann dynamisch die unterstützten Zahlungsmethoden an.

Um zu sehen, wie Ihre Zahlungsmethoden Kundinnen und Kunden angezeigt werden, geben Sie eine Transaktions-ID ein oder legen Sie einen Bestellbetrag und eine Währung im Dashboard fest.

Sie können Apple Pay und Google Pay in Ihren Einstellungen für Zahlungsmethoden aktivieren. Standardmäßig ist Apple Pay aktiviert und Google Pay deaktiviert. In einigen Fällen filtert Stripe die Optionen jedoch heraus, auch wenn sie aktiviert sind. Wir filtern Google Pay, wenn Sie automatische Steuern aktivieren, ohne eine Versandadresse zu erfassen.

Die von Stripe gehosteten Checkout-Seiten benötigen keine Integrationsänderungen, um Apple Pay oder Google Pay zu aktivieren. Stripe verarbeitet diese Zahlungen genauso wie andere Kartenzahlungen.

Checkout verbinden

Checkout ist als Teil von Stripe.js verfügbar. Nehmen Sie das Stripe.js-Skript in Ihre Seite auf, indem Sie es zum Header Ihrer HTML-Datei hinzufügen. Als Nächstes erstellen Sie einen leeren DOM-Knoten (Container), der zum Verbinden verwendet wird.

index.html
<head>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>

Initialisieren Sie Stripe.js mit Ihrem veröffentlichbaren API-Schlüssel.

Erstellen Sie eine asynchrone fetchClientSecret-Funktion, die eine Anfrage an Ihren Server stellt, um eine Checkout-Sitzung zu erstellen und das Client-Geheimnis abzurufen. Übergeben Sie diese Funktion an options, wenn Sie die Checkout-Instanz erstellen:

index.js
// Initialize Stripe.js
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

initialize();

// Fetch Checkout Session and retrieve the client secret
async function initialize() {
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Initialize Checkout
  const checkout = await stripe.initEmbeddedCheckout({
    fetchClientSecret,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}

Checkout wird in einem iFrame gerendert, der Zahlungsdaten sicher über eine HTTPS-Verbindung an Stripe sendet.

Häufiger Fehler

Vermeiden Sie es, Checkout in einem anderen iFrame zu platzieren, da bei einigen Zahlungsmethoden die Weiterleitung an eine andere Seite zur Zahlungsbestätigung erforderlich ist.

Erscheinungsbild anpassen

Passen Sie Checkout an das Design Ihrer Website an, indem Sie Hintergrundfarbe, Schaltflächenfarbe, Rahmenradius und Schriftarten in den Branding-Einstellungen Ihres Kontos festlegen.

Checkout wird standardmäßig ohne externes Padding oder Ränder gerendert. Um Ihren gewünschten Rand hinzuzufügen (z. B. 16px auf allen Seiten), empfehlen wir, ein Container-Element zu verwenden.

Eine Rückgabeseite anzeigen

Nachdem Ihre Kundinnen/Kunden einen Zahlungsversuch unternommen haben, leitet Stripe sie zu einer Rückgabeseite weiter, die Sie auf Ihrer Website hosten. Beim Erstellen der Checkout-Sitzung haben Sie die URL der Rückgabeseite im Parameter return_url angegeben. Erfahren Sie mehr über andere Optionen zum Anpassen des Weiterleitungsverhaltens.

Rufen Sie beim Rendern Ihrer Rückgabeseite den Status der Checkout-Sitzung mithilfe der Checkout-Sitzungs-ID in der URL ab. Verarbeiten Sie das Ergebnis entsprechend dem Sitzungsstatus wie folgt:

complete: Die Zahlung war erfolgreich. Verwenden Sie die Informationen aus der Checkout-Sitzung, um eine Bestätigungsseite zu rendern.
open: Die Zahlung ist fehlgeschlagen oder wurde storniert. Stellen Sie erneut eine Verbindung zu Checkout her, damit Ihre Kundinnen/Kunden es erneut versuchen können.

client.js
const session = await fetch(`/session_status?session_id=${session_id}`)
if (session.status == 'open') {
  // Remount embedded Checkout
} else if (session.status == 'complete') {
  // Show success page
  // Optionally use session.payment_status or session.customer_email
  // to customize the success page
}

Auf Weiterleitung basierende Zahlungsmethoden

Während der Zahlung leiten einige Zahlungsmethoden die Kundin/den Kunden auf eine Zwischenseite weiter, zum Beispiel eine Bankautorisierungsseite. Wenn sie diese Seite ausgefüllt haben, leitet Stripe sie zu Ihrer Rückgabeseite weiter.

Erfahren Sie mehr über auf Weiterleitung basierende Zahlungsmethoden und das Weiterleitungsverhalten.

PaymentIntent erfassen

Bei einem PaymentIntent im Status requires_capture, in dem die Mehrfacherfassung available ist, wird Stripe durch Angabe des optionalen Parameters final_capture auf false angewiesen, die verbleibenden, nicht erfassten Gelder freizugeben, wenn die Erfassungs-API aufgerufen wird. Wenn Sie beispielsweise einen Payment Intent in Höhe von 10 USD bestätigen, bleiben bei der Erfassung von 7 USD mit final_capture=false die verbleibenden 3 USD autorisiert.

In der PI-Erfassungsantwort werden die Felder amount_capturable und amount_received entsprechend aktualisiert.

// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 300, // 1000 - 700 = 300
  "amount_received": 700,
  // if latest_charge is expanded
  "latest_charge": {
      "id": "ch_xxx",
      "object": "charge",
      "amount": 1000,
      "amount_captured": 700,
      "amount_refunded": 0,
      ...
    }
  ...
}

Endgültige Erfassung

Der PaymentIntent verbleibt im Status requires_capture, bis Sie eine der folgenden Maßnahmen ergreifen:

Setzen Sie final_capture auf true
Erfassung ohne den Parameter final_capture (da final_capture standardmäßig auf true eingestellt ist)
Das Autorisierungsfenster läuft ab.

An dieser Stelle gibt Stripe alle verbleibenden Gelder frei, und der PaymentIntent wechselt in den Status succeeded.

In der PI-Erfassungsantwort werden die Felder amount_capturable und amount_received entsprechend aktualisiert.

// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 0, // not 100 due to final_capture=true
  "amount_received": 900, // 700 + 200 = 900
  // if latest_charge is expanded
  "latest_charge": {
      "id": "ch_xxx",
      "object": "charge",
      "amount": 1000,
      "amount_captured": 900,
      "amount_refunded": 0,
      ...
    }
  ...
}

Nicht erfasste PaymentIntents gehen in den Status canceled über, während teilweise erfasste PaymentIntents in den Status succeeded wechseln.

OptionalNicht erfasste Gelder freigeben

Ihre Integration testen

Verwenden Sie eine Stripe-Testkarte mit einer beliebigen CVC/Prüfzimmer und Postleitzahl und einem beliebigen zukünftigen Ablaufdatum, um Multicapture-Zahlungen zu testen.

Die Nummer	Zahlungsmethode	Beschreibung
	`pm_card_visa`	Diese Testkarte unterstützt die Mehrfacherfassung.
	`pm_card_visa_cartesBancaires`	Cartes Bancaires- oder Visa-Testkarte, die die Mehrfacherfassung unterstützt.

Rückerstattungen

Bei einem PaymentIntent mit dem Status requires_capture können Sie beliebig oft Rückerstattungen bis zum gesamten erfassten Betrag abzüglich des gesamten rückerstatteten Betrags durchfühen. Dies ist der amount_received – amount_refunded. Das Feld charge.refunded wechselt erst auf true, wenn die endgültige Erfassung durchgeführt wurde und die gesamte amount_received rückerstattet wird.

Stripe unterstützt keine Teilrückerstattungen mit refund_application_fee=true oder reverse_transfer=true. Stattdessen können Sie Teilgebührenrückerstattungen durchführen, indem Sie manuell Teilgebührenerstattungen und Transferrückbuchungen mit den Endpoints Rückerstattung von Plattformgebühren und Rückbuchung des Transfers durchführen. Nach Verwendung der Endpoints für die Rückerstattung der Plattformgebühr oder das Übertragungsstorno unterstützt Stripe keine weiteren Rückerstattungen mit refund_application_fee=true or reverse_transfer=true.

Connect

Multicapture unterstützt alle Use cases von Connect mit Ausnahme von Separate Zahlungen und Überweisungen mit dem Parameter source_transaction. Die Parameter application_fee_amount und transfer_data[amount] haben einige zusätzliche Validierungen. Beachten Sie die folgenden Validierungen bei der Implementierung von Multicapture mit Connect:

Die Festlegung von application_fee_amount oder transfer_data[amount] bei der ersten Erfassung macht sie für alle nachfolgenden Erfassungen erforderlich. Jede Übergabe von application_fee_amount und transfer_data[amount] zum Zeitpunkt der Erfassung setzt die bei der Erstellung, Bestätigung und Aktualisierungen des PaymentIntent übergebenen Werte außer Kraft.
Stripe unterstützt keine Teilrückerstattungen für Multicapture-Zahlungen mit refund_application_fee=true oder reverse_transfer=true. Sie können Teilgebührenrückerstattungen oder Transferrückbuchungen mit den Endpoints Rückerstattung von Plattformgebühren und Rückbuchung des Transfers durchführen.

Webhooks

Aktualisierte Webhooks belasten

Wir senden jedes Mal, wenn Sie eine Zahlung erfassen, einen charge.updated-Webhook.

Beispiel: Bei der ersten Erfassung einer Multicapture-Zahlung vom Typ Destination Charge mit einem application_fee_amount aktualisieren wir diese Felder von leeren auf nicht leere Werte.

// charge.updated
{
  "data": {
    "id": "ch_xxx",
    "object": "charge",
    "amount": 1000,
    "balance_transaction": "txn_xxx", // applicable to all charges
    "transfer": "tr_xxx",             // applicable to destination charges only
    "application_fee": "fee_xxx",     // applicable to Connect only
    ...
  },
  "previous_attributes": {
    "balance_transaction": null, // applicable to all charges
    "transfer": null,            // applicable to destination charges only
    "application_fee": null,     // applicable to Connect only
  }
}

payment_intent.amount_capturable_updated

Wir übermitteln payment_intent.amount_capturable_updated bei jeder Erfassung, unabhängig von den Werten amount_to_capture und final_capture.

Wenn wir beispielsweise 1 USD von einem PaymentIntent mit einem Betrag von 10 USD erfassen, wird das Feld amount_capturable des PaymentIntent auf 9 USD aktualisiert.

// payment_intent.amount_capturable_updated
{
  "data": {
    "id": "pi_xxx",
    "object": "payment_intent",
    "amount": 1000,
    "amount_capturable": 900 // 1000 - 100 = 900
     ...
  },
  "previous_attributes": {
    "amount_capturable": 1000
  }
}

Zahlungserfassungsereignisse

Wir senden ein charge.captured-Ereignis für die endgültige Erfassung oder am Ende des Autorisierungsfensters, um die Autorisierung des nicht erfassten Betrags rückgängig zu machen. Das Feld captured für eine Zahlung wird erst nach einer endgültigen Erfassung oder einem Autorisierungsstorno true.

Wenn wir beispielsweise eine Erfassung mit amount=0 und final_capture=true durchführen, ändert sich das Attribut captured der Zahlung von false in true.

// charge.captured
{
  "data": {
    "id": "ch_xxx",
    "object": "charge",
    "captured": true
        ...
  },
  "previous_attributes": {
    "captured": false
  }
}

Rückerstattungs-Webhooks

Multicapture-Webhooks für die Rückerstattung unterscheiden sich nicht von Webhooks ohne Multicapture.

Bei jeder Teilrückerstattung senden wir ein refund.created-Ereignis. Bei verbundenen Konten senden wir auch application_fee.refunded-Ereignisse, wenn wir Plattformgebühren erstatten, und transfer.reversed-Ereignisse, wenn wir Transfers zurückbuchen.