Trace webhook failures from payment event to PHP endpoint
A practical fault-isolation path for signed callbacks, queue retries and PHP servers—without assuming every gateway exposes the same controls.
A step-by-step guide to executing headless checkouts and verifying HMAC webhooks using Laravel and OwnPay's Merchant API.
Building an e-commerce platform or custom subscription service often forces a hard choice. Developers either bolt third-party payment SDKs directly into their core application codebase or hand the entire checkout experience over to expensive hosted SaaS platforms. Both approaches introduce risk. Direct SDK integration litters core repositories with vendor-specific dependencies and compliance burdens. Hosted SaaS pages lock transaction data behind monthly subscriptions and cut into margins.
A headless setup using self-hosted infrastructure solves this friction. By running an AGPL-licensed engine like OwnPay on an isolated PHP server, you separate order orchestration from payment handling. Your main application—whether built on Laravel, Symfony, or custom PHP—handles carts and user profiles. The payment gateway engine handles balance ledgers, processor communication, and transaction states. Evaluating this architecture requires an honest look at comparing payment stacks across SaaS, custom code, and self-hosted deployments.
The integration begins inside your primary PHP application when a customer clicks proceed to checkout. Instead of loading gateway JavaScript bundles directly into your frontend, your application server initiates an authenticated HTTP request to the self-hosted OwnPay REST API.
The Merchant API accepts transaction metadata, including order identifiers, line item totals, and currency codes. Because OwnPay utilizes double-entry bookkeeping at the engine level, every payload creates balanced ledger entries isolating merchant revenue from customer receivables. Your Laravel application dispatches a POST request to your payment endpoint using an HTTP client.
The REST request passes authorization headers along with parameters such as the transaction amount in cents, currency code, order reference, and return URL. The API responds with a structured payment object containing the payment token and checkout URL. If your installation runs a multi-brand configuration, the API resolves the brand context directly from the host request domain or submitted credentials.
Once your Laravel application receives the payment object, redirect the customer to the generated checkout URL or embed the checkout flow. Because OwnPay provides complete white-label checkout capabilities, the payment URL reflects your custom domain and branding.
Customers complete their transaction using whichever payment plugin is active on your instance—ranging from standard credit card gateways like Stripe or Braintree to regional processors like SSLCommerz, Nagad, or bKash. The core Laravel application remains completely agnostic to the underlying gateway. If you swap payment processors in the dashboard later, your core application code never changes.
Synchronous HTTP redirects are inherently untrusted. A user might close their browser window immediately after payment approval, preventing your return URL from executing properly. Robust headless checkouts rely entirely on asynchronous webhooks for state settlement.
When a transaction settles, OwnPay emits an HMAC-signed webhook event to your designated endpoint. Your Laravel application must capture this payload, compute an HMAC SHA-256 hash using your shared webhook secret, and compare the result against the incoming signature header using a hash-equals comparison. Once verified, the application decodes the JSON payload, checks for the payment completion event, and updates the local order status in the database.
Verifying the cryptographic signature protects your system against forged payment completion signals. For developers extending the payment engine itself, review how to write custom post-payment hooks in OwnPay to trigger internal notifications or run custom server-side scripts before webhooks leave the gateway.
Deploying a headless payment integration is not without operational commitments. While eliminating platform transaction fees saves substantial capital at scale, self-hosting requires active infrastructure management.
For teams seeking full data sovereignty and white-label isolation, coupling Laravel with a dedicated self-hosted payment engine offers an enterprise-grade payment pipeline without vendor lock-in.
A practical fault-isolation path for signed callbacks, queue retries and PHP servers—without assuming every gateway exposes the same controls.
A practical sequence for mapping a checkout domain, setting up TLS, and applying merchant branding without assuming controls your installation may not expose.
No verified release or pricing change is in the record; the useful signal is how builders can evaluate API-first checkout and gateway extensions.