> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercy-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paiement intégré

> Affichez le formulaire de paiement Mercy Pay, mobile money et carte, directement dans votre site ou votre app.

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.

> [!NOTE]
>
> Préférez la [page hébergée](https://docs.mercy-pay.com/payments/accept-a-payment.md) 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 :

   | Type | Nom | Valeur |
   | - | - | - |
   | TXT | `_mercy-pay.boutique.com` | `mercy-pay-verification=…` |

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`](https://docs.mercy-pay.com/api/embed-domains/create), puis [`POST /api/v1/embed_domains/{id}/verify`](https://docs.mercy-pay.com/api/embed-domains/verify).

> [!TIP]
>
> 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](https://docs.mercy-pay.com/payments/accept-a-payment.md) : 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](https://docs.mercy-pay.com/payments/checkout-sessions.md) comme d'habitude, avec `ui_mode: "embedded"`. Votre clé API reste sur votre serveur.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://mercy-pay.com/api/v1/checkout_sessions \
  -H "Authorization: Bearer $MERCY_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821" \
  -d '{
    "amount": 15000,
    "currency": "XAF",
    "description": "Commande 4821",
    "ui_mode": "embedded",
    "metadata": { "order_id": "4821" }
  }'
```

La réponse contient un `client_secret` :

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "id": "cs_01JCF8Q2W7Y3V9B5N1K4M6P8R0",
    "object": "checkout_session",
    "status": "created",
    "ui_mode": "embedded",
    "client_secret": "cs_01JCF8Q2W7Y3V9B5N1K4M6P8R0_secret_3fK9…",
    "amount": 15000,
    "currency": "XAF"
  }
}
```

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 :

```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
<iframe
  id="mercy-pay"
  src="https://mercy-pay.com/integre/v1/paiement?client_secret=CS_CLIENT_SECRET"
  allow="payment"
  style="width: 100%; border: 0; min-height: 520px"
  title="Paiement"
></iframe>
```

`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.

```html Script theme={"theme":{"light":"github-light","dark":"github-dark"}}
<div id="paiement"></div>
<script src="https://cdn.jsdelivr.net/npm/@mercy-pay/js@0.1/dist/mercy-pay.js"></script>
<script>
  MercyPay.embedCheckout({
    clientSecret: 'CS_CLIENT_SECRET',
    onSuccess: () => (window.location.href = '/commande/4821/merci'),
  }).mount('#paiement');
</script>
```

```js JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// npm install @mercy-pay/js
import { embedCheckout } from '@mercy-pay/js';

embedCheckout({
  clientSecret,
  onSuccess: () => (window.location.href = '/commande/4821/merci'),
}).mount('#paiement');
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark"}}
// npm install @mercy-pay/react
import { EmbeddedCheckout } from '@mercy-pay/react';

<EmbeddedCheckout
  clientSecret={clientSecret}
  onSuccess={() => router.push('/commande/4821/merci')}
/>
```

Avec Next.js, la session se crée dans une action serveur : voir [`@mercy-pay/next`](https://github.com/mercy-pay/next#afficher-le-formulaire-dans-votre-page).

### Apparence

Le formulaire reprend votre [Image de marque](https://docs.mercy-pay.com/payments/checkout-page.md) : couleur, police et arrondis. Vous pouvez l'ajuster dans l'adresse :

| Paramètre | Valeurs | Effet |
| - | - | - |
| `theme` | `light`, `dark` | Force le thème clair ou sombre. Sans lui, il suit l'appareil de votre client. |
| `color` | `1a7f37` | La couleur principale, en hexadécimal, sans `#`. |
| `radius` | `0` à `24` | L'arrondi des champs et des boutons, en pixels. |

```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
<iframe src="https://mercy-pay.com/integre/v1/paiement?client_secret=CS_CLIENT_SECRET&theme=dark&radius=12" allow="payment"></iframe>
```

## 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` :

| `type` | Quand | Données |
| - | - | - |
| `ready` | Le formulaire est affiché. | `checkout_session` |
| `resize` | Sa hauteur change : ajustez celle de l'iframe. | `height`, en pixels |
| `processing` | Le paiement est lancé : le client valide sur son téléphone ou auprès de sa banque. | `checkout_session`, `payment` |
| `payment_succeeded` | Le paiement a réussi. | `checkout_session`, `payment` |
| `payment_failed` | Le paiement a échoué. Le client peut réessayer dans le formulaire. | `checkout_session`, `payment`, `message` |
| `expired` | La session a expiré. | `checkout_session` |
| `error` | Le formulaire ne peut pas s'ouvrir : secret invalide, ou session introuvable. Créez une nouvelle session. | `code` : `session_unavailable` |

```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
<script>
  const frame = document.getElementById('mercy-pay');

  window.addEventListener('message', (event) => {
    if (event.origin !== 'https://mercy-pay.com' || event.data?.source !== 'mercy-pay') return;

    switch (event.data.type) {
      case 'resize':
        frame.style.height = event.data.height + 'px';
        break;
      case 'payment_succeeded':
        window.location.href = '/commande/4821/merci';
        break;
    }
  });
</script>
```

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`](https://docs.mercy-pay.com/developers/webhooks/events), ou en relisant la session avec [`GET /api/v1/checkout_sessions/{id}`](https://docs.mercy-pay.com/api/checkout-sessions/get).

## Dans une app mobile

Le même formulaire s'affiche dans une vue web, en plein écran. Nos paquets s'en chargent :

```dart Flutter theme={"theme":{"light":"github-light","dark":"github-dark"}}
// flutter pub add mercy_pay_flutter
import 'package:mercy_pay_flutter/mercy_pay_flutter.dart';

MercyPayEmbeddedCheckout(
  clientSecret: clientSecret,
  onSuccess: (event) => Navigator.of(context).pop(true),
)
```

```tsx React Native theme={"theme":{"light":"github-light","dark":"github-dark"}}
// npm install @mercy-pay/react-native react-native-webview
import { EmbeddedCheckout } from '@mercy-pay/react-native';

<EmbeddedCheckout
  style={{ flex: 1 }}
  clientSecret={clientSecret}
  onSuccess={() => navigation.navigate('Merci')}
/>
```

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](https://docs.mercy-pay.com/start/environments.md) :

* 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](https://docs.mercy-pay.com/developers/cli.md) relaie les webhooks vers votre serveur local : `mercypay listen --forward-to localhost:8000/webhooks/mercy-pay`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.