订单列表返回支付方式说明和支付附加信息。

Co-authored-by: Cursor <cursoragent@cursor.com>

packages/Webkul/BagistoApi/src/Admin/Dto/AdminOrderListDto.php

@@ -48,6 +48,15 @@ class AdminOrderListDto
     #[ApiProperty(writable: false)]
     public ?string $payment_title = null;
 
+    /**
+     * Payment-method instructions (`Payment::getAdditionalDetails`) plus the
+     * stored `order_payment.additional` payload under `additional`.
+     *
+     * @var array<string, mixed>
+     */
+    #[ApiProperty(writable: false)]
+    public array $additional_details = [];
+
     #[ApiProperty(writable: false)]
     public ?string $coupon_code = null;
 

packages/Webkul/BagistoApi/src/Admin/Models/AdminOrder.php

@@ -76,6 +76,13 @@ use Webkul\BagistoApi\Admin\State\OrderCollectionProvider;
                                             'customerEmail' => 'admin@example.com',
                                             'customerName' => 'Test User',
                                             'paymentTitle' => 'Money Transfer',
+                                            'additionalDetails' => [
+                                                'title' => 'Instructions',
+                                                'value' => 'Mail the check to the store address.',
+                                                'additional' => [
+                                                    'transaction_id' => 'CAP-123',
+                                                ],
+                                            ],
                                             'couponCode' => null,
                                             'totalItemCount' => 1,
                                             'totalQtyOrdered' => 1,
@@ -227,7 +234,7 @@ class AdminOrder extends EloquentModel
     protected $appends = [
         'status_label', 'channel_name', 'customer_name', 'payment_title',
         'location', 'formatted_grand_total', 'transaction_id', 'customer_note',
-        'formatted_shipping_insurance_amount',
+        'formatted_shipping_insurance_amount', 'additional_details',
     ];
 
     protected $casts = [
@@ -337,4 +344,15 @@ class AdminOrder extends EloquentModel
     {
         return $this->attributes['formatted_shipping_insurance_amount'] ?? null;
     }
+
+    /**
+     * @return array<string, mixed>
+     */
+    #[ApiProperty(writable: false)]
+    public function getAdditionalDetailsAttribute(): array
+    {
+        $value = $this->attributes['additional_details'] ?? [];
+
+        return is_array($value) ? $value : [];
+    }
 }

packages/Webkul/BagistoApi/src/Admin/State/OrderCollectionProvider.php

@@ -19,6 +19,7 @@ use Webkul\BagistoApi\Admin\Models\AdminOrderDetailInvoice;
 use Webkul\BagistoApi\Admin\Models\AdminOrderItemPreview;
 use Webkul\BagistoApi\Admin\State\Concerns\ResolvesAdminDateRange;
 use Webkul\BagistoApi\Exception\AuthenticationException;
+use Webkul\Payment\Payment;
 use Webkul\Sales\Models\Order;
 
 /**
@@ -213,6 +214,7 @@ class OrderCollectionProvider implements ProviderInterface
             'customer_email' => $order->customer_email,
             'customer_name' => trim($order->customer_first_name.' '.$order->customer_last_name),
             'payment_title' => $this->paymentTitle($order),
+            'additional_details' => $this->additionalDetails($order),
             'coupon_code' => $order->coupon_code,
             'total_item_count' => $order->total_item_count,
             'total_qty_ordered' => (int) $order->total_qty_ordered,
@@ -276,6 +278,7 @@ class OrderCollectionProvider implements ProviderInterface
         $row->customer_email = $order->customer_email;
         $row->customer_name = trim($order->customer_first_name.' '.$order->customer_last_name);
         $row->payment_title = $this->paymentTitle($order);
+        $row->additional_details = $this->additionalDetails($order);
         $row->coupon_code = $order->coupon_code;
         $row->total_item_count = $order->total_item_count;
         $row->total_qty_ordered = (int) $order->total_qty_ordered;
@@ -577,6 +580,39 @@ class OrderCollectionProvider implements ProviderInterface
         return $notesByCustomer[$customerId] ?? [];
     }
 
+    /**
+     * Payment-method instructions plus the order payment's stored additional
+     * payload (`order_payment.additional`: transaction id, PayPal payer, …).
+     *
+     * @return array<string, mixed>
+     */
+    protected function additionalDetails(Order $order): array
+    {
+        $payment = $order->payment;
+        $method = $payment?->method;
+        $details = [];
+
+        if ($method) {
+            try {
+                $fromMethod = Payment::getAdditionalDetails($method);
+            } catch (\Throwable) {
+                $fromMethod = [];
+            }
+
+            if (is_array($fromMethod)) {
+                $details = $fromMethod;
+            }
+        }
+
+        $stored = $payment?->additional;
+
+        if (is_array($stored) && $stored !== []) {
+            $details['additional'] = $stored;
+        }
+
+        return $details;
+    }
+
     /**
      * Resolve the payment-method display title from core config.
      */

packages/Webkul/BagistoApi/tests/Unit/Admin/OrderCollectionProviderListTest.php

@@ -28,6 +28,7 @@ class OrderCollectionProviderListTest extends TestCase
             ]],
         ]);
 
+        $this->assertSame('CAP-9', $dto->additional_details['additional']['transaction_id']);
         $this->assertSame('USD', $dto->base_currency_code);
         $this->assertSame('EUR', $dto->channel_currency_code);
         $this->assertSame('EUR', $dto->order_currency_code);
@@ -101,6 +102,7 @@ class OrderCollectionProviderListTest extends TestCase
         $this->assertSame('Gold / Large', $dto->items[0]['variantTitle']);
 
         $model = (new OrderListProbe)->mapEloquent($order, []);
+        $this->assertSame('LAST-1', $model->additional_details['additional']['last_trans_id']);
         $this->assertSame('LAST-1', $model->transaction_id);
         $this->assertSame('Child Variant', $model->items->first()->variant_name);
         $this->assertSame('Gold / Large', $model->items->first()->variant_title);