feat: add payment reconciliation cron job

[feelautom]

Problem

Stancer does not support webhooks. When a customer completes payment on the Stancer hosted page, the validation.php controller handles the return and creates the PrestaShop order. However, if the redirect never happens (browser closed, network error, session expired), the local payment stays pending indefinitely — no order is ever created, even though the payment was captured by Stancer.

This affects all shops running in redirect mode and results in captured payments with no corresponding order on the merchant side.

Solution

Add a reconciliation cron job that polls the Stancer API every 15 minutes for pending payments older than 15 minutes and creates the PrestaShop order when the payment has been captured.

Implementation

New file: controllers/front/cron.php

Class StancerCronModuleFrontController accessible at:

https://example.com/module/stancer/cron?token=STANCER_CRON_TOKEN

Recommended crontab:

*/15 * * * * curl -s "https://example.com/module/stancer/cron?token=TOKEN" > /dev/null

Logic:

• Queries ps_stancer_payment for rows with status = pending, no id_order, and date_add older than 15 minutes (threshold allows in-progress redirect flows to complete first)
• For each payment, fetches the real status from the Stancer API
• to_capture or captured → calls module->validateOrder() to create the PS order, saves id_order on the local record, logs success
• refused, failed, canceled, expired → logs a warning, marks the payment as processed (no order will be created)
• capture, capture_sent and other intermediate statuses → skipped until next run (these do not reliably map to a valid PS order state via getOrderState())
• Returns a JSON response: { processed, reconciled, skipped, errors }
• Endpoint secured with hash_equals() token comparison

Modified: stancer.php

• getConfigurationsList(): adds STANCER_CRON_TOKEN (generated once on install via random_bytes(16), stored as a hidden configuration key)
• $hooks: adds actionCronJob for compatibility with the PrestaShop CronJobs module (ps_cronjobs)
• hookActionCronJob(): implements the same reconciliation logic for shops using ps_cronjobs as an alternative to a server cron job

Notes

• The 15-minute threshold prevents interference with in-progress redirect flows
• StancerApiPayment::getOrderState() is reused as-is — only to_capture and captured are handled as they reliably map to PS_OS_PAYMENT
• The STANCER_CRON_TOKEN is generated on install and never exposed in the admin UI — merchants retrieve it from the PS configuration table or via a future admin setting
• All errors are logged to PrestaShop's logger under the StancerCronModuleFrontController object type
• Status normalization handles both enum returns (PHP 8.1+ SDK) and plain string returns for forward compatibility