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

Use HTTPS

• Webhook endpoints must use HTTPS
• Never expose webhook secrets in client-side code
• Store webhook secrets securely in environment variables

GreenBanana Group’s webhook endpoint format is as specified below, or you can obtain the endpoint from the control center under the Processors tab.

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

Ready to go live?