Stripe must be told where to send payment event notifications. The URL must be on your Main Backend host (MAIN_BACKEND_DOMAIN — hosted: webhook.payment-gateway.app) — Hostnames & DNS conventions.
[!NOTE]
For self-hosted stacks using branded webhook domains, keep this hostname stable and under your control. Many providers expect webhook and return/callback URLs to stay on approved domains. If that hostname is behind Cloudflare proxying, review the custom-domain Cloudflare caveat in Hostnames & DNS conventions.
In Stripe Dashboard, go to Developers → Webhooks → Add endpoint.
(Hosted: https://webhook.payment-gateway.app/hooks/stripe/{providerId}.)
The {providerId} is the MongoDB ObjectId of your provider record — visible in the Admin Panel URL after you create the provider.
Set the webhook Event payload API version to 2026-03-25.dahlia or later.
The gateway tolerates signed Stripe webhooks from other API versions, but matching the backend SDK version gives the safest object deserialization.
Under Events to listen to, select only the events you need. At minimum, enable payment_intent.succeeded, payment_intent.payment_failed, charge.succeeded, charge.failed, charge.refunded, and charge.dispute.created.
Classic payment-ID callback: configure the URL for the payment. Mollie sends a payment ID, and the gateway fetches the canonical payment with the API key for the selected Test or Live mode. A signing secret is not required for this classic form-encoded callback.
Next-generation event webhook: in Developers → WebHooks, create one webhook for each Test or Live mode you use, select Snapshot payloads, and copy that webhook's signing secret. Store the secret in the provider's Webhook Signing Secret field for the same mode. The gateway verifies X-Mollie-Signature with HMAC-SHA256 before it fetches and validates the referenced records.
For a next-generation webhook, subscribe only to the event families handled by the gateway:
Use your Main Backend host (MAIN_BACKEND_DOMAIN — hosted: webhook.payment-gateway.app) — Hostnames & DNS conventions.
[!NOTE]
For self-hosted stacks using branded webhook domains, keep this hostname stable and under your control. If you proxy it through Cloudflare, review the custom-domain Cloudflare caveat in Hostnames & DNS conventions before onboarding merchant custom domains.
In GoCardless Dashboard, go to Developers → Webhooks → Create Webhook.
Unlike card payments, GoCardless uses a redirect mandate flow:
Customer clicks Pay on checkout → redirected to GoCardless mandate authorization page.
Customer authorizes the debit mandate at their bank.
GoCardless redirects back to the gateway.
The gateway creates a pending_provider transaction; payment is captured asynchronously (usually within 1–5 business days).
GoCardless sends a webhook when payment clears → transaction moves to succeeded.
[!IMPORTANT]
GoCardless payments are not instant. Design your fulfillment logic to handle pending_provider state and wait for the succeeded webhook before delivering goods/services.
Copy the PayPal Webhook ID and store it on the provider record. The gateway uses it to verify PayPal webhook signatures before processing order or payment events.
If advanced card fields are enabled, set the supported currency code.
Save.
The selected mode determines the canonical PayPal API endpoint. Do not configure or persist an apiBaseUrl override. For an older deployment, use this bounded migration:
Back up MongoDB and test restoration before the maintenance window. Inventory every affected provider by organization, provider ID, label, receipt account identity, current enabled state, explicit mode, and whether apiBaseUrl is present. Record presence only; never export endpoint values, masked or unmasked credentials, webhook IDs, configuration dumps, .env files, or customer data.
Prevent new PayPal checkout attempts during the change while keeping accepted payment and webhook records intact. In Providers → Edit, open each inventoried PayPal provider. The migration notice appears when the legacy key is present.
Confirm the provider belongs to Sandbox or Live, select that mode explicitly, leave masked Client ID and Client Secret values unchanged, and verify the immutable receiving account identity, Webhook ID, enabled state, domain assignments, and unrelated settings. Select Save Changes. This supported save removes only apiBaseUrl; repeating the save is safe.
Reopen the same provider and read it back. Confirm the migration notice is gone, the chosen mode is still shown, credentials remain masked, the receipt account identity and other settings match the inventory, and the provider remains assigned as intended. Verify the matching PayPal app and webhook are in the same Sandbox or Live environment before resuming callbacks. Use sandbox test traffic for Sandbox; do not create a live charge solely for migration verification.
Rollback the application separately from payment data. Do not restore apiBaseUrl, delete accepted events, clear operations, or restore a database snapshot over newer payment or callback records. If the wrong canonical mode was selected, return to maintenance, choose the correct mode, save again, read it back, and repeat the environment and webhook checks. Production has no custom endpoint fallback.
Wire Transfer is a manual-confirmation provider — the gateway generates payment instructions and marks transactions as paid when you manually confirm receipt.
