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

Accepter un paiement Multibanco

Découvrez comment accepter le moyen de paiement Multibanco.

Mise en garde

Nous vous recommandons de suivre le guide Accepter un paiement, sauf si vous devez exécuter la confirmation manuelle côté serveur, ou si votre intégration requiert la présentation de moyens de paiement de manière distincte. Si vous avez déjà intégré Elements, consultez le Guide de migration du Payment Element.

Multibanco est un moyen de paiement à l’aide de coupons répandu au Portugal. Si votre entreprise est établie en Europe ou aux États-Unis, vous pouvez accepter les paiements Multibanco de vos clients au Portugal à l’aide de l’API Payment Intents.

Pour effectuer une transaction, les clients reçoivent un bon sur lequel figurent les numéros d’entité et de référence Multibanco. Les clients utilisent ces informations de coupon pour effectuer un paiement en dehors de votre tunnel de paiement, via leur espace bancaire en ligne ou au distributeur automatique de billets.

La confirmation du paiement peut être retardée de plusieurs jours en raison de l’initiation d’un virement bancaire lorsqu’un client règle un bon Multibanco. Les virements bancaires peuvent subir des retards, en particulier le week-end, ce qui contribue à retarder la confirmation du paiement.

Configurer Stripe
Côté serveur

Pour commencer, vous devez créer un compte Stripe. S’inscrire.

Pour accéder à l’API Stripe depuis votre application, utilisez nos bibliothèques officielles :

Command Line
# Available as a gem
sudo gem install stripe
Gemfile
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Créer un PaymentIntent
Côté serveur

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

Créez un PaymentIntent sur votre serveur en précisant un montant et la devise eur (Multibanco ne prend pas en charge d’autres devises). Si votre intégration inclut déjà l’API Payment Intents, ajoutez multibanco à la liste des types de moyens de paiement valides pour votre PaymentIntent.

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=eur \
  -d "payment_method_types[]"=multibanco

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

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
emailL’adresse e-mail complète du client.
checkout.html
<form id="payment-form">
  <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 Multibanco</button>
</form>

Envoyer le paiement à Stripe
Côté client

Lorsqu’un client clique pour payer avec Multibanco, 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'
);

Soumettez les informations de facturation du client en appelant stripe.confirmMultibancoPayment avec la clé secrète du client de l’objet PaymentIntent que vous avez créé.

Après la confirmation, votre client voit automatiquement s’afficher une fenêtre modale contenant le bon Multibanco.

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

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

  const result = await stripe.confirmMultibancoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        billing_details: {
          email: document.getElementById('email').value,
        },
      },
    });
  // Stripe.js will open a modal to display the Multibanco 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.confirmMultibancoPayment peut prendre plusieurs secondes. Pendant ce temps, bloquez le renvoi de votre formulaire et affichez un indicateur d’attente. Si vous recevez une erreur, affichez-la, réactivez le formulaire et masquez l’indicateur d’attente.

Une fois le bon Multibanco 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 Multibanco é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).

Stripe envoie un événement payment_intent.requires_action lors de la création d’un bon Multibanco. Si vous avez besoin d’envoyer un e-mail avec le lien vers les instructions de paiement du bon, vous pouvez localiser le hosted_voucher_url dans payment_intent.next_action.multibanco_display_details.hosted_voucher_url.

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

Multibanco est un moyen de paiement à notification différée. Un client règle un bon Multibanco en dehors de votre tunnel de paiement, via son espace bancaire en ligne ou à un distributeur automatique de billets.

Une fois qu’un paiement Multibanco aboutit, Stripe envoie un événement payment_intent.succeeded. Utilisez le Dashboard ou créez un gestionnaire de webhooks pour recevoir ces événements et exécuter des actions, comme envoyer une confirmation de commande par e-mail à votre client, enregistrer la vente dans une base de données ou lancer un flux de livraison.

En savoir plus sur l’expiration des bons Multibanco.

ÉvénementDescriptionProchaines étapes
payment_intent.requires_actionLe bon Multibanco a bien été créé.Attendez que le client règle le bon Multibanco.
payment_intent.processingLe client ne peut plus régler le bon Multibanco.Attendez que le paiement aboutisse ou échoue.
payment_intent.succeededLe client a payé le bon Multibanco.Traitez la commande de biens ou de services du client.
payment_intent.payment_failedLe client n’a pas payé le bon Multibanco.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 localement, grâce à l’interface de ligne de commande Stripe.

Découvrez comment 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.confirmMultibancoPayment pour tester différents scénarios.

E-mailDescription

{any_prefix}@{any_domain}

Simule un bon Multibanco payé par un client. Le webhook payment_intent.succeeded arrive après environ 3 minutes.

Exemple : julie@exemple.com

{any_prefix}succeed_immediately@{any_domain}

Simule un bon Multibanco qu’un client paie immédiatement. Le webhook payment_intent.succeeded arrive en quelques secondes.

Exemple : succeed_immediately@exemple.com

{any_prefix}expire_immediately@{any_domain}

Simule un bon Multibanco qui expire immédiatement. Le webhook payment_intent.payment_failed arrive en quelques secondes.

Exemple : expire_immediately@exemple.com

{any_prefix}expire_with_delay@{any_domain}

Simule un bon Multibanco qui expire avant le règlement du client. Le webhook payment_intent.payment_failed arrive après environ 3 minutes.

Exemple : expire_with_delay@exemple.com

{any_prefix}fill_never@{any_domain}

Simule un bon Multibanco qui n’aboutit jamais. Le webhook payment_intent.payment_failed arrive au bout de 11 jours, ce qui simule le comportement en mode production. En savoir plus sur l’expiration des bons Multibanco.

Exemple : fill_never@example.com

Date d’expiration

Les bons Multibanco expirent à la date UNIX expires_at indiquée dans next_action.multibanco_display_details.expires_at, soit 7 jours après la création du bon. Les clients ne peuvent pas payer un bon Multibanco après son expiration. Après expiration, l’état du PaymentIntent passe de requires_action à processing et Stripe envoie un événement payment_intent.processing.

Le PaymentIntent demeure à l’état processing pendant une période de 4 jours pour tenir compte des éventuels retards de notification de paiement réussi causés par les retards de virement bancaire. Si le paiement Multibanco n’est pas finalisé au cours de cette période, l’état du PaymentIntent passe à requires_payment_method et Stripe envoie un événement payment_intent.payment_failed. Si vous recevez les fonds du client après cette période, Stripe lance automatiquement un processus de remboursement pour le montant indûment versé.

Annulation

Vous pouvez annuler les bons Multibanco en annulant un PaymentIntent. Après l’annulation, Stripe envoie un événement payment_intent.canceled.

Si les fonds d’un client sont versés alors que le bon Multibanco est annulé, Stripe lance automatiquement le processus de remboursement du montant indûment versé.

Remarque

L’annulation d’un paiement en attente entraîne l’invalidation des instructions initiales du bon. Lorsque vous annulez un paiement Multibanco en attente, informez-en votre client.

Lorsque vous reconfirmez avec succès un PaymentIntent à l’état requires_action, Stripe crée de nouvelles instructions pour le coupon et un nouveau hosted_voucher_url. Vous devez les fournir à votre client.

Remboursements

En savoir plus sur les remboursements Multibanco.

Cette page vous a-t-elle été utile ?
OuiNon
Besoin d'aide ? Contactez le service Support.
Rejoignez notre programme d'accès anticipé.
Consultez notre log des modifications.
Des questions ? Contactez l'équipe commerciale.
LLM ? Lire llms.txt.
Propulsé par Markdoc