Looking to hire Laravel developers? Try LaraJobs

laravel maintained by mercy-pay

Description
Mercy Pay pour Laravel : configuration, façade et réception des webhooks signés.
Last update
2026/11/16 23:42 (dev-main)
License
Downloads
0

Comments
comments powered by Disqus

Mercy Pay pour Laravel

Mercy Pay dans une app Laravel 12 ou 13 : la configuration, une façade, et une route qui reçoit les webhooks, vérifie leur signature et les transforme en événements Laravel.

composer require mercy-pay/laravel

Dans .env :

MERCY_PAY_API_KEY=mp_sandbox_...
MERCY_PAY_WEBHOOK_SECRET=whsec_...

Encaisser un paiement

use MercyPay\Laravel\Facades\MercyPay;

$session = MercyPay::checkoutSessions()->create([
    'amount' => 15000,
    'currency' => 'XAF',
    'description' => "Commande {$order->id}",
    'success_url' => route('orders.show', $order),
    'metadata' => ['order_id' => (string) $order->id],
], ['idempotency_key' => "order-{$order->id}"]);

return redirect()->away($session->checkout_url);

Vous pouvez aussi injecter MercyPay\MercyPayClient : $mercyPay->payments->retrieve($id). Toutes les méthodes sont décrites dans mercy-pay/mercy-pay-php.

Recevoir les webhooks

Le paquet déclare POST /webhooks/mercy-pay. Donnez cette adresse à votre endpoint dans Développeurs > Webhooks. Chaque webhook dont la signature est bonne déclenche MercyPay\Laravel\Events\WebhookReceived ; les autres reçoivent un 400.

use Illuminate\Support\Facades\Event;
use MercyPay\Laravel\Events\WebhookReceived;

Event::listen(function (WebhookReceived $webhook) {
    match ($webhook->type) {
        'payment.succeeded' => Order::find($webhook->data()->metadata['order_id'])?->markAsPaid(),
        'payout.failed' => Notification::send(...),
        default => null,
    };
});
  • Un même événement peut arriver deux fois : servez-vous de $webhook->id pour ne le traiter qu'une fois.
  • La route répond 200 tout de suite. Mettez un travail long dans un listener en file d'attente (ShouldQueue).
  • La route n'a pas le middleware web : pas de jeton CSRF à exclure.

Pour une autre adresse, MERCY_PAY_WEBHOOK_PATH=paiements/webhook. Pour déclarer la route vous-même, mettez null dans la config et ajoutez le middleware MercyPay\Laravel\Http\Middleware\VerifyWebhookSignature.

En local

mercypay listen --forward-to localhost:8000/webhooks/mercy-pay
mercypay trigger payment.succeeded

La CLI affiche son secret de signature au démarrage : mettez-le dans MERCY_PAY_WEBHOOK_SECRET en local.

Configuration

php artisan vendor:publish --tag=mercy-pay-config

config/mercy-pay.php règle aussi le délai d'attente, le nombre de nouvelles tentatives et la tolérance de signature.