fix(core-flows, payment, types): expose metadata on refund creation through refundPaymentsWorkflow (#15273)

Closes #14816

## What
Expose the `metadata` field on refund creation when using `refundPaymentsWorkflow`.

## Why
The `Refund` data model already has a `metadata` column (see `packages/modules/payment/src/models/refund.ts`), but the field is not present on:

- `CreateRefundDTO`
- `RefundPaymentsStepInput`
- `RefundPaymentsWorkflowInput`

So callers of `refundPaymentsWorkflow` (and the `PaymentModuleService.refundPayment` API directly) have no way to attach metadata to a refund — even though the underlying storage supports it. The reporter in #14816 hit this exact gap.

## How
1. Add `metadata?: Record<string, unknown>` to `CreateRefundDTO` in `@medusajs/types`.
2. Add the same optional field to `RefundPaymentsStepInput` and `RefundPaymentsWorkflowInput` in `@medusajs/core-flows`. The step already spreads the input into `paymentModule.refundPayment`, so no behavioral change is needed at the workflow layer once the type allows it.
3. Forward `data.metadata` to `refundService_.create(...)` inside `PaymentModuleService.refundPayment_` so the value actually lands on the refund row.

Changes are additive and the new property is optional — no behavior change for existing callers.

## Testing
- Added an integration test in `packages/modules/payment/integration-tests/__tests__/services/payment-module/index.spec.ts` that calls `refundPayment` with a `metadata` payload and asserts the refund persists those values.
- Existing refund tests continue to pass (no signature changes, field is optional).

## Changeset
Included: `.changeset/refund-payments-metadata.md` (patch bumps for `@medusajs/core-flows`, `@medusajs/payment`, `@medusajs/types`).


---

> [!NOTE]
> **Medium Risk**
> Touches refund creation in the payment module (a money-critical path), but the change is additive (optional `metadata`) and covered by an integration test.
> 
> **Overview**
> Exposes optional `metadata` when creating refunds via `refundPaymentsWorkflow` by extending `RefundPaymentsStepInput`, `RefundPaymentsWorkflowInput`, and `CreateRefundDTO`.
> 
> Threads the new field through `PaymentModuleService.refundPayment` into `refundService_.create(...)`, and adds an integration test asserting refund metadata is persisted. Includes a changeset bumping `@medusajs/core-flows`, `@medusajs/payment`, and `@medusajs/types`.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit c100f18. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>

Author: Metbcy

.changeset/refund-payments-metadata.md

@@ -0,0 +1,14 @@
+---
+"@medusajs/core-flows": patch
+"@medusajs/payment": patch
+"@medusajs/types": patch
+---
+
+fix(core-flows, payment, types): expose `metadata` on refund creation through `refundPaymentsWorkflow`
+
+The `Refund` data model supports a `metadata` field, but it was not exposed on
+`CreateRefundDTO`, `RefundPaymentsStepInput`, or `RefundPaymentsWorkflowInput`,
+making it impossible to set metadata on a refund created via
+`refundPaymentsWorkflow`. This adds the optional field to all three types and
+threads it through `PaymentModuleService.refundPayment` so the value reaches
+the underlying refund row.

packages/core/core-flows/src/payment/steps/refund-payments.ts

@@ -32,6 +32,10 @@ export type RefundPaymentsStepInput = {
    * The note to attach to the refund.
    */
   note?: string
+  /**
+   * Holds custom data in key-value pairs.
+   */
+  metadata?: Record<string, unknown>
 }[]
 
 export const refundPaymentsStepId = "refund-payments-step"

packages/core/core-flows/src/payment/workflows/refund-payments.ts

@@ -102,6 +102,10 @@ export type RefundPaymentsWorkflowInput = {
    * The note to attach to the refund.
    */
   note?: string
+  /**
+   * Holds custom data in key-value pairs.
+   */
+  metadata?: Record<string, unknown>
 }[]
 
 export const refundPaymentsWorkflowId = "refund-payments-workflow"

packages/core/types/src/payment/mutations.ts

@@ -187,6 +187,11 @@ export interface CreateRefundDTO {
    * a user's ID.
    */
   created_by?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
+  metadata?: Record<string, unknown>
 }
 
 /**

packages/modules/payment/integration-tests/__tests__/services/payment-module/index.spec.ts

@@ -944,6 +944,34 @@ moduleIntegrationTestRunner<IPaymentModuleService>({
             )
           })
 
+          it("should persist metadata passed when refunding a payment", async () => {
+            await service.capturePayment({
+              amount: 100,
+              payment_id: "pay-id-2",
+            })
+
+            const refundedPayment = await service.refundPayment({
+              amount: 100,
+              payment_id: "pay-id-2",
+              metadata: { reason: "customer-request", ticket_id: "42" },
+            })
+
+            expect(refundedPayment).toEqual(
+              expect.objectContaining({
+                id: "pay-id-2",
+                refunds: [
+                  expect.objectContaining({
+                    amount: 100,
+                    metadata: {
+                      reason: "customer-request",
+                      ticket_id: "42",
+                    },
+                  }),
+                ],
+              })
+            )
+          })
+
           it("should fully refund a payment through two refunds", async () => {
             await service.capturePayment({
               amount: 100,

packages/modules/payment/src/services/payment-module.ts

@@ -926,6 +926,7 @@ export default class PaymentModuleService
         created_by: data.created_by,
         note: data.note,
         refund_reason_id: data.refund_reason_id,
+        metadata: data.metadata,
       },
       sharedContext
     )