Secure Payment Callbacks / Webhooks

Core Rule

Never trust a payment callback (webhook) blindly.
A callback is just an HTTP POST from the payment provider to a URL you control. Anyone who discovers that URL can send a crafted “payment successful” payload unless you verify it.

When this skill applies

• Implementing or reviewing M-Pesa STK Push, C2B, or B2C integrations
• Handling any payment provider webhook (Stripe, Paystack, Flutterwave, etc.)
• Adding or modifying code that marks an order/payment as successful

Required Security Checks (in order)

1. Correlate with a request you initiated
   • When you start a payment, store the MerchantRequestID and/or CheckoutRequestID (or equivalent) in your database with status pending.
   • On callback, look up that exact ID. If it does not exist or is not pending → reject.