Weiter zum Inhalt
Konto erstellen oder anmelden
Das Logo der Stripe-Dokumentation
/
Konto erstellenAnmelden
ÜbersichtAktualisieren Sie Ihre Integration
Online-Zahlungen
ÜbersichtIhren Use case findenVerwenden Sie Managed Payments
Präsenzzahlungen
Zahlungsmethoden
Zahlungsszenarien
Mehr als Zahlungen

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 einrichten
Serverseitig

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:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

PaymentIntent erstellen
Serverseitig

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=brl \
  -d "payment_method_types[]"=boleto

Zusätzliche Optionen für Zahlungsmethoden

Sie können für Ihre PaymentIntent den optionalen Parameter expires_after_days 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_after_days 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_after_days 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 erfassen
Clientseitig

Erstellen Sie ein Zahlungsformular auf Ihrem Client, um die erforderlichen Rechnungsdaten von den Kund/innen zu erfassen:

FeldWert
nameDer vollständige Name des/der Kund/in.
emailDie E-Mail-Adresse des/der Kund/in.
tax_idDie 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.000.000-00 oder 00000000000. Die CNPJ muss 14 Ziffern in einem der folgenden Formate enthalten: 00.000.000/0000-00 oder 00000000000000.
addressStraße und Hausnummer der Adresse des/der Kund/in.
cityOrt der Adresse des/der Kund/in.
stateDer aus zwei Buchstaben bestehende Code des brasilianischen Bundesstaats (ISO_3166-2:BR) der Adresse des/der Kund/in.
postal_codeDie Postleitzahl der Adresse des/der Kund/in. Die Postleitzahl muss eines der folgenden Formate aufweisen: XXXXX-XXX or XXXXXXXX.

Hinweis

Die Felder name, address, city müssen mindestens ein alphanumerisches Zeichen aus dem Basic-Latin-(ASCII)-Unicode-Block enthalten.

checkout.html
<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 senden
Clientseitig

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.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Erstellen Sie auf Ihrer Zahlungsseite eine Instanz von Stripe.js mit dem folgenden JavaScript.

client.js
// 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.

client.js
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;
  }
});

Hinweis

Die Ausführung von stripe.confirmBoletoPayment 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_action. 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_voucher_url 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 Zahlung
Serverseitig

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.

EreignisBeschreibungNächste Schritte
payment_intent.succeededDer/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_intent.payment_failedDer/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_method.billing_details.email auf die folgenden Werte fest, wenn Sie stripe.confirmBoletoPayment aufrufen, um verschiedene Szenarien zu testen.

E-MailBeschreibung

{any_prefix}@{any_domain}

Simuliert einen Boleto-Gutschein, bei dem Kund/innen nach 3 Minuten bezahlen und der Webhook payment_intent.succeeded nach etwa 3 Minuten eingeht. Im Live-Betrieb geht dieser Webhook 1 Werktag nach der Zahlung ein.

Beispiel: fulaninho@beispiel.com

{any_prefix}succeed_immediately@{any_domain}

Simuliert einen Boleto-Gutschein, bei dem Kund/innen sofort bezahlen und der Webhook payment_intent.succeeded nach wenigen Sekunden eingeht. Im Live-Betrieb geht dieser Webhook 1 Werktag nach der Zahlung ein.

Beispiel: succeed_immediately@beispiel.com

{any_prefix}expire_immediately@{any_domain}

Simuliert einen Boleto-Gutschein, der abläuft, bevor Kund/innen bezahlen, und bei dem der Webhook payment_intent.payment_failed nach wenigen Sekunden eingeht.

Das Feld expires_at in next_action.boleto_display_details wird unabhängig davon, auf was der Parameter expires_after_days in den Optionen für Zahlungsmethoden gesetzt ist, auf die aktuelle Zeit festgelegt.

Beispiel: expire_immediately@beispiel.com

{any_prefix}expire_with_delay@{any_domain}

Simuliert einen Boleto-Gutschein, der abläuft, bevor Kund/innen zahlen, und bei dem der Webhook payment_intent.payment_failed nach ca. 3 Minuten eingeht.

Das Feld expires_at in next_action.boleto_display_details wird unabhängig davon, auf was der Parameter expires_after_days in den Optionen für Zahlungsmethoden gesetzt ist, auf 3 Minuten festgelegt.

Beispiel: expire_with_delay@beispiel.com

{any_prefix}fill_never@{any_domain}

Simuliert einen Boleto-Gutschein, der nie erfolgreich ist. Er läuft entsprechend der Angabe im Feld expires_at in den next_action.boleto_display_details für die angegebenen Parameter in den Optionen für Zahlungsmethoden ab, und der Webhook payment_intent.payment_failed trifft danach ein.

Beispiel: fill_never@beispiel.com

SteueridentifikationsnummerBeschreibung

CPF 000.000.000-00

CNPJ 00.000.000/0000-00

Setzen Sie in einer Sandbox tax_id auf diese Werte und umgehen Sie so die Validierung der Steuer-ID.

OptionalIhre eigene Gutscheinseite erstellen
Clientseitig

Wir empfehlen, den Boleto-Gutschein mithilfe von Stripe.js und confirmBoletoPayment darstellen zu lassen. Sie können Kund/innen den Gutschein aber auch manuell anzeigen.

Sie können handleActions: false beim Aufruf von stripe.confirmBoletoPayment in Schritt 4 festlegen. Dadurch geben Sie an, dass Sie die nächste Aktion vornehmen werden, um Boleto-Details für Ihre Kund/innen anzuzeigen.

client.js
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',
          },
        },
      },
    }, {handleActions: false},
  );
  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  } else {
    // An Boleto voucher was successfully created
    const amount = result.paymentIntent.amount;
    const currency = result.paymentIntent.currency;

    const details = result.paymentIntent.next_action.boleto_display_details;
    const number = details.number;
    const expires_at = details.expires_at;

    // Handle the next action by displaying the Boleto details to your customer

    // You can also use the generated hosted voucher
    const hosted_voucher_url = details.hosted_voucher_url;
  }
});

Geben Sie mindestens Folgendes an:

DetailBeschreibung
NummerZeigen Sie die Nummer des Boleto-Gutscheins an, sodass Ihre Kundinnen/Kunden diese problemlos in ihre Zwischenablage kopieren können. Suchen Sie die Nummer im PaymentIntent-Objekt unter next_action.boleto_display_details.number.
AblaufdatumZeigen Sie das Ablaufdatum des Boleto-Gutscheins an. Suchen Sie den UNIX-Zeitstempel, zu dem der Boleto-Gutschein abläuft, im PaymentIntent unter next_action.boleto_display_details.expires_at.
PDF herunterladenZeigen Sie eine Download-Schaltfläche an, über die Ihr Kunde/Ihre Kundin die Boleto-PDF-Datei herunterladen kann. Suchen Sie nach der PDF-Datei, über die der Kunde/die Kundin den Boleto-Gutschein im PDF-Format für den PaymentIntent unter next_action.boleto_display_details.pdf herunterladen kann.

OptionalPayment Intent serverseitig bestätigen
Serverseitig

Wir empfehlen den Einsatz von Stripe.js, um einen Boleto Payment Intent mit confirmBoletoPayment zu bestätigen. Bei Verwendung von Stripe.js können Sie Ihre Integration viel leichter auf andere Zahlungsmethoden ausdehnen. Sie können einen Payment Intent aber auch serverseitig wie folgt bestätigen:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=brl \
  -d confirm=true \
  -d "payment_method_types[]"=boleto \
  -d "payment_method_data[type]"=boleto \
  -d "payment_method_data[billing_details][name]"="João da Silva" \
  --data-urlencode "payment_method_data[billing_details][email]"="joao@exemplo.com" \
  -d "payment_method_data[billing_details][address][line1]"="1234 Av. Paulista" \
  -d "payment_method_data[billing_details][address][city]"="São Paulo" \
  -d "payment_method_data[billing_details][address][state]"=SP \
  -d "payment_method_data[billing_details][address][postal_code]"=01310-000 \
  -d "payment_method_data[billing_details][address][country]"=BR \
  -d "payment_method_data[boleto][tax_id]"="000.000.000-00"

OptionalZahlungsanweisungen per E-Mail senden

Sie können E-Mails mit Boleto-Zahlungsanweisungen auf der Seite E-Mail-Einstellungen im Dashboard aktivieren. Nach der Aktivierung sendet Stripe E-Mails mit Zahlungsanweisungen, nachdem der PaymentIntent bestätigt wurde. Die E-Mails enthalten die Boleto-Nummer und einen Link zu der von Stripe gehosteten Gutscheinseite.

Hinweis

In Testumgebungen werden E-Mails mit Anweisungen nur an E-Mail-Adressen gesendet, die mit dem Stripe-Konto verknüpft sind.

Ablauf und Stornierung

Boleto-Gutscheine gelten bis zum UNIX-Zeitstempel expires_at, 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_payment_method. Zu diesem Zeitpunkt können Sie den PaymentIntent mit einer anderen Zahlungsmethode bestätigen oder stornieren.