Skip to content

Payment System

The payment system handles online payment collection for invoices. It supports two payment providers — Mollie (primary) and Rabobank (betaalverzoeken) — and includes a public-facing payment page where members can view their invoice and select a payment plan without logging in.

Mollie no longer uses one global API key. Finance settings now store a list of Mollie accounts, each with:

  • internal name
  • account holder
  • IBAN
  • one encrypted API key

The key is never returned by the REST API. The UI only gets:

  • has_api_key
  • environment (live or test)

Finance settings also store three default account IDs:

  • mollie_default_membership_account_id
  • mollie_default_discipline_account_id
  • mollie_default_manual_account_id

These decide which Mollie account is snapshotted onto new invoices of each type.

Class: Rondo\Finance\MollieClient

Thin wrapper around the official Mollie PHP SDK 4 (MollieApiClient). It receives the API key explicitly so each invoice can use the correct Mollie account.

$client = new MollieClient( $apiKey );
$mollie = $client->get(); // Returns configured MollieApiClient

Class: Rondo\Finance\MolliePayment

Creates payment links (not regular payments) via POST /v2/payment-links. Payment links are persistent and don’t expire, unlike regular Mollie payments which expire in ~15 minutes. This is important because links are emailed to members.

Flow:

  1. Validate invoice exists
  2. Idempotency check — If _mollie_payment_link_id and payment_link are already stored, return existing URL
  3. Read the snapshotted invoice account and load that account’s API key
  4. Build payload with amount, description (Factuur {number}), and redirect URL
  5. Conditionally add webhookUrl — omitted on localhost and .local environments
  6. Call Mollie Payment Links API
  7. Store checkout URL in payment_link ACF field and payment link ID in _mollie_payment_link_id meta

Class: Rondo\Finance\MollieWebhook

Receives webhook POST events at POST /wp-json/rondo/v1/mollie/webhook (public endpoint, no auth required).

Always returns HTTP 200 to prevent Mollie retry storms, regardless of processing outcome.

The webhook handler supports payment-link IDs only:

PathID PrefixLookup MethodUse Case
0apl_xxx_mollie_pid_{pl_xxx} metaInstallment payment links
0bpl_xxx_mollie_payment_link_id metaDiscipline / full payment links

Security: The webhook first finds the invoice, then re-fetches the payment link from Mollie using that invoice’s snapshotted account key. It never trusts the POST body alone.

For full payments (Path 0b):

  1. Find invoice by payment link ID or payment ID
  2. Idempotency check — skip if already rondo_paid
  3. Transition post status to rondo_paid
  4. Update ACF status field to paid

For installment payments (Path 0a):

  1. Find invoice by reverse-lookup meta
  2. Mark specific installment as betaald
  3. Check if all installments are now paid → transition to rondo_paid if so
  4. If more installments remain → automatically create next installment’s Mollie payment link

When the webhook reads a paid transaction from a payment link, the Mollie SDK can return a payment method as a backed enum. The webhook stores the enum value as a string in _mollie_payment_method for a full payment or _installment_{N}_mollie_method for an installment. Method names already returned as strings pass through unchanged. Invoice details expose an absent method as null.

Class: Rondo\Finance\RabobankOAuth

Manages the OAuth 2.0 Premium authorization flow for the Rabobank Payment Request API.

Features:

  • Environment-aware URLs (sandbox vs production)
  • Authorization URL generation with CSRF state token (stored in transient, 10-minute TTL)
  • Code-to-token exchange with Basic Auth client credentials
  • Automatic token refresh (5-minute buffer before expiry)
  • Encrypted token storage via CredentialEncryption

REST Endpoints:

MethodEndpointAuthDescription
GET/rabobank/authorizemanage_optionsGet OAuth authorize URL
GET/rabobank/callbackPublic (state nonce)Handle OAuth callback, redirect to settings
GET/rabobank/statusmanage_optionsCheck connection status + environment
POST/rabobank/disconnectmanage_optionsClear stored tokens

Class: Rondo\Finance\RabobankPayment

Creates payment requests (betaalverzoeken) via the Rabobank API with full message signing.

Features:

  • mTLS client certificate injection via http_api_curl filter
  • Self-signed certificate generation for sandbox environment
  • HTTP message signing per Rabobank spec (date, digest, x-request-id)
  • QR code download from Rabobank API after payment request creation
  • Sandbox test IBAN (NL19RABO0123456790) used automatically in sandbox mode

Payment Request Flow:

  1. Get valid access token (auto-refreshes if needed)
  2. Build payload: IBAN, amount in cents, description (35-char SWIFT limit)
  3. Compute SHA-256 digest of request body
  4. Sign headers with RSA-SHA256 using mTLS private key
  5. POST to Rabobank Payment Request API with mTLS enabled
  6. Store paymentPageUrl in payment_link ACF field
  7. Download and store QR code PNG from Rabobank QR code endpoint

Class: Rondo\Finance\PublicPaymentPage

A standalone, public-facing landing page at /betaling/{token} where members can view their invoice and choose a payment plan — no WordPress login required.

Each membership invoice gets a unique 64-character hex token (32 bytes via random_bytes), stored in _payment_token post meta. The full URL is stored in the payment_link ACF field for inclusion in emails via {betaallink}.

Tokens are generated by PublicPaymentPage::generate_token(), called during bulk invoice creation.

A WordPress rewrite rule matches ^betaling/([a-f0-9]{64})$ and maps to the rondo_payment_token query var. The template_redirect handler fires at priority 0 (before the React SPA catch-all at priority 1).

Renders a standalone mobile-first HTML page (no WordPress theme, no external dependencies) showing:

  • Club branding (logo, name, accent color from FinanceConfig)
  • Invoice summary (member name, invoice number, season, total amount)
  • Payment plan options:
    • Volledig betalen — Full payment, no extra costs
    • 3 termijnen — Quarterly installments (if enabled for season and ≥3 payment dates remain)
    • N termijnen — Monthly installments, up to 8 (if enabled and >3 dates remain)

Installment amounts include a configurable admin fee per installment. Plan visibility adapts based on available payment dates (23rd of each month through April of the season’s end year).

Per-invoice override: installment plans can be disabled for specific invoices via _disable_installments meta.

  1. CSRF validation (submitted token must match URL token)
  2. Validate plan is allowed and enabled for the season
  3. Guard against already-paid invoices or duplicate submissions
  4. Clear any previous installment data (supports plan changes on return visits)
  5. Write installment meta (amounts, admin fees, due dates, statuses)
  6. Create Mollie payment for installment 1 via InstallmentPaymentService
  7. Redirect to Mollie checkout

After Mollie redirects back with ?betaald=1, a success page renders with a confirmation message and invoice summary.

Finance administrators can adjust the family-discount and entry-discount percentages on sent or overdue membership invoices. The REST endpoint recalculates the discount lines and invoice total and invalidates the existing PDF.

The normal correction flow is blocked once an installment has been paid, a payment request has been sent, or an installment payment link exists. At that point the collected amount and issued payment links must be reconciled together through a bounded administrative correction; changing only the invoice total would leave the payment plan inconsistent.

Class: Rondo\Finance\QrCodeGenerator

Generates branded QR codes using the chillerlan/php-qrcode library with GD image output.

Features:

  • Club accent color applied to all dark QR modules
  • Club logo overlay in the center (sized to 20% of QR area, with white background padding)
  • ECC Level H (30% error correction) to support logo overlay
  • 10px per module scale (~330×330px output)
  • Saved in private invoice storage
  • Relative path invoices/qr-{invoice_number}.png stored in the read-only qr_code_path field

The generator accepts any URL, including Mollie checkout links. For Rabobank, Rondo downloads the QR image from the Rabobank API into the same private storage.