Accepter un paiement FPX

Découvrez comment accepter les paiements effectués à l'aide de FPX, un moyen de paiement très répandu en Malaisie.

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.

FPX est un moyen de paiement à usage unique. Pour effectuer un paiement avec FPX, les clients quittent votre site Web, autorisent le paiement, puis reviennent vers votre site Web. Vous recevez alors une notification immédiate indiquant si le paiement a abouti ou échoué.

To enable FPX payments:

Navigate to the Payment methods settings in the Dashboard. If you haven’t already, activate your Stripe account.
Find FPX under Bank redirects and select Turn on.
Accept the FPX terms of service.

FPX is only available to merchants based in Malaysia. See payment method support for more information about countries, currencies, and payment methods compatible with Stripe products.

Remarque

FPX est un moyen de paiement à usage unique qui ne peut pas être utilisé pour des paiements récurrents ou supplémentaires. Actuellement, il n’est pas pris en charge par Stripe Billing. La prise en charge des paiements FPX pour les comptes Custom est en version bêta. Veuillez contacter le service Support de Stripe pour toute demande de support.

Configurer Stripe
Côté serveur

Pour commencer, vous avez besoin d’un compte Stripe. Inscrivez-vous.

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

Créer un PaymentIntent
Côté serveur

Un PaymentIntent représente votre intention d’encaisser un paiement auprès d’un client et suit le cycle de vie du processus de paiement étape par étape. Créez un PaymentIntent dès que vous connaissez le montant (par exemple, au début du processus de paiement). Pour ce faire, utilisez les valeurs suivantes :

Paramètre	Valeur
`payment_method_types`	fpx
`amount`	Nombre entier positif dans la plus petite unité monétaire représentant le montant à facturer au client (par exemple, 1099 pour un paiement de 10,99 RM). Stripe prend en charge les montants allant de 2 RM à 30 000 RM par transaction.
`currency`	myr (FPX doit toujours utiliser le Ringgit).

Vous pouvez également mettre à jour le montant s’il change ultérieurement (à l’occasion par exemple du calcul des frais de livraison et des taxes) :

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

Stripe Elements est un ensemble de composants d’interface utilisateur préconfigurés pour la collecte des informations de paiement. Elements est automatiquement fourni en tant que fonctionnalité de Stripe.js. Incluez le script Stripe.js sur votre page de paiement en l’ajoutant à la section head de votre fichier HTML. Chargez toujours Stripe.js directement depuis js.stripe.com pour maintenir votre conformité PCI. Vous ne devez pas inclure le script dans un lot ni en héberger de copie.

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

Créez une instance d’Elements à l’aide du code JavaScript suivant sur votre page de paiement.

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);
const elements = stripe.elements();

Elements doit avoir un emplacement dédié dans votre formulaire de paiement. Créez des nœuds DOM (conteneurs) ayant des ID uniques dans votre formulaire de paiement, puis transmettez ces ID à Elements.

checkout.html
<form id="payment-form">
  <div class="form-row">
    <div>
      <label for="fpx-bank-element">
        FPX Bank
      </label>
      <div id="fpx-bank-element">
        <!-- A Stripe Element will be inserted here. -->
      </div>
    </div>
  </div>

  <button id="fpx-button" data-secret="{{ CLIENT_SECRET }}">
    Submit Payment
  </button>

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

Lorsque le formulaire ci-dessus est chargé, créez une instance d’un élément fpxBank et intégrez-la au conteneur Element précédemment créé.

const style = {
  base: {
    // Add your base input styles here. For example:
    padding: '10px 12px',
    color: '#32325d',
    fontSize: '16px',
  },
};

// Create an instance of the fpxBank Element.
const fpxBank = elements.create(
  'fpxBank',
  {
    style: style,
    accountHolderType: 'individual',
  }
);

// Add an instance of the fpxBank Element into the container with id `fpx-bank-element`.
fpxBank.mount('#fpx-bank-element');

Envoyer le paiement à Stripe
Côté client

Pour créer un paiement côté client, transmettez la clé secrète du client de l’objet PaymentIntent créé à l’étape 1.

Utilisez stripe.confirmFpxPayment pour exécuter la redirection vers la banque et effectuer le paiement. Ajoutez une URL return_url à cette fonction pour indiquer à Stripe vers quelle page rediriger l’utilisateur une fois le paiement effectué sur le site Web de sa banque ou l’application mobile.

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

form.addEventListener('submit', async function(event) {
  event.preventDefault();
  const fpxButton = document.getElementById('fpx-button');
  const clientSecret = fpxButton.dataset.secret;

  const result = await stripe.confirmFpxPayment(clientSecret, {
    payment_method: {
      fpx: fpxBank,
    },
    // Return URL where the customer should be redirected after the authorization
    return_url: `${window.location.href}`,
  });

  if (result.error) {
    // Inform the customer that there was an error.
    const errorElement = document.getElementById('error-message');
    errorElement.textContent = result.error.message;
  }
});

Lorsque votre client effectue un paiement, Stripe le redirige vers l’URL return_url et inclut les paramètres de requête d’URL suivants. La page de redirection peut utiliser ces paramètres pour récupérer l’état du PaymentIntent et ainsi afficher l’état du paiement pour le client.

Lorsque vous spécifiez une URL return_url, vous pouvez également ajouter vos propres paramètres de requête à utiliser sur la page de redirection.

Paramètre	Description
`payment_intent`	Identifiant unique du `PaymentIntent`.
`payment_intent_client_secret`	The client secret of the `PaymentIntent` object. For subscription integrations, this client_secret is also exposed on the `Invoice` object through `confirmation_secret`

Lorsque le client est redirigé vers votre site, vous pouvez utiliser le payment_intent_client_secret pour interroger le PaymentIntent et communiquer l’état de la transaction à votre client.

Tester votre intégration

Cas de réussite et d’échec d’authentification

Testez votre intégration FPX en sélectionnant une banque à l’aide de vos clés API de test et en affichant la page de redirection. Vous pouvez tester la réussite de paiement en l’authentifiant sur la page de redirection. Le PaymentIntent passera alors de l’état requires_action à succeeded.

Pour tester un échec d’authentification de l’utilisateur, sélectionnez une banque à l’aide de vos clés API de test. Puis, sur la page de redirection, cliquez sur Échec du paiement test. Votre PaymentIntent passera alors de l’état requires_action à requires_payment_method.

Cas d’erreur de confirmation

Les autres cas d’erreur que vous pouvez rencontrer sont connectés aux banques hors ligne qui traitent les erreurs pendant la confirmation. Pour déclencher ces erreurs, définissez la valeur fpx[bank] à la confirmation de l’une des valeurs de banque d’erreur de test ci-dessous. L’état PaymentIntent sera requires_confirmation. Apprenez-en davantage sur ces codes d’erreur.

Paramètre	Valeur	Code d’erreur
`fpx[bank]`	`test_offline_bank`	`offline_bank`
`fpx[bank]`	`test_processing_error`	`payment_method_processing_error_transient`

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

Stripe envoie un événement payment_intent.succeeded à l’issue du paiement. Utilisez le Dashboard, un webhook personnalisé ou une solution partenaire 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 workflow de livraison.

Plutôt que d’attendre un rappel de votre client, écoutez ces événements. En effet, côté client, l’acheteur pourrait fermer la fenêtre de son navigateur ou quitter l’application avant l’exécution du rappel. Des personnes malveillantes peuvent en profiter pour manipuler la réponse. Si vous configurez votre intégration de manière à écouter les événements asynchrones, cela vous permettra également d’accepter de nouveaux moyens de paiement plus facilement à l’avenir. Apprenez-en davantage sur les différences entre les différents moyens de paiement pris en charge.

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 ayant échoué.

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é

Applications préconfigurées

Intégrez une application partenaire pour gérer les événements métier courants, comme l’automatisation, le marketing ou les ventes.

FacultatifGérer les événements de l'élément FPX Bank

FacultatifGérer la redirection FPX manuellement

Exigences relatives au paiement et à la confirmation du paiement

Vous devez accepter les conditions requises suivantes sur votre page de paiement :

Exigence	Détail
Afficher le logo FPX.	Téléchargez le logo FPX ici.
Créez la sélection de la banque FPX dans une liste déroulante.	Les noms des banques doivent correspondre aux noms se trouvant dans le référentiel des noms de banques.
Afficher la formulation standard des Conditions d’utilisation du service FPX et l’URL.	Formulation standard : En cliquant sur le bouton Continuer, vous acceptez les Conditions générales de FPX.

Les informations suivantes doivent être affichées sur la page de confirmation du paiement que votre client renvoie après avoir finalisé son authentification bancaire.

Informations	Source d’informations
Date et heure de la transaction	`created` à partir de l’objet `Charge`.
Montant	`amount` à partir de l’objet `Charge`.
Numéro de commande du vendeur	`statement_descriptor` à partir de l’objet `Charge`.
ID de transaction FPX	`payment_method_details[fpx][transaction_id]` à partir de l’objet `Charge`.
Nom de la banque de l’acheteur	`payment_method_details[fpx][bank]` à partir de l’objet `Charge`
État de la transaction	`status` à partir de l’objet `Charge`

Vous pouvez accéder à ces informations sur le paiement en les récupérant à partir de l’événement payment_intent.succeeded.

Pour les utilisateurs de la version d’API 2022-08-01 ou une version ultérieure : ces informations relatives au paiement peuvent être extraites de l’événement payment_intent.succeeded ou sont accessibles directement depuis le PaymentIntent.

Référence bancaire

Nom de la banque	Valeur
Affin Bank	affin_bank
Alliance Bank	alliance_bank
AmBank	ambank
Bank Islam	bank_islam
Bank Muamalat	bank_muamalat
Bank Rakyat	bank_rakyat
BSN	bsn
CIMB Clicks	cimb
Hong Leong Bank	hong_leong_bank
HSBC Bank	hsbc
KFH	kfh
Maybank2E	maybank2e
Maybank2U	maybank2u
OCBC Bank	ocbc
Public Bank	public_bank
RHB Bank	rhb
Standard Chartered	standard_chartered
UOB Bank	uob

Codes d’erreur

Voici les codes d’erreur courants et les actions recommandées correspondantes :

Code d’erreur	Action recommandée
`invalid_amount`	Les transactions FPX doivent être supérieures à 2 RM et inférieures à 30 000 RM.
`invalid_bank`	La banque fournie n’est pas prise en charge par FPX. Veuillez utiliser l’une des options du référentiel des noms de banques ci-dessus.
`invalid_currency`	FPX prend uniquement en charge les transactions MYR.
`missing_parameter`	Un paramètre requis est manquant. Veuillez vérifier le `error_message` pour plus d’informations sur le paramètre qui est requis.
`offline_bank`	La banque fournie est actuellement hors ligne. Veuillez essayer une autre banque ou un type de moyen de paiement différent.
`payment_method_not_available`	Le moyen de paiement n’est pas disponible actuellement. Vous devez inviter votre client à utiliser un autre moyen de paiement pour continuer.
`payment_method_processing_error_transient`	Une erreur inattendue s’est produite, nous empêchant de confirmer le payment intent. Un nouvel essai doit être tenté.

Virements et transferts

Pour des raisons de conformité, vos fonds FPX sont virés sur un solde fpx séparé sur votre compte. Cela signifie que vous pouvez recevoir deux virements automatiques séparés en une journée, un pour vos fonds FPX et l’autre pour tous les autres fonds. Pour les plateformes Connect, vous pouvez créer un virement ou un transfert depuis votre solde fpx en indiquant fpx comme source_type :

Vous pouvez également récupérer votre solde pour afficher une répartition de vos soldes Stripe available et pending par source_type.