Essentials
Webhook
Stay in sync with real-time payment updates. Webhooks notify your application instantly when payment statuses change, eliminating the need to constantly poll our API.
What are Webhooks?
Webhooks are HTTP POST requests that bnplx.io sends to your application when payment events occur. Instead of checking payment status repeatedly, you’ll receive immediate notifications about status changes. Benefits- Real-time updates - Know instantly when payments are approved, captured, or refunded
- Reliable delivery - Automatic retries ensure you don’t miss critical events
- Reduced API calls - No need to poll for status updates
- Better user experience - Update your UI immediately when events happen
- Webhook endpoints must use HTTPS
- Never expose webhook secrets in client-side code
- Store webhook secrets securely in environment variables
| Environment | Webhook Endpoint |
|---|---|
| sandbox | https://api.staging.bnplx.io/webhooks/{merchant_id}/{merchant_connector_id} |
| Production | https://api.bnplx.io/webhooks/{merchant_id}/{merchant_connector_id} |
Webhook Handling
Below are list of events for which you will receive the webhooks:| Event | Description |
|---|---|
payment_succeeded | Payment completed successfully and funds have been processed |
payment_failed | Payment processing failed due to provider rejection or technical error |
payment_processing | Payment is currently being processed by the BNPL provider |
payment_cancelled | Payment was cancelled before completion (by customer or system) |
payment_authorized | Payment approved by provider but not yet captured |
payment_captured | Authorized payment funds have been captured and settled |
action_required | Customer action needed to complete payment (authentication, verification) |
refund_succeeded | Refund processed successfully and funds returned to customer |
refund_failed | Refund processing failed and funds could not be returned to customer |
Troubleshooting
Webhook Not Received- Check your endpoint URL is correct and accessible
- Verify HTTPS is properly configured
- Ensure your server returns HTTP 200 status
Next Steps
With webhooks configured, you can:- Build real-time features using instant payment updates
- Automate business processes triggered by payment events
- Improve customer experience with immediate feedback
- Integrate with third-party services using webhook data