Accéder directement au contenu
Créez un compte ou connecter-vous
Logo de la documentation Stripe
/
Créez un compteConnectez-vous
AperçuMettre votre intégration à niveau
Paiements en ligne
PrésentationTrouver votre cas d'usageUtiliser Managed Payments
Paiements par TPE
Moyens de paiement
Scénarios de paiement
Au-delà des paiements

Accepter un paiement OXXO

Découvrez comment accepter les paiements effectués à l'aide de OXXO, un moyen de paiement très répandu au Mexique.

Mise en garde

Le contenu de cette section fait référence à un produit antérieur. Vous devez plutôt consulter le guide relatif à l’acceptation d’un paiement pour en savoir plus sur le chemin d’intégration le plus récent. Stripe prend toujours en charge ce produit, néanmoins cette prise en charge peut prendre fin si le produit devient obsolète.

Les utilisateurs de Stripe au Mexique peuvent accepter des paiements OXXO de clients situés au Mexique grâce aux API Payment Intents et Payment Methods. Les clients procèdent au paiement en espèces dans un commerce de proximité OXXO en fournissant un coupon OXXO doté d’un numéro généré automatiquement. Stripe vous informe lorsque le paiement est effectué.

Ce que vous développez

Configurer Stripe
Côté serveur

Tout d’abord, il vous faut un compte Stripe. S’inscrire.

Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre application :

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'

Créer un PaymentIntent
Côté serveur

Pour représenter votre intention d’encaisser le paiement d’un client, Stripe utilise un objet PaymentIntent qui suit les changements d’état du paiement, de la création du coupon OXXO à la finalisation du règlement.

Créez un PaymentIntent sur votre serveur avec un montant et la devise mxn (OXXO ne prendre en charge les autres devises). Si vous disposez déjà d’une intégration utilisant l’API Payment Intents, ajoutez oxxo à la liste des types de moyens de paiement pour votre PaymentIntent.

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"

Récupérer la clé secrète du client

Le PaymentIntent contient une clé secrète à utiliser côté client pour finaliser le processus de paiement en toute sécurité. Vous pouvez adopter différentes approches pour transmettre cette clé secrète côté client.

Récupérez la clé secrète du client à partir d’un endpoint sur votre serveur, à l’aide de la fonction fetch du navigateur. Cette approche est recommandée si votre côté client est une application d’une seule page, en particulier si elle repose sur un framework front-end moderne tel que React. Créez l’endpoint de serveur qui gère la clé secrète du client :

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

Récupérez ensuite la clé secrète du client à l’aide JavaScript côté client :

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

Options supplémentaires du moyen de paiement

Vous pouvez assigner à votre PaymentIntent un paramètre facultatif expires_after_days dans les options du moyen de paiement, afin de configurer le nombre de jours calendaires avant l’expiration d’un coupon OXXO. Par exemple, si vous créez un coupon OXXO le lundi avec un paramètre expires_after_days de 2, le coupon OXXO expirera le mercredi suivant à 23 h 59, heure de la ville de Mexico (America/Mexico_City : UTC-6). La valeur du paramètre expires_after_days doit être comprise entre 1 et 7 jours. Par défaut, elle est de 3 jours.

Collecter les informations du moyen de paiement
Côté client

Créez un formulaire de paiement côté client pour collecter les informations de facturation du client :

ChampValeur
nameLe nom et le prénom du client. Chacun doit comporter au moins deux caractères.
emailL’adresse e-mail complète du client.
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>

Soumettre le paiement à Stripe
Côté client

Lorsqu’un client clique pour payer avec OXXO, utilisez Stripe.js pour soumettre le paiement à Stripe. Stripe.js est notre bibliothèque JavaScript de base pour la création de tunnels de paiement.

Intégrez le script Stripe.js à votre page de paiement en l’ajoutant entre les balises head de votre fichier HTML.

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

Créez une instance de Stripe.js avec le code JavaScript suivant sur votre page de paiement.

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'
);

Utilisez stripe.confirmOxxoPayment et la clé secrète du client de l’objet PaymentIntent créé à l’étape 2 pour envoyer les informations de facturation du client.

Après la confirmation, votre client verra automatiquement s’afficher une fenêtre modale contenant le coupon OXXO.

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

Remarque

L’exécution de la méthode stripe.confirmOxxoPayment peut prendre plusieurs secondes. Pendant ce temps, bloquez le renvoi de votre formulaire et affichez un indicateur d’attente. Si vous recevez une erreur, montrez-la au client, réactivez le formulaire et masquez l’indicateur d’attente.

Une fois le bon OXXO créé, la valeur de la propriété status du PaymentIntent renvoyé passe à requires_action. Vous pouvez vérifier l’état d’un PaymentIntent dans le Dashboard ou en examinant la propriété état de l’objet. Si la création du bon OXXO échoue, examinez la valeur error renvoyée afin de déterminer la cause de cet échec (par exemple, un format d’adresse e-mail non valide).

Facultatif : Envoyer à votre client un e-mail contenant un lien vers le coupon

Stripe envoie un événement payment_intent.requires_action lors de la création d’un coupon OXXO. Si vous souhaitez envoyer à votre client un e-mail contenant un lien vers le coupon, vous pouvez récupérer le PaymentIntent afin d’obtenir un lien lors de la réception de l’événement. Le champ hosted_voucher_url de payment_intent.next_action.oxxo_display_details contient un lien vers le coupon.

Facultatif : Personnaliser votre coupon

Stripe permet de personnaliser les interfaces utilisateur sur la page Adaptation à votre marque.

Vous pouvez appliquer les paramètres de marque suivants à vos coupons :

  • Icône : image représentant votre marque et votre dénomination sociale publique
  • Couleur d’accentuation : utilisée comme couleur du bouton Copier le numéro
  • Couleur de marque : utilisée comme couleur d’arrière-plan

Gérer les événements post-paiement
Côté serveur

OXXO est un moyen de paiement à notification différée, ce qui signifie que les fonds ne sont pas disponibles immédiatement. Il est possible que les clients ne se rendent pas immédiatement dans un magasin pour régler le coupon OXXO.

Stripe envoie un événement payment_intent.succeeded le jour ouvrable suivant (du lundi au vendredi, sauf jours fériés mexicains) pour chaque coupon OXXO payé. Utilisez le Dashboard ou créez un gestionnaire de webhooks pour recevoir ces événements et exécuter certaines actions (comme l’envoi par e-mail d’une confirmation de commande à votre client, l’enregistrement de la vente dans une base de données ou le lancement d’un flux de livraison).

Une fois la date d’expiration passée, l’état du PaymentIntent passe à processing et le client ne peut plus effectuer le règlement du coupon OXXO expiré. Si le coupon OXXO n’est pas payé avant 23 h 59, heure de la ville de Mexico (America/Mexico_City : UTC-6) le jour de son expiration, Stripe envoie un événement payment_intent.payment_failed au plus tard 10 jours calendaires (et le plus souvent moins de 7 jours) après la date d’expiration. Par exemple si le coupon OXXO expire le 1er septembre, l’évènement sera envoyé au plus tard le 10 septembre.

ÉvénementDescriptionÉtapes suivantes
payment_intent.requires_actionLe coupon OXXO a bien été créé.Attendez que le client règle le coupon OXXO.
payment_intent.processingLe client ne peut plus régler le coupon OXXO.Attendez que le paiement réussisse ou échoue.
payment_intent.succeededLe client a réglé le coupon OXXO avant son expiration.Traitez la commande de biens ou de services de votre client.
payment_intent.payment_failedLe client n’a pas réglé le coupon OXXO avant son expiration.Envoyez un e-mail ou une notification push au client pour lui demander d’utiliser un autre moyen de paiement.

Recevoir des événements et exécuter des actions métier

Manuellement

Utilisez le Dashboard Stripe pour consulter tous vos paiements Stripe, envoyer des reçus par e-mail, gérer les virements et relancer les paiements en échec.

Code personnalisé

Créez un gestionnaire de webhooks pour écouter des événements et créer des tunnels de paiement asynchrones personnalisés. Testez et déboguez votre intégration de webhooks en local, grâce à la CLI Stripe.

Tester l'intégration

Dans un environnement de test, définissez payment_method.billing_details.email sur les valeurs suivantes lorsque vous appelez stripe.confirmOxxoPayment pour tester différents scénarios.

Adresse e-mailDescription

{any_prefix}@{any_domain}

Simule un coupon OXXO réglé par le client au bout de 3 minutes et pour lequel le webhook payment_intent.succeeded arrive après environ 3 minutes. En mode production, ce webhook arrive au bout d’un jour ouvrable.

Exemple : fulano@test.com

{any_prefix}succeed_immediately@{any_domain}

Simule un coupon OXXO immédiatement réglé par le client et pour lequel le webhook payment_intent.succeeded arrive en quelques secondes. En mode production, ce webhook arrive au bout d’un jour ouvrable.

Exemple : succeed_immediately@test.com

{any_prefix}expire_immediately@{any_domain}

Simule un coupon OXXO qui expire avant le règlement du client et pour lequel le webhook payment_intent.payment_failed arrive en quelques secondes.

Le champ expires_after de next_action.oxxo_display_details est défini sur la date/heure du jour, quelle que soit la valeur du paramètre expires_after_days des options du moyen de paiement.

Exemple : expire_immediately@test.com

{any_prefix}expire_with_delay@{any_domain}

Simule un coupon OXXO qui expire avant le règlement du client et pour lequel le webhook payment_intent.payment_failed arrive au bout de 3 minutes environ.

Le champ expires_after de next_action.oxxo_display_details est défini sur 3 minutes plus tard, quelle que soit la valeur du paramètre expires_after_days des options du moyen de paiement.

Exemple : expire_with_delay@test.com

{any_prefix}fill_never@{any_domain}

Simule un coupon OXXO qui expire avant le règlement du client et pour lequel le webhook payment_intent.payment_failed arrive au bout d’un jour ouvré et de deux jours calendaires. En mode production, ce webhook arrive à la même vitesse qu’en mode test.

Exemple : fill_never@test.com

FacultatifMontrer les informations OXXO à votre client
Côté client

Nous recommandons d’utiliser Stripe.js pour gérer l’affichage du coupon OXXO à l’aide de confirmOxxoPayment. Vous pouvez toutefois gérer manuellement l’affichage du coupon pour vos clients.

Vous pouvez spécifier handleActions: false lorsque vous appelez stripe.confirmOxxoPayment à l’étape 4 afin d’indiquer que vous gérerez l’action suivante consistant à afficher les informations OXXO pour votre client.

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

Incluez, au minimum, les éléments suivants :

DétailsDescription

Logo OXXO

Affichez le logo OXXO sur le coupon. Vous pouvez télécharger le logo ici.

NuméroRepérez le numéro sur l’objet PaymentIntent dans next_action.oxxo_display_details.number.
Date d’expirationRepérez l’horodatage UNIX indiquant la date d’expiration du coupon OXXO sur le PaymentIntent, dans next_action.oxxo_display_details.expires_after.
MontantLe montant à encaisser.
DeviseLes coupons OXXO sont toujours libellés en pesos mexicains.
Code-barresGénérez le code-barres à partir du numéro en utilisant le Code 128. Une fois imprimé, le code-barres devrait mesurer environ 7,5 cm de long. Pour les affichages mobiles, assurez-vous que l’utilisateur puisse agrandir le code-barres. Cela permettra au caissier du magasin de proximité de le scanner plus facilement. Vous pouvez utiliser une bibliothèque externe, telle que JSBarcode.
Instructions de paiementLes instructions de paiement à l’intention du client. Voir les traductions en français et en espagnol ci-dessous.

Instructions de paiement OXXO

Instructions de paiement OXXO :

  1. Remettez le coupon en caisse pour scan du code-barres.
  2. Réglez votre achat en espèces à la caisse.
  3. Une fois le paiement effectué, conservez le reçu.
  4. Pour toute question ou clarification, veuillez contacter le marchand.
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>

Généralement, les clients impriment le coupon OXXO et l’apportent dans un magasin de proximité. Vous pouvez prévoir un bouton d’impression facile et/ou envoyer le bon OXXO par e-mail à votre client. Nous vous conseillons de tester l’impression du coupon OXXO afin de vérifier la taille du code-barres (qui devrait mesurer environ 7,5 cm de long).

FacultatifEnvoyer des instructions sur les paiements par e-mail

Vous pouvez activer l’envoi d’instructions sur les paiements OXXO et de rappels par e-mail sur la page Paramètres des e-mails sur le Dashboard. Une fois activé, Stripe enverra par e-mail des instructions sur les paiements dès le PaymentIntent confirmé. Les e-mails contiennent le numéro OXXO et un lien vers la page coupon hébergée par Stripe.

Remarque

Dans les environnements de test, seules les adresses e-mail associées au compte Stripe reçoivent des instructions par e-mail.

Expiration et annulation

Les coupons OXXO expirent après l’horodatage Unix expires_after. Une fois le coupon OXXO expiré, le client ne peut plus effectuer le règlement. Les coupons OXXO ne peuvent pas être annulés avant leur expiration.

Après expiration d’un bon de réduction OXXO, l’état de la PaymentIntent passe à requires_payment_method. Vous pouvez alors confirmer la PaymentIntent avec un autre moyen de paiement, ou l’annuler.