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

UPGRADE.md

@@ -1,5 +1,21 @@
 # Upgrading
 
+## From v3.8.x to v3.9.0
+
+Multibanco, MB WAY, PayShop and PaysafeCard references now store the Eupago transaction their callback delivers, so a paid reference can be refunded through `$reference->transaction_id`. A new migration adds the column. Re-publish the migrations, which leaves the existing files untouched:
+
+```bash
+php artisan vendor:publish --provider=CodeTech\\EuPago\\Providers\\EuPagoServiceProvider --tag=migrations
+```
+
+Run the new migration:
+
+```bash
+php artisan migrate
+```
+
+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.
+
 ## From v3.7.x to v3.8.0
 
 This release adds Credit Card support, which uses a new `credit_card_references` table. Re-publish the migrations (existing files are left untouched) and run the new one:

database/migrations/2026_09_17_000000_add_transaction_id_to_reference_tables.php

@@ -0,0 +1,57 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * The tables gaining the column. Credit Card already has it.
+     *
+     * @var array<int, string>
+     */
+    private array $tables = [
+        'mb_references',
+        'mbway_references',
+        'payshop_references',
+        'paysafecard_references',
+    ];
+
+    /**
+     * Run the migrations.
+     *
+     * `transaction_id` is the Eupago transaction the callback delivers once
+     * the payment is made — the id refunds are keyed by. References paid
+     * before this migration keep a null value: the transaction only ever
+     * exists in the callback payload, so there is nothing to backfill from.
+     *
+     * @return void
+     */
+    public function up()
+    {
+        foreach ($this->tables as $table) {
+            Schema::table($table, function (Blueprint $blueprint) {
+                $blueprint->string('transaction_id')->nullable()->index()->after('reference');
+            });
+        }
+    }
+
+    /**
+     * Reverse the migrations.
+     *
+     * SQLite rebuilds the table on a column drop and validates the surviving
+     * indexes against it, so the index goes first.
+     *
+     * @return void
+     */
+    public function down()
+    {
+        foreach ($this->tables as $table) {
+            Schema::table($table, function (Blueprint $blueprint) {
+                $blueprint->dropIndex(['transaction_id']);
+                $blueprint->dropColumn('transaction_id');
+            });
+        }
+    }
+};

docs/mbway.md

@@ -55,4 +55,6 @@ Retrieve the MB WAY references:
 $mbwayReferences = $order->mbwayReferences;
 ```
 
-When the payment is confirmed, the [callback](callbacks.md) fires an `MBWayReferencePaid` event.
+When the payment is confirmed, the [callback](callbacks.md) fires an `MBWayReferencePaid`
+event and stores the Eupago transaction on the reference, so a paid reference can be
+[refunded](refunds.md) through `$reference->transaction_id`.

docs/multibanco.md

@@ -74,4 +74,6 @@ Retrieve the MB references:
 $mbReferences = $order->mbReferences;
 ```
 
-When the reference is paid, the [callback](callbacks.md) fires an `MBReferencePaid` event.
+When the reference is paid, the [callback](callbacks.md) fires an `MBReferencePaid` event
+and stores the Eupago transaction on the reference, so a paid reference can be
+[refunded](refunds.md) through `$reference->transaction_id`.

docs/paysafecard.md

@@ -79,4 +79,6 @@ Retrieve the PaysafeCard references:
 $paysafeCardReferences = $order->paysafeCardReferences;
 ```
 
-When the payment is completed, the [callback](callbacks.md) fires a `PaysafeCardReferencePaid` event.
+When the payment is completed, the [callback](callbacks.md) fires a `PaysafeCardReferencePaid`
+event and stores the Eupago transaction on the reference, so a paid reference can be
+[refunded](refunds.md) through `$reference->transaction_id`.

docs/payshop.md

@@ -64,4 +64,6 @@ Retrieve the PayShop references:
 $payShopReferences = $order->payShopReferences;
 ```
 
-When the reference is paid, the [callback](callbacks.md) fires a `PayShopReferencePaid` event.
+When the reference is paid, the [callback](callbacks.md) fires a `PayShopReferencePaid`
+event and stores the Eupago transaction on the reference, so a paid reference can be
+[refunded](refunds.md) through `$reference->transaction_id`.

docs/refunds.md

@@ -7,7 +7,8 @@ group: Handling payments
 Paid transactions can be refunded, partially or in full, through Eupago's management
 API. Refunds require the [OAuth client credentials](configuration.md#oauth-client-credentials)
 to be configured. The refund is keyed by the transaction id — the `transacao` value
-delivered by the payment [callback](callbacks.md):
+delivered by the payment [callback](callbacks.md), which the package also stores on the
+reference it marks as paid, so a stored reference carries it as `transaction_id`:
 
 ```php
 use CodeTech\EuPago\EuPago;

src/Http/Controllers/MBController.php

@@ -28,7 +28,10 @@ public function callback(Request $request)
             return response()->json(['response' => 'No pending reference found'])->setStatusCode(404);
         }
 
-        $reference->update(['state' => 1]);
+        $reference->update([
+            'state' => 1,
+            'transaction_id' => $validatedData['transacao'],
+        ]);
 
         // trigger event
         event(new MBReferencePaid($reference));

src/Http/Controllers/MBWayController.php

@@ -28,7 +28,10 @@ public function callback(Request $request)
             return response()->json(['response' => 'No pending reference found'])->setStatusCode(404);
         }
 
-        $reference->update(['state' => 1]);
+        $reference->update([
+            'state' => 1,
+            'transaction_id' => $validatedData['transacao'],
+        ]);
 
         // trigger event
         event(new MBWayReferencePaid($reference));

src/Http/Controllers/PayShopController.php

@@ -28,7 +28,10 @@ public function callback(Request $request)
             return response()->json(['response' => 'No pending reference found'])->setStatusCode(404);
         }
 
-        $reference->update(['state' => 1]);
+        $reference->update([
+            'state' => 1,
+            'transaction_id' => $validatedData['transacao'],
+        ]);
 
         // trigger event
         event(new PayShopReferencePaid($reference));

src/Http/Controllers/PaysafeCardController.php

@@ -28,7 +28,10 @@ public function callback(Request $request)
             return response()->json(['response' => 'No pending reference found'])->setStatusCode(404);
         }
 
-        $reference->update(['state' => 1]);
+        $reference->update([
+            'state' => 1,
+            'transaction_id' => $validatedData['transacao'],
+        ]);
 
         // trigger event
         event(new PaysafeCardReferencePaid($reference));

src/Models/MbReference.php

@@ -12,6 +12,7 @@ class MbReference extends Model
     protected $fillable = [
         'entity',
         'reference',
+        'transaction_id',
         'value',
         'start_date',
         'end_date',

src/Models/MbwayReference.php

@@ -11,6 +11,7 @@ class MbwayReference extends Model
      */
     protected $fillable = [
         'reference',
+        'transaction_id',
         'value',
         'alias',
         'state',

src/Models/PayShopReference.php

@@ -16,6 +16,7 @@ class PayShopReference extends Model
      */
     protected $fillable = [
         'reference',
+        'transaction_id',
         'value',
         'state',
     ];

src/Models/PaysafeCardReference.php

@@ -17,6 +17,7 @@ class PaysafeCardReference extends Model
     protected $fillable = [
         'identifier',
         'reference',
+        'transaction_id',
         'url',
         'value',
         'state',

tests/Feature/MbCallbackTest.php

@@ -11,6 +11,8 @@
 
     $response->assertOk()->assertJson(['response' => 'Success']);
     expect((int) $reference->fresh()->state)->toBe(1);
+    // The callback's `transacao` is the id refunds are keyed by.
+    expect($reference->fresh()->transaction_id)->toBe('TXN123');
     Event::assertDispatched(
         MBReferencePaid::class,
         fn (MBReferencePaid $event) => $event->reference->is($reference)

tests/Feature/MbwayCallbackTest.php

@@ -11,6 +11,8 @@
 
     $response->assertOk()->assertJson(['response' => 'Success']);
     expect((int) $reference->fresh()->state)->toBe(1);
+    // The callback's `transacao` is the id refunds are keyed by.
+    expect($reference->fresh()->transaction_id)->toBe('TXN999');
     Event::assertDispatched(
         MBWayReferencePaid::class,
         fn (MBWayReferencePaid $event) => $event->reference->is($reference)

tests/Feature/PayShopCallbackTest.php

@@ -11,6 +11,8 @@
 
     $response->assertOk()->assertJson(['response' => 'Success']);
     expect((int) $reference->fresh()->state)->toBe(1);
+    // The callback's `transacao` is the id refunds are keyed by.
+    expect($reference->fresh()->transaction_id)->toBe('TXN555');
     Event::assertDispatched(
         PayShopReferencePaid::class,
         fn (PayShopReferencePaid $event) => $event->reference->is($reference)

tests/Feature/PaysafeCardCallbackTest.php

@@ -11,6 +11,8 @@
 
     $response->assertOk()->assertJson(['response' => 'Success']);
     expect((int) $reference->fresh()->state)->toBe(1);
+    // The callback's `transacao` is the id refunds are keyed by.
+    expect($reference->fresh()->transaction_id)->toBe('29749250');
     Event::assertDispatched(
         PaysafeCardReferencePaid::class,
         fn (PaysafeCardReferencePaid $event) => $event->reference->is($reference)