Boleto-Zahlungen
So akzeptieren Sie Zahlungen per Boleto, einer gängigen Zahlungsmethode in Brasilien.
Stripe-Nutzer/innen in Brasilien können Boleto-Zahlungen in Brasilien mit der Payment Intents API und der Payment Methods API von Kund/innen annehmen. Kund/innen zahlen mit einem Boleto-Gutschein mit einer generierten Nummer an Geldautomaten, bei Banken, Bankportalen oder autorisierten Agenturen.
Stripe einrichtenServerseitig
Zunächst benötigen Sie ein Stripe-Konto. Jetzt registrieren.
Nutzen Sie unsere offiziellen Bibliotheken für den Zugriff auf die Stripe-API aus Ihrer Anwendung heraus:
PaymentIntent erstellenServerseitig
Stripe verwendet ein PaymentIntent-Objekt, um Ihre Absicht darzustellen, Zahlungen von Kundinnen/Kunden einzuziehen und Statusänderungen von der Erstellung des Boleto-Gutscheins bis zum Zahlungsabschluss zu verfolgen.
Erstellen Sie einen PaymentIntent auf Ihrem Server mit einem Betrag und der Währung brl (Boleto unterstützt keine anderen Währungen). Wenn Sie bereits eine Integration mit dem Payment Intents API haben, fügen Sie boleto zur Liste der Zahlungsmethoden für Ihren PaymentIntent hinzu.
Im zurückgegebenen PaymentIntent ist ein Client-Geheimnis enthalten, das Sie verwenden müssen, um den Zahlungsvorgang sicher abzuschließen. Senden Sie das Client-Geheimnis zurück an den Client, sodass Sie es in späteren Schritten verwenden können.
Zusätzliche Optionen für Zahlungsmethoden
Sie können für Ihre PaymentIntent den optionalen Parameter expires_ in den Optionen für Zahlungsmethoden nutzen, um die Gültigkeit eines Boleto-Gutscheins in Kalendertagen anzugeben. Wenn Sie beispielsweise einen Boleto-Gutschein am Montag erstellen und expires_ auf 2 setzen, läuft der Boleto-Gutschein am Mittwoch um 23:59 Uhr amerikanischer/brasilianischer Zeit (UTC-3) ab. Wenn Sie ihn auf 0 setzen, verfällt der Boleto-Gutschein am Ende des Tages. Der Parameter expires_ kann Werte zwischen 0 und 60 Tagen aufweisen. Der Standardwert ist 3 Tage. Sie können die standardmäßigen Ablauftage für Ihr Konto in den Einstellungen für Zahlungsmethoden anpassen.
Angaben zur Zahlungsmethode erfassenClientseitig
Erstellen Sie ein Zahlungsformular auf Ihrem Client, um die erforderlichen Rechnungsdaten von den Kund/innen zu erfassen:
| Feld | Wert |
|---|---|
name | Der vollständige Name des/der Kund/in. |
email | Die E-Mail-Adresse des/der Kund/in. |
tax_ | Die CPF (für Einzelpersonen) oder CNPJ (für Unternehmen) des/der Kund/in. Die CPF muss 11 Ziffern in einem der folgenden Formate enthalten: 000. oder 00000000000. Die CNPJ muss 14 Ziffern in einem der folgenden Formate enthalten: 00. oder 00000000000000. |
address | Straße und Hausnummer der Adresse des/der Kund/in. |
city | Ort der Adresse des/der Kund/in. |
state | Der aus zwei Buchstaben bestehende Code des brasilianischen Bundesstaats (ISO_3166-2:BR) der Adresse des/der Kund/in. |
postal_ | Die Postleitzahl der Adresse des/der Kund/in. Die Postleitzahl muss eines der folgenden Formate aufweisen: XXXXX-XXX or XXXXXXXX. |
Notiz
Die Felder name, address, city müssen mindestens ein alphanumerisches Zeichen aus dem Basic-Latin-(ASCII)-Unicode-Block enthalten.
<form id="payment-form"> <div class="form-row"> <label for="name"> Name </label> <input id="name" name="name" required> </div> <div class="form-row"> <label for="tax_id"> CPF/CNPJ </label> <input id="tax_id" name="tax_id" required> </div> <div class="form-row"> <label for="email"> Email </label> <input id="email" name="email" required> </div> <div class="form-row"> <label for="address"> Address </label> <input id="address" name="address" required> </div> <div class="form-row"> <label for="city"> City </label> <input id="city" name="city" required> </div> <div class="form-row"> <label for="state"> State </label> <input id="state" name="state" required> </div> <div class="form-row"> <label for="postal_code"> Postal Code </label> <input id="postal_code" name="postal_code" required> </div> <!-- Used to display form errors. --> <div id="error-message" role="alert"></div> <button id="submit-button">Pay with Boleto</button> </form>
Zahlung an Stripe sendenClientseitig
Verwenden Sie Stripe.js zur Übermittlung von Zahlungen an Stripe, wenn Kundinnen/Kunden mit Boleto bezahlen möchten. Stripe.js ist unsere grundlegende JavaScript-Bibliothek für die Erstellung von Zahlungsabläufen.
Binden Sie das Stripe.js-Skript in Ihre Zahlungsseite ein, indem Sie es im head Ihrer HTML-Datei einfügen.
<head> <title>Checkout</title> <script src="https://js.stripe.com/basil/stripe.js"></script> </head>
Erstellen Sie auf Ihrer Zahlungsseite eine Instanz von Stripe.js mit dem folgenden JavaScript.
// Set your publishable key. Remember to switch to your live publishable key in production! // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe();'pk_test_TYooMQauvdEDq54NiTphI7jx'
Verwenden Sie stripe.confirmBoletoPayment und das Client-Geheimnis des PaymentIntent-Objekts, das Sie in Schritt 2 erstellt haben, um die Rechnungsdaten der Kundin/des Kunden zu übermitteln.
Nach der Bestätigung öffnet Stripe automatisch ein Modal, um den Boleto-Gutschein für Ihre/n Kund/in anzuzeigen.
var form = document.getElementById('payment-form'); form.addEventListener('submit', async (event) => { event.preventDefault(); const result = await stripe.confirmBoletoPayment( '{{PAYMENT_INTENT_CLIENT_SECRET}}', { payment_method: { boleto: { tax_id: document.getElementById('tax_id').value, }, billing_details: { name: document.getElementById('name').value, email: document.getElementById('email').value, address: { line1: document.getElementById('address').value, city: document.getElementById('city').value, state: document.getElementById('state').value, postal_code: document.getElementById('postal_code').value, country: 'BR', }, }, }, } ); // Stripe.js will open a modal to display the Boleto voucher to your customer // This async function finishes when the customer closes the modal if (result.error) { // Display error to your customer const errorMsg = document.getElementById('error-message'); errorMsg.innerText = result.error.message; } });
Notiz
Die Ausführung von stripe. kann einige Sekunden dauern. Während dieser Zeit sollten Sie Ihr Formular deaktivieren, damit keine erneute Absendung erfolgen kann. Lassen Sie stattdessen ein Wartesymbol einblenden, wie beispielsweise eine Sanduhr. Tritt ein Fehler auf, lassen Sie eine Fehlermeldung für den/die Kund/in anzeigen, aktivieren Sie das Formular erneut und blenden Sie das Wartesymbol aus.
Wenn die Erstellung des Boleto-Gutscheins erfolgreich war, lautet der Wert der zurückgegebenen Eigenschaft status des PaymentIntent requires_. Sie können den Status eines PaymentIntent im Dashboard oder in der Eigenschaft status des Objekts einsehen. War die Erstellung des Boleto-Gutscheins nicht erfolgreich, prüfen Sie den zurückgegebenen error, um den Grund zu erfahren (z. B. ein ungültiges E-Mail-Format).
Optional: Gutschein-Link per E-Mail an Kund/innen senden
Stripe sendet ein payment_intent.requires_action-Ereignis, wenn ein Boleto-Gutschein erfolgreich erstellt wurde. Wenn Sie Ihren Kund/innen den Link für den Gutschein per E-Mail senden müssen, können Sie die hosted_ in payment_intent.next_action.boleto_display_details ermitteln.
Optional: Gutschein anpassen
Auf der Seite mit den Branding-Einstellungen können Sie die Nutzeroberfläche für Ihre Kund/innen anpassen.
Folgende Branding-Einstellungen können auf den Gutschein angewendet werden:
- Symbol – Ihr Markenlogo und Ihr offizieller Firmenname
- Akzentfarbe: Farbe für die Schaltfläche „Nummer kopieren“
- Markenfarbe – Die Hintergrundfarbe
Handhabung von Ereignissen nach der ZahlungServerseitig
Boleto-Zahlungen sind asynchron, daher sind die Gelder nicht sofort verfügbar. Kund/innen bezahlen den Boleto-Gutschein eventuell nicht sofort nach dem Abschluss des Bestellvorgangs.
Für jeden bezahlten Boleto-Gutschein übermittelt Stripe am nächsten Werktag (Montag bis Freitag außer an brasilianischen Feiertagen) das Ereignis payment_intent.succeeded. Verwenden Sie das Dashboard oder einen nutzerdefinierten Webhook, um diese Ereignisse zu empfangen und Aktionen auszuführen (Versenden einer Bestellbestätigung per E-Mail an die Kundinnen/Kunden, Erfassen des Verkaufs in einer Datenbank oder Einleiten des Versandablaufs).
Wenn ein Boleto-Gutschein am Ablauftag nicht vor 23:59 Uhr amerikanischer Zeit/Zeit in Sao_Paulo (UTC-3) bezahlt wird, sendet Stripe nach einem Werktag das Ereignis payment_intent.payment_failed. Läuft ein Boleto-Gutschein beispielsweise am Donnerstag ab, wird das Ereignis am Freitag gesendet. Läuft ein Boleto-Gutschein am Freitag ab, wird das Ereignis am folgenden Montag gesendet.
| Ereignis | Beschreibung | Nächste Schritte |
|---|---|---|
payment_ | Der/die Kund/in hat vor Ablauf für den Boleto-Gutschein bezahlt. | Wickeln Sie die Bestellung der Waren oder Dienstleistungen ab, die der/die Kund/in gekauft hat. |
payment_ | Der/die Kund/in hat vor Ablauf nicht für den Boleto-Gutschein bezahlt. | Kontaktieren Sie Ihre/n Kund/in per E-Mail oder Push-Benachrichtigung und fordern Sie eine andere Zahlungsmethode an. |
Integration testen
Legen Sie in einer Sandbox payment_ auf die folgenden Werte fest, wenn Sie stripe.confirmBoletoPayment aufrufen, um verschiedene Szenarien zu testen.
| Beschreibung | |
|---|---|
| Simuliert einen Boleto-Gutschein, bei dem Kund/innen nach 3 Minuten bezahlen und der Webhook Beispiel: fulaninho@beispiel.com |
| Simuliert einen Boleto-Gutschein, bei dem Kund/innen sofort bezahlen und der Webhook Beispiel: succeed_immediately@beispiel.com |
| Simuliert einen Boleto-Gutschein, der abläuft, bevor Kund/innen bezahlen, und bei dem der Webhook Das Feld Beispiel: expire_immediately@beispiel.com |
| Simuliert einen Boleto-Gutschein, der abläuft, bevor Kund/innen zahlen, und bei dem der Webhook Das Feld Beispiel: expire_with_delay@beispiel.com |
| Simuliert einen Boleto-Gutschein, der nie erfolgreich ist. Er läuft entsprechend der Angabe im Feld Beispiel: fill_never@beispiel.com |
| Steueridentifikationsnummer | Beschreibung |
|---|---|
CPF CNPJ | Setzen Sie in einer Sandbox |
Ablauf und Stornierung
Boleto-Gutscheine gelten bis zum UNIX-Zeitstempel expires_, und Kundinnen/Kunden können einen Boleto-Gutschein nicht mehr bezahlen, wenn er abgelaufen ist. Boleto-Gutscheine können nicht vor Ablauf storniert werden.
Nachdem ein Boleto-Gutschein abgelaufen ist, ändert sich der Status des PaymentIntent in requires_. Zu diesem Zeitpunkt können Sie den PaymentIntent mit einer anderen Zahlungsmethode bestätigen oder stornieren.