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

# SDK et bibliothèques

> Les bibliothèques officielles pour appeler l'API et vérifier les webhooks, en PHP, Node.js, Python et Dart, avec Laravel, Next.js, React, Django et Flutter.

Chaque SDK couvre tous les endpoints de la [référence](https://docs.mercy-pay.com/api/account/get.md) et fait pour vous ce que la doc demande de faire à la main :

* les **nouvelles tentatives** après une coupure, un `429` ou une erreur `5xx`, avec la même `Idempotency-Key` à chaque tentative, générée si vous n'en donnez pas ;
* la **pagination** : une boucle parcourt toutes les pages ;
* des **erreurs typées** avec `code`, `param` et `request_id` ;
* la **vérification des webhooks** (`MercyPay-Signature`, tolérance de 5 minutes, plusieurs `v1` acceptés après une rotation du secret).

Le code est public, dans l'organisation [mercy-pay sur GitHub](https://github.com/mercy-pay).

## SDK serveur

```sh PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
composer require mercy-pay/mercy-pay-php
```

```sh Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install @mercy-pay/node
```

```sh Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install mercy-pay
```

```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
$mercyPay = new MercyPay\MercyPayClient(getenv('MERCY_PAY_API_KEY'));

$session = $mercyPay->checkoutSessions->create([
    'amount' => 15000,
    'currency' => 'XAF',
    'metadata' => ['order_id' => '4821'],
], ['idempotency_key' => 'order-4821']);
```

```ts Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { MercyPay } from '@mercy-pay/node';

const mercyPay = new MercyPay(process.env.MERCY_PAY_API_KEY!);

const session = await mercyPay.checkoutSessions.create(
  { amount: 15000, currency: 'XAF', metadata: { order_id: '4821' } },
  { idempotencyKey: 'order-4821' },
);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from mercypay import MercyPay

mercy_pay = MercyPay(os.environ["MERCY_PAY_API_KEY"])

session = mercy_pay.checkout_sessions.create(
    amount=15000, currency="XAF", metadata={"order_id": "4821"}, idempotency_key="order-4821"
)
```

Envoyez ensuite le client sur `session.checkout_url`.

| Langage | Paquet | Code |
| - | - | - |
| PHP 8.2 et plus | `mercy-pay/mercy-pay-php` | [mercy-pay-php](https://github.com/mercy-pay/mercy-pay-php) |
| Node.js 20 et plus, Bun, Deno, edge | `@mercy-pay/node` | [mercy-pay-node](https://github.com/mercy-pay/mercy-pay-node) |
| Python 3.10 et plus, synchrone et `async` | `mercy-pay` | [mercy-pay-python](https://github.com/mercy-pay/mercy-pay-python) |
| Dart 3.4 et plus, côté serveur | `mercy_pay` | [mercy-pay-dart](https://github.com/mercy-pay/mercy-pay-dart) |

## Vérifier un webhook

```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
$event = MercyPay\Webhook::constructEvent($rawBody, $signatureHeader, $secret);
```

```ts Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const event = await MercyPay.webhooks.constructEvent(rawBody, signatureHeader, secret);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
event = mercypay.construct_event(raw_body, signature_header, secret)
```

Une signature fausse ou trop ancienne lève une erreur : répondez `400`. Voir [Recevoir un webhook](https://docs.mercy-pay.com/developers/webhooks/handle.md).

## Par framework

| Framework | Paquet | Ce qu'il ajoute |
| - | - | - |
| Laravel 12 et 13 | [`mercy-pay/laravel`](https://github.com/mercy-pay/laravel) | Configuration par `.env`, façade `MercyPay`, route `POST /webhooks/mercy-pay` qui déclenche l'événement `WebhookReceived`. |
| Next.js (App Router) | [`@mercy-pay/next`](https://github.com/mercy-pay/next) | `createWebhookHandler()` : une route de webhooks avec un handler par type d'événement. |
| JavaScript (navigateur) | [`@mercy-pay/js`](https://github.com/mercy-pay/js) | `embedCheckout()` : le [formulaire de paiement intégré](https://docs.mercy-pay.com/payments/embedded.md) dans votre page, aussi par une simple balise `<script>`. |
| React | [`@mercy-pay/react`](https://github.com/mercy-pay/react) | `<EmbeddedCheckout>` affiche le formulaire dans votre page. `<CheckoutButton>` et `useCheckout()` ouvrent la page de paiement hébergée. |
| Django 4.2 et plus | [`mercy-pay-django`](https://github.com/mercy-pay/mercy-pay-django) | Client lu dans les settings, vue de webhooks qui envoie le signal `webhook_received`. |
| Flutter (Android, iOS) | [`mercy_pay_flutter`](https://github.com/mercy-pay/mercy-pay-flutter) | `MercyPayEmbeddedCheckout` affiche le formulaire dans votre app. `MercyPayCheckoutButton` ouvre la page de paiement dans le navigateur intégré. |
| React Native | [`@mercy-pay/react-native`](https://github.com/mercy-pay/react-native) | `<EmbeddedCheckout>` affiche le formulaire de paiement dans votre app. |

> [!WARNING]
>
> Votre clé API reste sur votre serveur. Une app React, Flutter ou mobile ne l'appelle jamais directement : elle demande à votre serveur de créer la session, puis ouvre `checkout_url`, ou affiche le [formulaire intégré](https://docs.mercy-pay.com/payments/embedded.md) avec le `client_secret` de la session.

## En local

La [ligne de commande](https://docs.mercy-pay.com/developers/cli.md) relaie les webhooks vers votre ordinateur et déclenche des événements de test, quel que soit le SDK.

## Versions

Chaque SDK suit [SemVer](https://semver.org/lang/fr/) et parle à l'API `v1`. Le journal de chaque version est dans le `CHANGELOG.md` de son dépôt, et une faille se signale à [security@mercy-pay.com](mailto:security@mercy-pay.com).

* Les SDK sont en `0.x` : une version mineure (`0.2.0`) peut encore changer une signature. Elle le dit alors dans son journal. Une version corrective (`0.1.1`) ne casse jamais rien.
* Ils passeront en `1.0.0` une fois les paramètres typés en place. Ensuite, rien de cassant sans nouvelle version majeure, comme pour l'API.
* Fixez la version mineure dans vos dépendances, par exemple `^0.1` en PHP ou `~0.1.0` en Node, et lisez le journal avant de monter.


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