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

OXXO-Zahlung annehmen

So akzeptieren Sie Zahlungen per OXXO, einer gängigen Zahlungsmethode in Mexiko.

Vorsicht

Der Inhalt dieses Abschnitts bezieht sich auf ein Legacy-Produkt. Verwenden Sie den Leitfaden Zahlungen akzeptieren für den aktuellsten Integrationspfad. Auch wenn Stripe dieses Produkt jetzt noch unterstützt, kann sich dies ändern, wenn das Produkt nicht mehr unterstützt wird.

Stripe-Nutzer/innen in Mexiko können OXXO-Zahlungen von Kund/innen in Mexiko mithilfe der Payment Intents API und Payment Methods API annehmen. DieKund/innen nutzen einen OXXO-Gutschein mit einer generierten Nummer zur Barzahlung in einem OXXO Convenience Store. Stripe benachrichtigt Sie, wenn die Zahlung abgeschlossen ist.

Das erstellen Sie gerade

Stripe einrichten
Serverseitig

Als Erstes 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:

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'

Erstellen Sie ein PaymentIntent
Serverseitig

Stripe verwendet ein PaymentIntent-Objekt, um Ihre Absicht darzustellen, Zahlungen von Kundinnen/Kunden einzuziehen und Statusänderungen von der Erstellung des OXXO-Gutscheins bis zum Zahlungsabschluss zu verfolgen.

Erstellen Sie ein PaymentIntent auf Ihrem Server mit einem Betrag und der Währung mxn (andere Währungen werden von OXXO nicht unterstützt). Wenn Sie bereits eine Integration mit der Payment Intents API haben, fügen Sie oxxo zur Liste der Zahlungsmethoden für Ihren PaymentIntent hinzu.

Command Line
curl
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"="mxn" \
  -d "payment_method_types[]"="oxxo"

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:

main.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

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

Zusätzliche Optionen für Zahlungsmethoden

Sie können für Ihren PaymentIntent den optionalen Parameter expires_after_days in den Optionen für Zahlungsmethoden nutzen, um die Gültigkeit eines OXXO-Gutscheins in Kalendertagen anzugeben. Wenn Sie beispielsweise einen OXXO-Gutschein am Montag erstellen und expires_after_days auf 2 setzen, läuft der OXXO-Gutschein am Mittwoch um 23:59 Uhr amerikanischer/mexikanischer Zeit (UTC-6) ab. Der Parameter expires_after_days kann Werte zwischen 1 und 7 aufweisen. Der Standardwert ist 3 Tage.

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 (Vor- und Nachname) der Kundin/des Kunden. Der Vor- und Nachname muss jeweils mindestens zwei Zeichen lang sein.
emailDie vollständige E-Mail-Adresse des/der Kund/in.
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="email">
      Email
    </label>
    <input id="email" name="email" required>
  </div>

  <!-- Used to display form errors. -->
  <div id="error-message" role="alert"></div>

  <button id="submit-button">Pay with OXXO</button>
</form>

Zahlung an Stripe senden
Clientseitig

Verwenden Sie Stripe.js zur Übermittlung von Zahlungen an Stripe, wenn Kundinnen/Kunden mit OXXO 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 Bezahlseite 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 einen Instanz von Stripe.js mit dem folgenden JavaScript auf Ihrer Bezahlseite.

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.confirmOxxoPayment 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 OXXO-Gutschein für Ihre Kundin/Ihren Kunden anzuzeigen.

client.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmOxxoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
        },
      },
    });
  // Stripe.js will open a modal to display the OXXO 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.confirmOxxoPayment 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 die Kundin/den Kunden anzeigen, aktivieren Sie das Formular erneut und blenden Sie das Wartesymbol aus.

Wenn die Erstellung des OXXO-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 Statuseigenschaft des Objekts einsehen. War die Erstellung des OXXO-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 OXXO-Gutschein erfolgreich erstellt wurde. Wenn Sie Ihren Kundinnen/Kunden den Gutschein-Link per E-Mail zusenden möchten, können Sie den PaymentIntent abrufen, um den Link beim Empfang des Ereignisses zu erhalten. Das Feld hosted_voucher_url in payment_intent.next_action.oxxo_display_details enthält den Link zum Gutschein.

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

Ereignisse nach der Zahlung verarbeiten
Serverseitig

OXXO ist eine Zahlungsmethode mit verzögerter Benachrichtigung, bei der Gelder nicht sofort verfügbar sind. Kundinnen/Kunden bezahlen den OXXO-Gutschein eventuell nicht sofort nach dem Abschluss des Bestellvorgangs in einem OXXO Convenience Store.

Für jeden bezahlten OXXO-Gutschein übermittelt Stripe am nächsten Werktag (Montag bis Freitag außer an mexikanischen Feiertagen) das Ereignis payment_intent.succeeded. Verwenden Sie das Dashboard oder erstellen Sie einen Webhook-Handler, 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).

Nach Ablauf der Gültigkeit geht der Status des PaymentIntent in processing über, und die Kundinnen/Kunden können nicht mehr mit den abgelaufenen OXXO-Gutschein bezahlen. Wenn der OXXO-Gutschein nicht vor 23:59 Uhr amerikanischer/mexikanischer Zeit (UTC-6) am Ablaufdatum bezahlt wird, sendet Stripe innerhalb von 10 Kalendertagen nach dem Ablaufdatum ein payment_intent.payment_failed-Ereignis (in den meisten Fällen wird es innerhalb von 7 Kalendertagen gesendet). Wenn der OXXO-Gutschein z. B. am 1. September abgelaufen ist, wird das Ereignis spätestens am 10. September gesendet.

EreignisBeschreibungNächste Schritte
payment_intent.requires_actionDer OXXO-Gutschein wurde erfolgreich erstellt.Warten Sie, bis die Kundin/der Kunde den OXXO-Gutschein bezahlt hat.
payment_intent.processingDie Kundin/der Kunde kann den OXXO-Gutschein nicht mehr bezahlen.Warten Sie, bis die Zahlung erfolgt oder fehlschlägt.
payment_intent.succeededDie Kundin/der Kunde hat den OXXO-Gutschein vor Ablauf bezahlt.Wickeln Sie die Bestellung der Kundin/des Kunden ab.
payment_intent.payment_failedDie Kundin/der Kunde hat den OXXO-Gutschein nicht vor Ablauf bezahlt.Kontaktieren Sie Ihre/n Kund/in per E-Mail oder Push-Benachrichtigung und fordern Sie eine andere Zahlungsmethode an.

Ereignisse empfangen und Geschäftsaktionen ausführen

Manuell

Im Stripe-Dashboard können Sie alle Stripe-Zahlungen anzeigen, Zahlungsbelege per E-Mail versenden, Auszahlungen abwickeln oder fehlgeschlagene Zahlungen erneut durchführen.

Nutzerdefinierter Code

Erstellen Sie einen Webhook-Handler, um Ereignisse zu überwachen und nutzerdefinierte asynchrone Zahlungsabläufe zu erstellen. Mit der Stripe-CLI können Sie Ihre Webhook-Integration lokal testen und Fehler beheben.

Integration testen

Legen Sie in einer Sandbox payment_method.billing_details.email auf die folgenden Werte fest, wenn Sie stripe.confirmOxxoPayment aufrufen, um verschiedene Szenarien zu testen.

E-Mail-AdresseBeschreibung

{any_prefix}@{any_domain}

Simuliert einen OXXO-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 nach 1 Werktag ein.

Beispiel: fulano@test.com

{any_prefix}succeed_immediately@{any_domain}

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

Beispiel: succeed_immediately@test.com

{any_prefix}expire_immediately@{any_domain}

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

Das Feld expires_after in next_action.oxxo_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@test.com

{any_prefix}expire_with_delay@{any_domain}

Simuliert einen OXXO-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_after in next_action.oxxo_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@test.com

{any_prefix}fill_never@{any_domain}

Simuliert einen OXXO-Gutschein, der abläuft, bevor Kund/innen bezahlen, und bei dem der Webhook payment_intent.payment_failed nach 1 Werktag und 2 Kalendertagen eingeht. Im Live-Betrieb geht dieser Webhook zur gleichen Zeit ein wie im Test-Modus.

Beispiel: fill_never@test.com

OptionalOXXO-Details für die Kund/innen anzeigen
Clientseitig

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

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

client.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmOxxoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
        },
      },
    }, {handleActions: false},
  );

  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  } else {
    // An OXXO voucher was successfully created
    const amount = result.paymentIntent.amount;
    const currency = result.paymentIntent.currency;

    const details = result.paymentIntent.next_action.oxxo_display_details;
    const number = details.number;
    const expires_after = details.expires_after;

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

    // You can also use the generated hosted voucher
    const hosted_voucher_url = result.paymentIntent.next_action.oxxo_display_details.hosted_voucher_url;
  }
});

Geben Sie mindestens Folgendes an:

DetailsBeschreibung

OXXO-Logo

Betten Sie das OXXO-Logo in den Gutschein ein. Sie können das Logo hier herunterladen.

NummerSuchen Sie die Nummer im PaymentIntent-Objekt unter next_action.oxxo_display_details.number.
AblaufdatumSuchen Sie den UNIX-Zeitstempel, zu dem der OXXO-Gutschein abläuft, im PaymentIntent unter next_action.oxxo_display_details.expires_after.
BetragDer einzuziehende Betrag.
WährungOXXO-Gutscheine sind immer in mexikanischen Pesos ausgestellt.
BarcodeErzeugen Sie mit Code 128 aus der Nummer einen Barcode. Der Barcode sollte gedruckt ca. 7,5 cm breit sein. Stellen Sie bei mobilen Displays sicher, dass der Barcode vergrößert werden kann. Dies erleichtert den Mitarbeiter/innen des OXXO Convenience Store das Einlesen. Sie können eine externe Bibliothek wie z. B. JSBarcode verwenden.
ZahlungsanweisungenDie Zahlungsanweisungen für Kundinnen/Kunden. Die englischen und spanischen Versionen finden Sie unten.

OXXO-Zahlungsanweisungen

OXXO-Zahlungsanweisungen:

  1. Zeigen Sie den Gutschein an der Kasse vor, damit der Barcode gescannt werden kann.
  2. Bezahlen Sie in bar an der Kasse.
  3. Bewahren Sie nach Abschluss der Zahlung den Zahlungsbeleg für Ihre Unterlagen auf.
  4. Bei Fragen oder Unklarheiten wenden Sie sich bitte an den Händler.
HTML
CSS
JavaScript
No results
<!-- Include a library for generating OXXO bar codes, such as JsBarcode -->
<!-- <script src="https://cdn.jsdelivr.net/jsbarcode/3.6.0/barcodes/JsBarcode.code128.min.js"></script> -->

<div class="result-oxxo">
  <img width="100px" src="/images/payments/oxxo.png">
  <div class="amount">MX <span class="order-amount"></span></div>
  <div>Expires <span class="oxxo-expiry-date"></span></div>
  <div class="oxxo-display"></div>

  <button onclick="window.print()">Print</button>

  <div class="instructions">
    Instructions to pay your OXXO:
    <ol>
      <li><p>Give the voucher to the cashier to scan the barcode.</p></li>
      <li><p>Provide cash payment to the cashier.</p></li>
      <li><p>After the payment is complete, keep the receipt of your payment for your records.</p></li>
      <li><p>For any questions or clarification, please contact the merchant.</p></li>
    </ol>
  </div>
</div>

In der Regel drucken Kund/innen den OXXO-Gutschein aus, um ihn bei einem OXXO Convenience Store vorzulegen. Sie können eine einfache Drucken-Schaltfläche bereitstellen und/oder den OXXO-Gutschein per E-Mail an die Kundinnen/Kunden senden. Drucken Sie den OXXO-Gutschein selbst aus, um die Größe des Barcodes zu prüfen (er sollte etwa 7,5 cm breit sein).

OptionalZahlungsanweisungen per E-Mail senden

Sie können E-Mails mit OXXO-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 OXXO-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

OXXO-Gutscheine gelten bis zum UNIX-Zeitstempel expires_after, und Kundinnen und Kunden können einen OXXO-Gutschein nicht mehr bezahlen, wenn er abgelaufen ist. OXXO-Gutscheine können nicht vor Ablauf storniert werden.

Nachdem ein OXXO-Gutschein abgelaufen ist, ändert sich der Status des PaymentIntent inrequires_payment_method. Zu diesem Zeitpunkt können Sie den PaymentIntent mit einer anderen Zahlungsmethode bestätigen oder stornieren.