Skip to content

ADR-0005 — Payment Provider: PayNL
Status Accepted
Date 2025
Deciders Flooris development team / Zwerfkei management

Context

The Zwerfkei e-commerce platform must support online payment processing. A payment service provider (PSP) is required to handle payment method selection, transaction processing, status callbacks and refund support.

Decision

PayNL is adopted as the payment service provider for the Zwerfkei platform.

Rationale

  • PayNL is already the payment provider used within the existing Zwerfkei infrastructure.
  • PayNL supports all major Dutch and European payment methods (iDEAL, credit card, Bancontact, etc.).
  • The PayNL API provides webhook-based payment status updates, enabling reliable asynchronous order confirmation.
  • An existing integration and merchant account are in place, reducing migration overhead.

Supported Payment Methods

Method Region
iDEAL Netherlands
Credit card (Visa / Mastercard) International
Bancontact Belgium
PayPal International
Klarna / Afterpay Netherlands / Belgium
Gift card (Givacard) Netherlands

Note

Supported payment methods are configurable per PayNL account and may be extended or restricted based on business requirements.

Gift Card Support

Zwerfkei supports gift cards via Givacard.nl. Gift card validation and redemption is handled through Pay.NL.

If the gift card does not cover the full order amount, the customer pays the remaining balance using any other supported payment method (e.g. iDEAL, credit card).

Integration Pattern

  1. At checkout, the Zwerfkei Backend creates a PayNL transaction and redirects the customer to the PayNL payment page.
  2. After payment, PayNL redirects the customer back to the platform and sends a webhook to the Zwerfkei Backend.
  3. The webhook updates the OrderTransaction status and triggers the OrderConfirmed event on successful payment.

Consequences

  • The Zwerfkei Backend must implement a PayNL API client and a secure webhook endpoint.
  • Webhook endpoints must validate the PayNL signature to prevent fraudulent callbacks.
  • Refunds can be initiated via the PayNL dashboard or API, with the status reflected in OrderTransaction.