<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.-
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. -
Chez votre hébergeur de domaine, créez l’enregistrement TXT affiché, par exemple :
- Cliquez sur Vérifier maintenant. Sinon, la vérification a lieu toute seule chaque heure. Une modification DNS peut mettre quelques heures à être visible.
POST /api/v1/embed_domains, puis POST /api/v1/embed_domains/{id}/verify.
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, avecui_mode: "embedded". Votre clé API reste sur votre serveur.
client_secret :
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.@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 avecpostMessage. Chacun porte source: "mercy-pay", version: 1 et un type :
event.origin, puis ne vous fiez qu’à source et type : ignorez tout autre message.
5. Confirmez sur votre serveur
Le messagepayment_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 :bridge :
bridge=flutter: les messages arrivent dans un canal JavaScript nomméMercyPayBridge;bridge=react-native: ils arrivent dansonMessagede la WebView.
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.
mercypay listen --forward-to localhost:8000/webhooks/mercy-pay.