OXXO-Zahlung annehmen

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

Web

Mobilgeräte

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

Name

E-Mail-Adresse

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:

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 einen PaymentIntent auf Ihrem Server mit einem Betrag und der Währung mxn (OXXO unterstützt keine anderen Währungen). Falls Sie bereits über eine Integration verfügen, die die Payment Intents API verwendet, fügen Sie der Liste der Zahlungsmethoden für Ihren PaymentIntent die Zahlungsmethode oxxo hinzu.

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

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:

Feld	Wert
`name`	Der vollständige Name (Vor- und Nachname) der Kundin/des Kunden. Der Vor- und Nachname muss jeweils mindestens zwei Zeichen lang sein.
`email`	Die 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/basil/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;
  }
});

Notiz

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.

Ereignis	Beschreibung	Nächste Schritte
`payment_intent.requires_action`	Der OXXO-Gutschein wurde erfolgreich erstellt.	Warten Sie, bis die Kundin/der Kunde den OXXO-Gutschein bezahlt hat.
`payment_intent.processing`	Die Kundin/der Kunde kann den OXXO-Gutschein nicht mehr bezahlen.	Warten Sie, bis die Zahlung erfolgt oder fehlschlägt.
`payment_intent.succeeded`	Die Kundin/der Kunde hat den OXXO-Gutschein vor Ablauf bezahlt.	Wickeln Sie die Bestellung der Kundin/des Kunden ab.
`payment_intent.payment_failed`	Die 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.

Testzahlungen im Dashboard anzeigen

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.

Nutzerdefinierten Webhook erstellen

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-Adresse	Beschreibung
`{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

OptionalZahlungsanweisungen per E-Mail senden

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 in requires_payment_method. Zu diesem Zeitpunkt können Sie den PaymentIntent mit einer anderen Zahlungsmethode bestätigen oder stornieren.