mercy-pay / laravel
Mercy Pay pour Laravel : configuration, façade et réception des webhooks signés.
Requires
- php: ^8.2
- illuminate/contracts: ^12.0|^13.0
- illuminate/http: ^12.0|^13.0
- illuminate/routing: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
- mercy-pay/mercy-pay-php: ^0.1
Requires (Dev)
- orchestra/testbench: ^10.0|^11.0
- phpunit/phpunit: ^11.0|^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
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->idpour ne le traiter qu'une fois. - La route répond
200tout 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.