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

Paiements Boleto

Découvrez comment accepter Boleto, un moyen de paiement très répandu au Brésil.

Les utilisateurs de Stripe au Brésil peuvent accepter des paiements Boleto grâce aux API Payment Intents et Payment Methods. Les clients procèdent au paiement en utilisant un coupon Boleto doté d’un numéro généré auprès des distributeurs automatiques de billets, des banques, des portails bancaires ou d’agences autorisées.

Configurer Stripe
Côté serveur

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

Utilisez nos bibliothèques officielles pour accéder à l’API Stripe à partir de 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 bon Boleto à la finalisation du règlement.

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

Le PaymentIntent renvoyé contient la clé secrète du client, que vous devez utiliser pour une exécution sécurisée du processus de paiement. Renvoyez la clé secrète au client afin de pouvoir l’utiliser ultérieurement.

Command Line
cURL
Stripe CLI
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=brl \
  -d "payment_method_types[]"=boleto

Options supplémentaires du moyen de paiement

Vous pouvez définir le paramètre facultatif expires_after_days dans les options du moyen de paiement de votre PaymentIntent. Celui-ci permet de paramétrer le nombre de jours calendaires au bout duquel votre bon Boleto expirera. Par exemple, si vous créez un bon Boleto le lundi et que vous définissez expires_after_days sur 2, le bon Boleto expirera le mercredi à 23 h 59, heure de Sao Paulo (America/Sao_Paulo : UTC-3). Si vous le définissez sur 0, le bon Boleto expirera à la fin de la journée. Le paramètre expires_after_days accepte une durée comprise entre 0 et 60 jours. La valeur par défaut est de 3 jours. Vous pouvez personnaliser le nombre de jours de validité par défaut dans les paramètres des moyens de paiement de votre compte

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

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

ChampValeur
nameLe nom complet du client.
emailL’adresse e-mail du client.
tax_idLe CPF (pour les particuliers) ou le CNPJ (pour les entreprises) du client. Le CPF doit comporter 11 chiffres et être saisi dans l’un des formats suivants : 000.000.000-00 ou 00000000000. Le CNPJ doit comporter 14 chiffres être saisi dans l’un des formats suivants : 00.000.000/0000-00 ou 00000000000000.
addressNom de la rue et numéro de l’adresse du client.
cityVille de l’adresse du client
stateLe code ISO (ISO_3166-2:BR) à deux lettres désignant l’état de résidence du client au Brésil.
postal_codeLe code postal de l’adresse du client. Celui-ci doit être saisi dans l’un des formats suivants : XXXXX-XXX ou XXXXXXXX.

Remarque

Les champs name, address et city doivent contenir au moins un caractère alphanumérique de la table des caractères Unicode de latin de base (ASCII).

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="tax_id">
      CPF/CNPJ
    </label>
    <input id="tax_id" name="tax_id" required>
  </div>

  <div class="form-row">
    <label for="email">
      Email
    </label>
    <input id="email" name="email" required>
  </div>

  <div class="form-row">
    <label for="address">
      Address
    </label>
    <input id="address" name="address" required>
  </div>

  <div class="form-row">
    <label for="city">
      City
    </label>
    <input id="city" name="city" required>
  </div>

  <div class="form-row">
    <label for="state">
      State
    </label>
    <input id="state" name="state" required>
  </div>

  <div class="form-row">
    <label for="postal_code">
      Postal Code
    </label>
    <input id="postal_code" name="postal_code" required>
  </div>

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

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

Soumettre le paiement à Stripe
Côté client

Lorsqu’un client clique pour payer avec Boleto, 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 Checkout 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.confirmBoletoPayment 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 Boleto.

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

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

  const result = await stripe.confirmBoletoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        boleto: {
          tax_id: document.getElementById('tax_id').value,
        },
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
          address: {
            line1: document.getElementById('address').value,
            city: document.getElementById('city').value,
            state: document.getElementById('state').value,
            postal_code: document.getElementById('postal_code').value,
            country: 'BR',
          },
        },
      },
    }
  );
  // Stripe.js will open a modal to display the Boleto 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.confirmBoletoPayment 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 coupon Boleto 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é « status » de l’objet. Si la création du coupon Boleto é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 bon Boleto. Si vous souhaitez envoyer à vos clients un e-mail contenant un lien vers le bon, localisez l’adresse hosted_voucher_url dans payment_intent.next_action.boleto_display_details.

Facultatif : Personnaliser votre coupon

Stripe permet de personnaliser les interfaces utilisateur dans 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

Les paiements Boleto sont asynchrones, les fonds ne sont donc pas immédiatement disponibles. Il se peut que les clients ne paient pas le coupon Boleto immédiatement après avoir finalisé la commande.

Stripe envoie un événement payment_intent.succeeded le jour ouvrable suivant (du lundi au vendredi, sauf jours fériés brésiliens) pour chaque bon Boleto payé. Utilisez le Dashboard ou un webhook personnalisé 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).

Si un bon Boleto n’est pas réglé avant sa date d’expiration à 23 h 59, heure de Sao Paulo (America/Sao_Paulo : UTC-3), Stripe envoie un événement payment_intent.payment_failed au bout d’un jour ouvrable. Par exemple, si un bon Boleto expire un jeudi, l’événement est envoyé le vendredi. Si un bon Boleto expire un vendredi, l’événement est envoyé le lundi suivant.

ÉvénementDescriptionÉtapes suivantes
payment_intent.succeededLe client a réglé le coupon Boleto avant son expiration.Traitez la commande de biens ou de services du client.
payment_intent.payment_failedLe client n’a pas réglé le coupon Boleto avant son expiration.Envoyez un e-mail ou une notification push au client pour lui demander d’utiliser un autre moyen de paiement.

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.

E-mailDescription

{any_prefix}@{any_domain}

Simule un coupon Boleto 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 un jour ouvrable après le paiement.

Exemple : fulaninho@example.com

{any_prefix}succeed_immediately@{any_domain}

Simule un coupon Boleto 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 un jour ouvrable après le paiement.

Exemple : succeed_immediately@example.com

{any_prefix}expire_immediately@{any_domain}

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

Le champ expires_at de next_action.boleto_display_details est défini sur l’heure actuelle, quelle que soit la valeur du paramètre expires_after_days des options du moyen de paiement.

Exemple : expire_immediately@example.com

{any_prefix}expire_with_delay@{any_domain}

Simule un coupon Boleto 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_at de next_action.boleto_display_details est défini sur 3 minutes dans le futur, quelle que soit la valeur du paramètre expires_after_days des options du moyen de paiement.

Exemple : expire_with_delay@example.com

{any_prefix}fill_never@{any_domain}

Simule un bon Boleto qui ne réussit jamais. Il expire conformément à la valeur du champ expires_at figurant dans next_action.boleto_display_details, en fonction des paramètres définis dans les options des moyens de paiement. Le webhook payment_intent.payment_failed s’affiche ensuite.

Exemple : fill_never@example.com

Numéro fiscalDescription

CPF 000.000.000-00

CNPJ 00.000.000/0000-00

Dans un environnement de test, définissez le paramètre tax_id sur ces valeurs de manière à contourner la validation du numéro fiscal.

FacultatifCréer votre propre page coupon
Côté client

Nous recommandons l’utilisation de Stripe.js pour gérer l’affichage du coupon Boleto à l’aide de confirmBoletoPayment. Vous pouvez toutefois gérer manuellement l’affichage du coupon pour vos clients.

Vous pouvez définir le paramètre handleActions: false lorsque vous appelez stripe.confirmBoletoPayment à l’étape 4 afin d’indiquer que vous gérerez l’action suivante consistant à afficher les informations Boleto pour votre client.

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

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

  const result = await stripe.confirmBoletoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        boleto: {
          tax_id: document.getElementById('tax_id').value,
        },
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
          address: {
            line1: document.getElementById('address').value,
            city: document.getElementById('city').value,
            state: document.getElementById('state').value,
            postal_code: document.getElementById('postal_code').value,
            country: 'BR',
          },
        },
      },
    }, {handleActions: false},
  );
  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  } else {
    // An Boleto voucher was successfully created
    const amount = result.paymentIntent.amount;
    const currency = result.paymentIntent.currency;

    const details = result.paymentIntent.next_action.boleto_display_details;
    const number = details.number;
    const expires_at = details.expires_at;

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

    // You can also use the generated hosted voucher
    const hosted_voucher_url = details.hosted_voucher_url;
  }
});

Inclure au minimum les éléments suivants :

DétailDescription
NuméroAffichez le numéro du bon Boleto de manière à ce que vos clients puissent facilement le copier dans leur presse-papiers. Repérez le numéro sur l’objet PaymentIntent dans next_action.boleto_display_details.number.
Date d’expirationAffichez la date d’expiration du bon Boleto. Repérez l’horodatage UNIX indiquant la date d’expiration du bon Boleto dans le PaymentIntent, sous next_action.boleto_display_details.expires_at.
Télécharger le PDFAffichez un bouton de téléchargement pour permettre à votre client de télécharger le boleto au format PDF. Repérez le pdf (permettant au client de télécharger le PDF du bon Boleto) dans le PaymentIntent à l’adresse next_action.boleto_display_details.pdf.

FacultatifConfirmer le PaymentIntent côté serveur
Côté serveur

Nous vous recommandons de vous appuyer sur Stripe.js pour confirmer un Payment Intent Boleto avec confirmBoletoPayment. L’utilisation de Stripe.js facilite grandement l’extension de votre intégration à d’autres moyens de paiement. Cependant, vous pouvez également confirmer un Payment Intent côté serveur de la manière suivante :

Command Line
cURL
Stripe CLI
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=brl \
  -d confirm=true \
  -d "payment_method_types[]"=boleto \
  -d "payment_method_data[type]"=boleto \
  -d "payment_method_data[billing_details][name]"="João da Silva" \
  --data-urlencode "payment_method_data[billing_details][email]"="joao@exemplo.com" \
  -d "payment_method_data[billing_details][address][line1]"="1234 Av. Paulista" \
  -d "payment_method_data[billing_details][address][city]"="São Paulo" \
  -d "payment_method_data[billing_details][address][state]"=SP \
  -d "payment_method_data[billing_details][address][postal_code]"=01310-000 \
  -d "payment_method_data[billing_details][address][country]"=BR \
  -d "payment_method_data[boleto][tax_id]"="000.000.000-00"

FacultatifEnvoyer des instructions sur les paiements par e-mail

Vous pouvez activer l’envoi d’instructions sur les paiements Boleto par e-mail sur la page des paramètres de messagerie du Dashboard. Une fois l’option activée, Stripe enverra par e-mail des instructions sur les paiements dès le PaymentIntent confirmé. Les e-mails contiennent le numéro Boleto 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 Boleto expirent après l’horodatage Unix expires_at. Une fois le coupon Boleto expiré, le client ne peut plus effectuer le règlement. Les coupons Boleto ne peuvent pas être annulés avant leur expiration.

Après expiration d’un coupon Boleto, l’état du PaymentIntent passe à requires_payment_method. Vous pouvez alors confirmer le PaymentIntent avec un autre moyen de paiement, ou l’annuler.