Skip to main content
Votre client paie sans quitter votre page : le formulaire Mercy Pay s’affiche dans votre interface, avec le mobile money, la carte bancaire, la 3D Secure, et Apple Pay et Google Pay quand l’appareil les propose. Vous n’installez aucune librairie de paiement, et les données de carte ne passent jamais par votre serveur. Le formulaire est une page servie par Mercy Pay, que vous affichez dans un <iframe>. Tout reste faisable en HTTP pur : une session créée par l’API, puis une balise HTML.
Préférez la page hébergée si vous voulez la mise en place la plus courte : votre client part payer sur Mercy Pay, puis revient sur votre site.

1. Autorisez votre site

Le formulaire ne s’affiche que sur les sites que vous avez déclarés et vérifiés. Ailleurs, le navigateur refuse de le montrer.
  1. Dans Paramètres > Paiements, section Sites autorisés pour le paiement intégré, ajoutez votre domaine, par exemple boutique.com. Il couvre aussi ses sous-domaines.
  2. Chez votre hébergeur de domaine, créez l’enregistrement TXT affiché, par exemple :
  3. Cliquez sur Vérifier maintenant. Sinon, la vérification a lieu toute seule chaque heure. Une modification DNS peut mettre quelques heures à être visible.
Vous pouvez aussi passer par l’API : POST /api/v1/embed_domains, puis POST /api/v1/embed_domains/{id}/verify.
En sandbox, localhost, 127.0.0.1 et les domaines .test et .localhost marchent tout de suite, sans rien déclarer.
Une fois le site vérifié, Mercy Pay l’enregistre pour Apple Pay et Google Pay, sur le domaine et son www. Ils s’affichent dès que l’enregistrement est validé, en général en quelques minutes : la ligne du site l’indique dans Sites autorisés. Les moyens qui font quitter la page pour payer ailleurs, comme Amazon Pay ou Klarna, ne sont proposés que sur la page hébergée : dans le formulaire intégré, votre client reste toujours chez vous.

2. Créez une session intégrée, côté serveur

Créez une session de paiement comme d’habitude, avec ui_mode: "embedded". Votre clé API reste sur votre serveur.
La réponse contient un client_secret :
Transmettez ce client_secret à votre page. Il ouvre le formulaire de cette session et rien d’autre : il ne remplace pas votre clé API.

3. Affichez le formulaire

Une balise suffit :
allow="payment" est nécessaire pour qu’Apple Pay et Google Pay s’affichent dans l’iframe.

Avec nos paquets

Ils créent l’iframe, suivent sa hauteur et vous donnent les événements, sans rien changer au reste. Facultatifs : la balise ci-dessus suffit.
Avec Next.js, la session se crée dans une action serveur : voir @mercy-pay/next.

Apparence

Le formulaire reprend votre Image de marque : couleur, police et arrondis. Vous pouvez l’ajuster dans l’adresse :

4. Suivez le paiement dans votre page

Le formulaire envoie des messages à votre page avec postMessage. Chacun porte source: "mercy-pay", version: 1 et un type :
Vérifiez toujours event.origin, puis ne vous fiez qu’à source et type : ignorez tout autre message.

5. Confirmez sur votre serveur

Le message payment_succeeded sert à mettre à jour votre page. Il ne prouve rien : n’importe quel script de la page pourrait en envoyer un faux. Confirmez la commande quand votre serveur reçoit le webhook payment.succeeded, ou en relisant la session avec GET /api/v1/checkout_sessions/{id}.

Dans une app mobile

Le même formulaire s’affiche dans une vue web, en plein écran. Nos paquets s’en chargent :
Sans paquet, ouvrez l’adresse du formulaire dans votre vue web avec bridge :
  • bridge=flutter : les messages arrivent dans un canal JavaScript nommé MercyPayBridge ;
  • bridge=react-native : ils arrivent dans onMessage de la WebView.
Les messages ont le même format, en texte JSON. Dans une vue web, Apple Pay et Google Pay ne s’affichent pas : le client paie par mobile money ou par carte.

Tester en sandbox

Avec une clé mp_sandbox_…, le formulaire affiche les numéros et cartes de test :
  • mobile money : un bouton par résultat (réussi, refusé, solde insuffisant…) remplit le bon numéro ;
  • carte : 4242 4242 4242 4242, 12/34, 123 ;
  • 3D Secure : 4000 0025 0000 3155, puis validez la fenêtre de test.
Depuis votre ordinateur, la ligne de commande relaie les webhooks vers votre serveur local : mercypay listen --forward-to localhost:8000/webhooks/mercy-pay.