Ajouter des moyens de paiement personnalisés

Apprenez à ajouter des moyens de paiement personnalisés au Payment Element.

Utilisez le Payment Element avec l’API Payment Intents pour afficher plus de 50 moyens de paiement préréglés, ainsi que vos moyens de paiement personnalisés, via un seul intégration. Après avoir créé votre moyen de paiement personnalisé dans le Dashboard, configurez le Payment Element pour vous assurer que ces transactions soient traitées et finalisées correctement en dehors de Stripe. Vous pouvez enregistrer ces transactions sur votre compte Stripe à des fins de reporting.

Remarque

Lors de l’intégration avec un prestataire de services de paiement tiers, vous êtes responsable de la conformité avec exigences juridiques applicables, y compris votre accord avec votre PSP, les lois applicables, etc.

Avant de commencer

Créer un compte Stripe ou se connecter avec votre compte existant.
Suivez ce guide pour compléter une intégration de paiement.

Créez votre moyen de paiement personnalisé
via le Dashboard.

Vous pouvez créer un moyen de paiement personnalisé dans le Dashboard en allant dans Paramètres > Paiements >Moyens de paiement personnalisés. Indiquez le nom et le logo du Payment Element à afficher.

Choisir le bon logo

Pour les logos avec un arrière-plan transparent, tenez compte de la couleur d’arrière-plan du Payment Element sur votre page et veillez à ce qu’ils ressortent bien.
Pour les logos avec un remplissage d’arrière-plan, incluez des coins arrondis dans votre fichier, si nécessaire.
Choisissez une variante de logo qui peut être réduite à 16 x 16 pixels. Il s’agit souvent du logo autonome d’une marque.

Après avoir créé le moyen de paiement personnalisé, le Dashboard affiche l’identifiant du moyen de paiement personnalisé (commençant par cpmt_) requis à l’étape suivante.

Ajouter un type de moyen de paiement personnalisé
Côté client

Ajoutez ensuite le type de moyen de paiement personnalisé à votre configuration Stripe Elements. Dans votre fichier checkout.js où vous initialisez Stripe Elements, spécifiez l’ajout du fichier customPaymentMethods au Payment Element. Fournissez l’ID du moyen de paiement personnalisé de l’étape précédente, l’options.type, et un sous-titre facultatif.

checkout.js
const elements = stripe.elements({
  // ...
  customPaymentMethods: [
    {
      id: '{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}'
,
      options: {
        type: 'static',
        subtitle: Optional subtitle,
      }
    }
  ]
});

Après que le Payment Element se charge, il affiche votre moyen de paiement personnalisé.

Le Payment Element de Stripe affichant un moyen de paiement personnalisé appelé PM Name.

FacultatifAffichage de contenu personnalisé intégré
Aperçu
Côté client

Utilisez le type embedded pour afficher le contenu de votre moyen de paiement personnalisé dans le composant Payment Element.

Le composant Payment Element de Stripe affichant un moyen de paiement personnalisé appelé PM Name, avec du contenu personnalisé superposé dans le conteneur de formulaires.

Gérez votre contenu personnalisé à l’aide des rappels suivants :

handleRender : Appelé lorsqu’un moyen de paiement est sélectionné et qu’il contient une référence à un node DOM conteneur dans lequel vous pouvez afficher votre contenu.
handleDestroy : Appelé lorsqu’un moyen de paiement est désélectionné et que le Payment Element n’est pas monté. Effectue des nettoyages, tels que la suppression d’écouteurs d’événements ou d’un SDK personnalisé.

Conseil en matière de sécurité

Afficher uniquement le contenu approuvé dans le container fourni par handleEmbed. La majoration de rendu que vous ne contrôlez pas, en particulier à partir d’un utilisateur ou d’une source non nettoyée, peut introduire une vulnérabilité de type cross-site scripting (XSS).

Des outils tels que React Portals vous permettent d’intégrer votre logique de rendu au code de votre application :

checkout.js
import {Elements} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';

// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

export default function App() {
  const [embedContainer, setEmbedContainer] = useState();

  const options = {
    customPaymentMethods: [
      {
        id: '{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}',
        options: {
          type: 'embedded',
          subtitle: Embedded payment method,
          embedded: {
            handleRender: (container) => {
              setEmbedContainer(container);
            },
            handleDestroy: () => {
              setEmbedContainer(null);
            }
          }
        }
      }
    ]
  };

  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutFormWithPaymentElement />
      {embedContainer && createPortal(<EmbeddedCpmContent />, embedContainer)}
    </Elements>
  );
};

Traiter la soumission du moyen de paiement
Côté client

Mettez à jour la fonction handleSubmit qui est appelée lorsque les utilisateurs cliquent sur le bouton de paiement sur votre site Web afin de traiter les transactions avec un moyen de paiement personnalisé en dehors de Stripe.

La fonction elements.submit() récupère le type de moyen de paiement sélectionné. Par exemple, vous pouvez afficher une fenêtre modale, puis traiter le paiement sur votre propre serveur, ou rediriger votre client vers une page de paiement externe.

checkout.js
async function handleSubmit(e) {
  const { submitError, selectedPaymentMethod } = await elements.submit();

  if (selectedPaymentMethod === '{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}'
) {
    // Process CPM payment on merchant server and handle redirect
    const res = await fetch("/process-cpm-payment", { method: 'post' });
    ...
  } else {
    // Process Stripe payment methods
    ...
  }
}

FacultatifIndiquer l'ordre des moyens de paiement personnalisés
Côté client

Par défaut, le Payment Element affiche les moyens de paiement personnalisés en dernier. Pour indiquer manuellement l’ordre des moyens de paiement, définissez la propriété paymentMethodOrder dans la configuration des options lors de la création de votre instance de Payment Element.

checkout.js
const paymentElement = elements.create('payment', {
  // an array of payment method types, including custom payment method types
  paymentMethodOrder: [...]
});

FacultatifEnregistrer le paiement sur votre compte Stripe
Côté serveur

Bien que vous traitiez les transactions avec des moyens de paiement personnalisés en dehors de Stripe, vous pouvez toujours enregistrer les détails de la transaction sur votre compte Stripe. Cela vous aide à créer des rapports uniformes et à mettre en place des workflows de back-office, tels que l’émission de reçus ou la création de rapports.

server.js
const stripe = new Stripe('sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-10-29.clover; invoice_partial_payments_beta=v3'
});

app.get('/process-cpm-payment', async (req, res) => {
  const paymentResult = processMyCustomPayment(...)

  // Create an instance of a custom payment method
  const paymentMethod = await stripe.paymentMethods.create({
    type: 'custom',
    custom: {
      type: '{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}'
,
    }
  });

  // Report successful payment
  const paymentRecord = await stripe.paymentRecords.reportPayment({
    amount_requested: {
      value: paymentResult.amount,
      currency: paymentResult.currency
    },
    payment_method_details: {
      payment_method: paymentMethod.id
    },
    customer_details: {
      customer: paymentResult.customer.id
    },
    processor_details: {
      type: 'custom',
      custom: {
        payment_reference: paymentResult.id
      }
    },
    initiated_at: paymentResult.initiated_at,
    customer_presence: 'on_session',
    outcome: 'guaranteed',
    guaranteed: {
      guaranteed_at: paymentResult.completed_at
    }
  });

  // Respond to frontend to finish buying experience
  return res.json(...)
});

Ajouter des moyens de paiement personnalisés

Apprenez à ajouter des moyens de paiement personnalisés au Payment Element.

Remarque

Avant de commencer

Créez votre moyen de paiement personnalisévia le Dashboard.

Choisir le bon logo

Ajouter un type de moyen de paiement personnaliséCôté client

FacultatifAffichage de contenu personnalisé intégréAperçuCôté client