Cash App Pay-Zahlungen

Fügen Sie Ihrer Integration Unterstützung für Cash App Pay hinzu.

Internet

Mobil

In diesem Leitfaden zeigen wir Ihnen, wie Sie mit dem Payment Element ein nutzerdefiniertes Zahlungsformular von Stripe in Ihre Website oder Anwendung einbetten. Mit dem Payment Element können Sie Zahlungsmethoden wie Cash App Pay automatisch annehmen. Informationen zu erweiterten Konfigurationen und Anpassungen finden Sie im Integrationsleitfaden Zahlungen annehmen.

Stripe einrichten
Serverseitig

Zunächst benötigen Sie ein Stripe-Konto. Registrieren Sie sich jetzt.

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

Erstellen Sie ein PaymentIntent
Serverseitig

Stripe verwendet ein PaymentIntent-Objekt, um Ihre Absicht darzustellen, eine Kundenzahlung einzuziehen. Dabei werden die Abbuchungsversuche und Zahlungsstatusänderungen während des gesamten Vorgangs dokumentiert.

Erstellen Sie einen PaymentIntent auf Ihrem Server mit einem Betrag und einer Währung. Sie können Zahlungsmethoden über das Dashboard verwalten. Stripe handhabt die Rückgabe der geeigneten Zahlungsmethoden anhand von Faktoren wie Transaktionsbetrag, Währung und Zahlungsablauf. Stellen Sie vor Erstellung des Payment Intent sicher, dass Cash App Pay in den Einstellungen für Zahlungsmethoden aktiviert ist.

Legen Sie den zu zahlenden Betrag immer serverseitig fest, also in einer vertrauenswürdigen Umgebung, und nicht auf Client-Seite. So wird verhindert, dass böswillige Kund/innen ihre eigenen Preise festlegen können.

Client-Geheimnis abrufen

Im PaymentIntent ist ein Client-Geheimnis enthalten, das auf dem Client verwendet wird, um Zahlungen sicher abzuschließen. Es gibt verschiedene Verfahren zum Übergeben des Client-Geheimnisses an den Client.

Rufen Sie das Client-Geheimnis von einem Endpoint auf Ihrem Server ab, indem Sie die Browser-Funktion fetch verwenden. Diese Vorgehensweise funktioniert am besten, wenn es sich bei Ihrer Client-Seite um eine einseitige Anwendung handelt, insbesondere wenn sie mit einem modernen Frontend-Framework wie React erstellt wurde. Erstellen Sie den Server-Endpoint, der das Client-Geheimnis bereitstellt:

Und dann rufen Sie das Client-Geheimnis mit JavaScript auf der Client-Seite ab:

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Zahlungsdetails erfassen
Clientseitig

Erfassen Sie Zahlungsdetails auf dem Client mit dem Payment Element. Das Payment Element ist eine vorgefertigte Komponente der Nutzeroberfläche, die die Erfassung von Zahlungsdaten für eine Vielzahl von Zahlungsmethoden vereinfacht.

Das Payment Element enthält einen iFrame, der Zahlungsinformationen über eine HTTPS-Verbindung sicher an Stripe sendet. Vermeiden Sie es, das Payment Element in einem anderen iFrame zu platzieren, da einige Zahlungsmethoden die Weiterleitung an eine andere Seite zur Zahlungsbestätigung verlangen.

Die Adresse der Bezahlseite muss mit https:// beginnen, nicht mit http://, damit Ihre Integration funktioniert. Sie können Ihre Integration ohne HTTPS testen. Denken Sie jedoch daran, dieses zu aktivieren, wenn Sie zur Annahme von Live-Zahlungen bereit sind.

Stripe.js einrichten

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 die PCI-Konformität zu gewährleisten. Fügen Sie das Skript nicht in ein Paket ein und hosten Sie selbst keine Kopie davon.

checkout.html
<head>
  <title>Checkout</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:

checkout.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 Ihrer Bezahlseite 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:

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

Wenn das vorherige Formular geladen wurde, erstellen Sie eine Instanz des Payment Element und verbinden es mit dem DOM-Knoten (Container). Übergeben Sie das Client-Geheimnis aus dem vorherigen Schritt an options, wenn Sie die Elements-Instanz erstellen:

Gehen Sie sorgfältig mit dem Client-Geheimnis um, denn es kann die Zahlung abschließen. Protokollieren Sie es nicht, betten Sie es nicht in URLs ein und geben Sie es nur dem/der Kund/in preis.

checkout.js
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous step
const elements = stripe.elements(options);
// Optional: Autofill user's saved payment methods. If the customer's
// email is known when the page is loaded, you can pass the email
// to the linkAuthenticationElement on mount:
//
//   linkAuthenticationElement.mount("#link-authentication-element",  {
//     defaultValues: {
//       email: 'jenny.rosen@example.com',
//     }
//   })

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

Zahlung an Stripe senden
Clientseitig

Verwenden Sie stripe.confirmPayment, um die Zahlung mit Details aus dem Payment Element vorzunehmen. Geben Sie für diese Funktion eine return_url an, um anzugeben, wohin Stripe die Nutzer/innen nach Durchführung der Zahlung weiterleiten soll. Ihre Nutzer/innen werden möglicherweise zunächst an eine zwischengeschaltete Seite weitergeleitet, wie z. B. eine Bankautorisierungsseite, bevor sie zur return_url weitergeleitet werden. Kartenzahlungen werden sofort zur return_url weitergeleitet, wenn eine Zahlung erfolgreich war.

checkout.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`.
  }
});

Achten Sie darauf, dass die return_url auf eine Seite Ihrer Website verweist, die den Status der Zahlung angibt. Wenn Stripe den/die Kund/in an die return_url weiterleitet, stellen wir die folgenden URL-Abfrageparameter bereit:

Parameter	Beschreibung
`payment_intent`	Die eindeutige ID für die `PaymentIntent`.
`payment_intent_client_secret`	Das Client-Geheimnis des `PaymentIntent`-Objekts.

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 einen der Abfrageparameter, um den PaymentIntent abzurufen. Überprüfen Sie den Status des PaymentIntent, 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;
  }
});

Transaktionen umleiten und authentifizieren

Kundinnen/Kunden können Transaktionen per Cash App Pay mit der mobilen App oder der Desktop-App authentifizieren. Der kundenseitig verwendete Client bestimmt die Authentifizierungsmethode, nachdem confirmPayment aufgerufen wurde.

Nachdem confirmPayment aufgerufen wurde, werden die Kundinnen/Kunden zu Cash App weitergeleitet, um die Zahlung zu genehmigen oder abzulehnen. Nachdem die Zahlung kundenseitig autorisiert wurde, werden diese zur return_url des Payment Intent weitergeleitet. Stripe fügt payment_intent, payment_intent_client_secret, redirect_pm_type und redirect_status als URL-Abfrageparameter hinzu (zusätzlich zu allen vorhandenen Abfrageparametern in return_url ).

Eine Authentifizierungssitzung läuft nach 60 Minuten ab, der Status des PaymentIntent wechselt dann wieder auf require_payment_method. Nach der Statusänderung sehen Kundinnen/Kunden einen Zahlungsfehler und müssen den Zahlungsvorgang von vorne beginnen.

OptionalSeparate Autorisierung und Erfassung

Sie können Autorisierung und Erfassung trennen, um eine Zahlung sofort zu erstellen, Gelder jedoch erst später zu erfassen. Stripe storniert den PaymentIntent und sendet das Ereignis payment_intent.canceled, wenn die Zahlung nicht innerhalb des 7-tägigen Zeitfensters erfasst wird.

Wenn Sie wissen, dass Sie die Zahlung nicht erfassen können, sollten Sie den PaymentIntent stornieren und nicht warten, bis das Zeitfenster von 7 Tagen abgelaufen ist.

Stripe anweisen, nur die Autorisierung durchzuführen

Um anzugeben, dass Sie Autorisierung und Erfassung trennen möchten, legen Sie capture_method beim Erstellen des PaymentIntent auf manual fest. Dieser Parameter weist Stripe an, nur den Betrag auf dem Cash App Pay-Konto der Kundin/des Kunden zu autorisieren.

Die Gelder erfassen

Nach erfolgreicher Autorisierung wechselt der Status des PaymentIntent zu requires_capture. Um die autorisierten Gelder zu erfassen, führen Sie eine Erfassungsanfrage für den PaymentIntent durch.

Der autorisierte Gesamtbetrag wird standardmäßig erfasst. Sie können auch amount_to_capture angeben. Dieser kann kleiner oder gleich der Summe sein.

Optional Autorisierung stornieren

Wenn Sie eine Autorisierung stornieren müssen, können Sie den PaymentIntent stornieren.

OptionalEreignisse nach der Zahlung verarbeiten

Stripe übermittelt ein payment_intent.succeeded-Ereignis, wenn die Zahlung abgeschlossen ist. Verwenden Sie im Dashboard einen Webhook oder eine Partnerlösung, um diese Ereignisse zu empfangen und Aktionen auszuführen (Versenden einer Bestellbestätigung per E-Mail an die Kund/innen, Erfassen des Verkaufs in einer Datenbank oder Einleiten des Versandablaufs).

Überwachen Sie diese Ereignisse, statt auf einen Callback vom Client zu warten. Auf dem Client könnte der Kunde/die Kundin das Browserfenster schließen oder die App beenden, bevor der Callback erfolgt ist und böswillige Clients könnten die Antwort manipulieren. Wenn Sie Ihre Integration so einrichten, dass asynchrone Ereignisse überwacht werden, hilft Ihnen dies auch dabei, in Zukunft mehr Zahlungsmethoden zu akzeptieren. Hier erhalten Sie Informationen zu den Unterschieden zwischen allen unterstützten Zahlungsmethoden.

Manuelles Bearbeiten von Ereignissen im Dashboard
Verwenden Sie das Dashboard, um Ihre Testzahlungen im Dashboard anzuzeigen, E-Mail-Belege zu senden, Auszahlungen zu bearbeiten oder fehlgeschlagene Zahlungen erneut zu versuchen.
Erstellen eines benutzerdefinierten Webhooks
Erstellen Sie einen benutzerdefinierten Webhook-Handler, um auf Ereignisse zu hören und eigene asynchrone Zahlungsabläufe zu implementieren. Testen und debuggen Sie Ihre Webhook-Integration lokal mit der Stripe CLI.
Integrieren einer vorgefertigten App
Bearbeiten Sie häufige Unternehmensereignisse, wie z. B.Automatisierung oderMarketing und Vertrieb, indem Sie eine Partneranwendung integrieren.

Integration testen

Um Ihre Integration zu testen, wählen Sie als Zahlungsmethode Cash App Pay aus und tippen Sie auf Bezahlen. Während des Tests werden Sie auf eine Testzahlungsseite weitergeleitet, auf der Sie die Zahlung genehmigen oder ablehnen können.

Wenn Sie im Live-Modus auf Bezahlen tippen, werden Sie zur mobilen Anwendung von Cash App weitergeleitet. In der Cash App haben Sie keine Möglichkeit, die Zahlung zu genehmigen oder abzulehnen. Die Zahlung wird nach abgeschlossener Weiterleitung automatisch genehmigt.

Fehlgeschlagene Zahlungen

Cash App Pay verwendet mehrere Datenpunkte, um zu entscheiden, wann eine Transaktion abgelehnt wird (zum Beispiel hat das KI-Modell ein hohes Verbraucherbetrugsrisiko für die Transaktion festgestellt oder der Verbraucher/die Verbraucherin hat die Zustimmung zur Abbuchung über die Cash App widerrufen).

In diesen Fällen wird die PaymentMethod getrennt und der Status des PaymentIntent-Objekts wechselt automatisch zu requires_payment_method.

Anders als bei einer abgelehnten Zahlung müssen Kundinnen/Kunden bei einem Cash App Pay-PaymentIntent mit dem Status requires_action die Zahlung innerhalb von 10 Minuten nach Weiterleitung zur Cash App-Website abschließen. Wenn nach 10 Minuten keine Aktion erfolgt ist, wird die Verbindung mit der PaymentMethod getrennt, und der Status des PaymentIntent-Objekts wechselt automatisch zu requires_payment_method.

In diesem Fall zeigt das Payment Element Fehlermeldungen an und fordert Ihre Kundinnen/Kunden auf, es mit einer anderen Zahlungsmethode erneut zu versuchen.

Fehlercodes

In der folgenden Tabelle finden Sie häufige Fehlercodes und die empfohlenen Maßnahmen:

Fehlercode	Empfohlene Maßnahme
`payment_intent_invalid_currency`	Geben Sie die korrekte Währung ein. Cash App Pay unterstützt nur `usd`.
`missing_required_parameter`	In der Fehlermeldung erhalten Sie weitere Informationen zum erforderlichen Parameter.
`payment_intent_payment_attempt_failed`	Dieser Code kann im Feld last_payment_error.code eines PaymentIntent angezeigt werden. Eine genauere Fehlerursache und Vorschläge zur Fehlerbehebung finden Sie in der Fehlermeldung.
`payment_intent_redirect_confirmation_without_return_url`	Geben Sie eine `return_url` an, wenn Sie einen PaymentIntent mit Cash App Pay bestätigen.