Payment System
Overview
Section titled “Overview”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 Integration
Section titled “Mollie Integration”Mollie Accounts in Finance Settings
Section titled “Mollie Accounts in Finance Settings”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_keyenvironment(liveortest)
Finance settings also store three default account IDs:
mollie_default_membership_account_idmollie_default_discipline_account_idmollie_default_manual_account_id
These decide which Mollie account is snapshotted onto new invoices of each type.
MollieClient
Section titled “MollieClient”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 MollieApiClientMolliePayment
Section titled “MolliePayment”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:
- Validate invoice exists
- Idempotency check — If
_mollie_payment_link_idandpayment_linkare already stored, return existing URL - Read the snapshotted invoice account and load that account’s API key
- Build payload with amount, description (
Factuur {number}), and redirect URL - Conditionally add
webhookUrl— omitted onlocalhostand.localenvironments - Call Mollie Payment Links API
- Store checkout URL in
payment_linkACF field and payment link ID in_mollie_payment_link_idmeta
MollieWebhook
Section titled “MollieWebhook”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.
Lookup Paths
Section titled “Lookup Paths”The webhook handler supports payment-link IDs only:
| Path | ID Prefix | Lookup Method | Use Case |
|---|---|---|---|
| 0a | pl_xxx | _mollie_pid_{pl_xxx} meta | Installment payment links |
| 0b | pl_xxx | _mollie_payment_link_id meta | Discipline / 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.
Payment Confirmation Flow
Section titled “Payment Confirmation Flow”For full payments (Path 0b):
- Find invoice by payment link ID or payment ID
- Idempotency check — skip if already
rondo_paid - Transition post status to
rondo_paid - Update ACF
statusfield topaid
For installment payments (Path 0a):
- Find invoice by reverse-lookup meta
- Mark specific installment as
betaald - Check if all installments are now paid → transition to
rondo_paidif so - 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.
Rabobank Integration
Section titled “Rabobank Integration”RabobankOAuth
Section titled “RabobankOAuth”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:
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /rabobank/authorize | manage_options | Get OAuth authorize URL |
| GET | /rabobank/callback | Public (state nonce) | Handle OAuth callback, redirect to settings |
| GET | /rabobank/status | manage_options | Check connection status + environment |
| POST | /rabobank/disconnect | manage_options | Clear stored tokens |
RabobankPayment
Section titled “RabobankPayment”Class: Rondo\Finance\RabobankPayment
Creates payment requests (betaalverzoeken) via the Rabobank API with full message signing.
Features:
- mTLS client certificate injection via
http_api_curlfilter - 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:
- Get valid access token (auto-refreshes if needed)
- Build payload: IBAN, amount in cents, description (35-char SWIFT limit)
- Compute SHA-256 digest of request body
- Sign headers with RSA-SHA256 using mTLS private key
- POST to Rabobank Payment Request API with mTLS enabled
- Store
paymentPageUrlinpayment_linkACF field - Download and store QR code PNG from Rabobank QR code endpoint
Public Payment Page
Section titled “Public Payment Page”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.
Token System
Section titled “Token System”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.
URL Routing
Section titled “URL Routing”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).
GET — Plan Selection Page
Section titled “GET — Plan Selection Page”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.
POST — Plan Selection Handler
Section titled “POST — Plan Selection Handler”- CSRF validation (submitted token must match URL token)
- Validate plan is allowed and enabled for the season
- Guard against already-paid invoices or duplicate submissions
- Clear any previous installment data (supports plan changes on return visits)
- Write installment meta (amounts, admin fees, due dates, statuses)
- Create Mollie payment for installment 1 via
InstallmentPaymentService - Redirect to Mollie checkout
Success Page
Section titled “Success Page”After Mollie redirects back with ?betaald=1, a success page renders with a confirmation message and invoice summary.
Correcting membership discounts
Section titled “Correcting membership discounts”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.
QR Code Generation
Section titled “QR Code Generation”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}.pngstored in the read-onlyqr_code_pathfield
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.
Related Documentation
Section titled “Related Documentation”- Invoicing — Invoice lifecycle and email sending
- Installments — Installment payment plans
- Membership Fees — Fee calculation