Payment Process¶

The Payment Process handles the entire lifecycle of a payment during the checkout flow — from initiating a payment to receiving confirmation or handling failure.

Purpose¶

The payment process ensures that customer payments are securely initiated, processed, and verified. It connects the internal order system with the external payment provider (Pay.nl) and handles the various outcomes of a payment attempt.

Core functions

:material-credit-card-plus: Initiate a payment session after order creation
:material-swap-horizontal: Redirect the customer to the payment provider
:material-check-decagram: Verify payment status via webhooks and callbacks
:material-alert-circle: Handle failed or cancelled payments gracefully

Involved Services¶

Service	Responsibility
zwerfkei-website	Customer-facing frontend that redirects to the payment provider and displays the result.
zwerfkei	Core engine that manages order status based on payment outcomes.
zwerfkei-backend	New backend that initiates payment sessions and processes payment callbacks/webhooks.

Involved Tools¶

Tool	Responsibility
Pay.nl	External payment service provider (PSP) that handles the actual payment transaction with the customer's chosen payment method.

Process Flows¶

General process flow¶

The diagram below shows the interaction between services and Pay.nl during a payment:

sequenceDiagram
    actor Customer
    participant Website as zwerfkei-website
    participant Backend as zwerfkei-backend
    participant Core as zwerfkei
    participant PayNL as Pay.nl

    Customer->>Website: Proceed to payment
    Website->>Backend: API call: initiate payment
    Backend->>Core: Create payment record for order
    Core-->>Backend: Payment record created
    Backend->>PayNL: Create payment session
    PayNL-->>Backend: Payment URL + transaction ID
    Backend-->>Website: Redirect URL
    Website-->>Customer: Redirect to Pay.nl

    Customer->>PayNL: Complete payment (iDEAL, card, etc.)
    PayNL-->>Customer: Redirect to return URL

    PayNL->>Backend: Webhook: payment status update
    Backend->>Core: Update order payment status
    Core-->>Backend: Status updated

    Customer->>Website: Return to shop
    Website->>Backend: API call: check payment status
    Backend-->>Website: Payment result
    Website-->>Customer: Show order confirmation or failure

Future architecture

In the future, this architecture can be transformed for the Brekz platform. In that case, zwerfkei-website is replaced by brekz-website and zwerfkei-backend by brekz-backend, without a dependency on the zwerfkei core service.

Payment status flow¶

The following diagram shows the possible states a payment can go through:

stateDiagram-v2
    [*] --> Initiated: Payment session created
    Initiated --> Pending: Customer redirected to Pay.nl
    Pending --> Paid: Payment successful
    Pending --> Failed: Payment failed
    Pending --> Cancelled: Customer cancelled
    Pending --> Expired: Session timed out

    Paid --> [*]
    Failed --> Initiated: Retry payment
    Cancelled --> Initiated: Retry payment
    Expired --> Initiated: Retry payment
    Failed --> [*]
    Cancelled --> [*]
    Expired --> [*]

Pay.nl¶

Pay.nl{ target="_blank" } is the external payment service provider (PSP) used by Zwerfkei to process all customer payments.

Credentials

Pay.nl API credentials and configuration details can be found in 1Password or by contacting the Zwerfkei team. Do not store credentials in the codebase.

Supported payment methods¶

Pay.nl supports a wide range of payment methods, including but not limited to:

:material-bank: iDEAL — Dutch bank payments
:material-credit-card: Credit Card — Visa, Mastercard, American Express
:material-contactless-payment: Bancontact — Belgian payment method
:material-wallet: PayPal
:material-cellphone: Apple Pay / Google Pay

Integration¶

The integration with Pay.nl is handled by zwerfkei-backend, which communicates with the Pay.nl REST API to:

Create payment sessions — Generate a unique payment URL for the customer
Receive webhooks — Process asynchronous payment status updates from Pay.nl
Verify payment status — Query the Pay.nl API when a customer returns to the shop

Useful links¶

Pay.nl Documentation{ .md-button target="_blank" }
Pay.nl Admin Portal{ .md-button target="_blank" }

Connection to other features¶

The Payment Process is closely connected to:

Cart Process — The cart is converted to an order before payment is initiated
Order Management — The payment outcome directly determines the order status