feat(callbacks): store the Eupago transaction on paid references

[jfrosorio]

Closes #87.

Multibanco, MB WAY, PayShop and PaysafeCard callbacks validated transacao and then discarded it, so refunding a stored reference meant capturing the transaction out of band. They now persist it the way Credit Card already does.

• A new migration adds a nullable, indexed transaction_id to mb_references, mbway_references, payshop_references and paysafecard_references. Its down() drops the index before the column, which SQLite requires when it rebuilds the table.
• The four controllers write transacao alongside state, and the four models gain transaction_id in $fillable.
• Each payment method's docs page now closes the way the Credit Card page does, and the refunds page says a paid reference carries the id. UPGRADE.md gains a v3.8.x to v3.9.0 entry covering the migration.
• The "marks as paid" test for each method asserts the stored transaction.

Purely additive, so it ships as a minor. References paid before the upgrade keep a null transaction_id — the value only ever exists in the callback payload, so there is nothing to backfill from.

[Copilot]

🟢 Approval recommended

The changes are consistent across methods, are covered by updated feature tests, and the migration/upgrade documentation matches the new behavior.

Pull request overview

This PR aligns Multibanco, MB WAY, PayShop, and PaysafeCard paid-reference handling with Credit Card by persisting the Eupago callback transacao value onto the reference as transaction_id, enabling refunds to be performed directly from stored references.

Changes:

• Adds a migration that introduces a nullable, indexed transaction_id column to the four non–Credit Card reference tables.
• Updates each payment callback controller to persist transaction_id when marking a reference as paid, and updates the corresponding models’ $fillable.
• Updates method/refund documentation and adds/extends feature tests to assert transaction_id persistence.

File summaries

File	Description
UPGRADE.md	Documents the v3.8.x → v3.9.0 upgrade step and required migration publish/run.
database/migrations/2026_09_17_000000_add_transaction_id_to_reference_tables.php	Adds nullable indexed transaction_id to reference tables and drops index before column on rollback.
src/Http/Controllers/MBController.php	Persists transaction_id from validated callback payload when marking MB references paid.
src/Http/Controllers/MBWayController.php	Persists transaction_id from validated callback payload when marking MB WAY references paid.
src/Http/Controllers/PayShopController.php	Persists transaction_id from validated callback payload when marking PayShop references paid.
src/Http/Controllers/PaysafeCardController.php	Persists transaction_id from validated callback payload when marking PaysafeCard references paid.
src/Models/MbReference.php	Allows mass-assignment of transaction_id.
src/Models/MbwayReference.php	Allows mass-assignment of transaction_id.
src/Models/PayShopReference.php	Allows mass-assignment of transaction_id.
src/Models/PaysafeCardReference.php	Allows mass-assignment of transaction_id.
docs/refunds.md	Clarifies the transaction id is stored on paid references as transaction_id.
docs/multibanco.md	Notes the callback stores the Eupago transaction on the reference for refunds.
docs/mbway.md	Notes the callback stores the Eupago transaction on the reference for refunds.
docs/payshop.md	Notes the callback stores the Eupago transaction on the reference for refunds.
docs/paysafecard.md	Notes the callback stores the Eupago transaction on the reference for refunds.
tests/Feature/MbCallbackTest.php	Asserts the callback persists transaction_id when marking MB references paid.
tests/Feature/MbwayCallbackTest.php	Asserts the callback persists transaction_id when marking MB WAY references paid.
tests/Feature/PayShopCallbackTest.php	Asserts the callback persists transaction_id when marking PayShop references paid.
tests/Feature/PaysafeCardCallbackTest.php	Asserts the callback persists transaction_id when marking PaysafeCard references paid.

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.