European payment integrations

Adyen, Mollie & GoCardless Integration

European payment integrations (Adyen, Mollie, GoCardless) frequently process asynchronous bank-to-bank and local payment methods (SEPA Direct Debit, Bacs, iDEAL, Bancontact, Sofort/Klarna) where final settlement takes minutes to several business days and can still fail or reverse after initial authorization.

1. Asynchronous Payment State Discipline

Never treat redirect return or mandate submission as final settlement for delayed methods:

• Synchronous redirect methods (iDEAL, Bancontact, 3DS cards): usually resolve quickly, but browser drop-offs are common — always fulfill from the server webhook (AUTHORISATION, Mollie status paid) combined with server status check.
• Delayed bank debit methods (SEPA Direct Debit, Bacs, ACH):
  • Transition through pending / submitted -> paid / settled (several days later), and can fail or be charged back weeks later (failed, charged_back) due to insufficient funds, closed accounts or unconditional SEPA 8-week customer refund rights.
  • Decide explicitly per product risk profile whether to grant provisional access on pending_submission (revocable if debit fails) or wait for settlement on high-fraud-risk goods.

2. Provider-Specific Protocols

Adyen (/payments, /sessions, Notification Webhooks)

• Inspect resultCode on /payments or /payments/details: Authorised, Pending, Received, RedirectShopper, IdentifyShopper, ChallengeShopper, Refused, Cancelled.
• HMAC Webhook Verification: verify the hmacSignature inside additionalData (or header) using your hex-decoded HMAC key before processing AUTHORISATION (success: "true" vs. "false"), CAPTURE, CAPTURE_FAILED, REFUND and CHARGEBACK events.
• Acknowledge webhooks promptly ([accepted] or 2xx per configured Adyen webhook version) after persisting the event (pspReference + eventCode).

Mollie (Payments, Customers, Mandates & Subscriptions)

• Webhook by ID (Pull Pattern): similar to Barion, Mollie webhooks send only id=tr_... (or sub_...) in the POST body.
• Your webhook handler must fetch the current resource (GET /v2/payments/tr_...) from the Mollie API using your API key to verify its authentic status (open, pending, authorized, paid, canceled, expired, failed).
• For recurring billing, create a first payment with sequenceType: "first" to establish a valid customer Mandate (status: "valid" or "pending"), then charge recurring payments with sequenceType: "recurring".

GoCardless (Direct Debit Mandates, Payments & Billing Requests)

• Use Billing Requests (billing_requests + billing_request_flows) to collect bank account details and Direct Debit Mandates (with Open Banking Instant Bank Pay where supported).
• Track mandates (pending_submission -> submitted -> active -> failed | cancelled | expired) separately from payments (pending_submission -> submitted -> confirmed -> paid_out | failed | charged_back).
• Verify Webhook-Signature (HMAC-SHA256 of raw body using webhook secret) and deduplicate by events[].id.