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.

Web

Mobile

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

Nom

E-mail

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 :

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 en spécifiant un montant et la devise mxn (OXXO n’accepte pas d’autres devises). Si votre intégration inclut déjà l’API Payment Intents, ajoutez oxxo à la liste des types de moyens de paiement pour votre PaymentIntent.

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 :

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 :

Champ	Valeur
`name`	Le nom et le prénom du client. Chacun doit comporter au moins deux caractères.
`email`	L’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/basil/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énement	Description	Étapes suivantes
`payment_intent.requires_action`	Le coupon OXXO a bien été créé.	Attendez que le client règle le coupon OXXO.
`payment_intent.processing`	Le client ne peut plus régler le coupon OXXO.	Attendez que le paiement réussisse ou échoue.
`payment_intent.succeeded`	Le client a réglé le coupon OXXO avant son expiration.	Traitez la commande de biens ou de services de votre client.
`payment_intent.payment_failed`	Le 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.

Afficher vos paiements tests dans le Dashboard

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.

Créer un webhook personnalisé

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-mail	Description
`{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

FacultatifEnvoyer des instructions sur les paiements 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 coupon OXXO, l’état du PaymentIntent passe à requires_payment_method. Vous pouvez alors confirmer le PaymentIntent avec un autre moyen de paiement, ou l’annuler.