Workflows

markSplitOrderPaymentsAsCapturedWorkflow

This documentation provides a reference to the markSplitOrderPaymentsAsCapturedWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow marks all split order payments associated with a payment collection as captured. It updates the payment status to “captured” and sets the captured amount equal to the authorized amount. This is typically triggered after a successful payment capture. Source code

Examples

Payment Captured Subscriber
Order Set Placed Subscriber

packages/modules/b2c-core/src/subscribers/split-payment-payment-captured.ts

import { SubscriberArgs, SubscriberConfig } from '@medusajs/framework'
import { Modules, PaymentEvents } from '@medusajs/framework/utils'
import { markSplitOrderPaymentsAsCapturedWorkflow } from '../workflows/split-order-payment/workflows'

export default async function paymentCapturedHandler({
  event,
  container
}: SubscriberArgs<{ id: string }>) {
  const payment_id = event.data.id
  const paymentService = container.resolve(Modules.PAYMENT)

  const payment = await paymentService.retrievePayment(payment_id, {
    relations: ['payment_collection']
  })

  await markSplitOrderPaymentsAsCapturedWorkflow.run({
    container,
    input: payment.payment_collection_id
  })
}

export const config: SubscriberConfig = {
  event: PaymentEvents.CAPTURED,
  context: {
    subscriberId: 'split-payment-payment-captured-handler'
  }
}

packages/modules/b2c-core/src/subscribers/order-set-placed-payment-capture.ts

import { SubscriberConfig } from '@medusajs/framework'
import { ContainerRegistrationKeys } from '@medusajs/framework/utils'
import { SubscriberArgs } from '@medusajs/medusa'
import { capturePaymentWorkflow } from '@medusajs/medusa/core-flows'
import { OrderSetWorkflowEvents } from '@mercurjs/framework'
import { markSplitOrderPaymentsAsCapturedWorkflow } from '../workflows/split-order-payment/workflows'

export default async function orderSetPlacedHandler({
  event,
  container
}: SubscriberArgs<{ id: string }>) {
  const query = container.resolve(ContainerRegistrationKeys.QUERY)
  const { id: orderSetId } = event.data

  const {
    data: [order_set]
  } = await query.graph({
    entity: 'order_set',
    fields: ['payment_collection_id'],
    filters: {
      id: orderSetId
    }
  })

  const {
    data: [payment_collection]
  } = await query.graph({
    entity: 'payment_collection',
    fields: ['status', 'payments.*'],
    filters: {
      id: order_set.payment_collection_id
    }
  })

  const { result } = await capturePaymentWorkflow.run({
    container,
    input: {
      payment_id: payment_collection.payments[0].id
    }
  })

  await markSplitOrderPaymentsAsCapturedWorkflow.run({
    container,
    input: order_set.payment_collection_id
  })
}

export const config: SubscriberConfig = {
  event: OrderSetWorkflowEvents.PLACED,
  context: {
    subscriberId: 'order-set-placed-payment-capture'
  }
}

Steps

useQueryGraphStep: Fetches all split order payments for the payment collection.
updateSplitOrderPaymentsStep: Updates the payments to set status to “captured” and captured_amount to authorized_amount.

Input

payment_collection_id

string

required

The ID of the payment collection whose split order payments should be marked as captured.

Output

SplitOrderPaymentDTO[]

Array of updated split order payments.

Show properties

string

The ID of the split order payment.

status

string

The payment status (set to “captured”).

captured_amount

number

The captured amount (equal to authorized_amount).

authorized_amount

number

The authorized amount.

refunded_amount

number

The refunded amount.

currency_code

string

The currency code.

payment_collection_id

string

The ID of the payment collection.

partialPaymentRefundWorkflow

This documentation provides a reference to the partialPaymentRefundWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow processes a partial refund for a split order payment. It validates the refund amount, processes the refund with the payment provider, and adds a refund transaction to the order. This workflow is nested within the refundSplitOrderPaymentWorkflow. Source code

Examples

Refund Workflow

packages/modules/b2c-core/src/workflows/split-order-payment/workflows/refund-split-order-payment.ts

import { partialPaymentRefundWorkflow } from './partial-payment-refund'

export const refundSplitOrderPaymentWorkflow = createWorkflow(
  {
    name: 'refund-split-order-payment'
  },
  function (input: RefundSplitOrderPaymentsDTO) {
    const updatePayload = validateRefundSplitOrderPaymentStep(input)
    const splitOrderPayment = updateSplitOrderPaymentsStep(
      transform(updatePayload, (updatePayload) => [updatePayload])
    )
    partialPaymentRefundWorkflow.runAsStep({ input })
    return new WorkflowResponse(splitOrderPayment)
  }
)

Steps

selectAndValidatePaymentRefundStep: Validates the refund amount and retrieves payment details.
refundPaymentsStep: Processes the refund with the payment provider using Medusa’s core step.
addOrderTransactionStep: Adds a refund transaction record to the order.

Input

input

RefundSplitOrderPaymentsDTO

required

The refund details.

Show properties

string

required

The ID of the split order payment to refund.

amount

number

required

The amount to refund.

Output

PaymentDTO[]

Array of refunded payments.

refundSplitOrderPaymentWorkflow

This documentation provides a reference to the refundSplitOrderPaymentWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow refunds a split order payment by validating the refund, updating the split payment record, and processing the actual refund through the payment provider. It updates the payment status to “partially_refunded” or “refunded” based on the remaining amount. Source code

Examples

Order Cancellation

packages/modules/b2c-core/src/workflows/order/workflows/cancel-order.ts

import { refundSplitOrderPaymentWorkflow } from '../../split-order-payment/workflows'

// ... inside cancelOrderWorkflow

parallelize(
  deleteReservationsByLineItemsStep(lineItemIds),
  cancelOrdersStep({ orderIds: [order.id] }),
  refundSplitOrderPaymentWorkflow.runAsStep({
    input: {
      id: order.split_order_payment.id,
      amount: order.split_order_payment.captured_amount
    }
  }),
  createPayoutReversalStep({
    payout_id: payoutId,
    amount: order.split_order_payment.captured_amount,
    currency_code: order.currency_code
  }),
  emitEventStep({
    eventName: OrderWorkflowEvents.CANCELED,
    data: { id: order.id }
  })
)

Steps

validateRefundSplitOrderPaymentStep: Validates the refund amount and calculates the new status.
updateSplitOrderPaymentsStep: Updates the split payment with new refunded amount and status.
partialPaymentRefundWorkflow: Processes the actual refund with the payment provider.

Input

input

RefundSplitOrderPaymentsDTO

required

The refund details.

Show properties

string

required

The ID of the split order payment to refund.

amount

number

required

The amount to refund.

Output

SplitOrderPaymentDTO[]

Array containing the updated split order payment.

Show properties

string

The ID of the split order payment.

status

string

The updated status (“partially_refunded” or “refunded”).

refunded_amount

number

The total refunded amount.

captured_amount

number

The captured amount.

authorized_amount

number

The authorized amount.

currency_code

string

The currency code.

Steps

createSplitOrderPaymentsStep

Creates split order payment records for each order in a multi-vendor cart and links them to their respective orders. If an error occurs after creation, the step’s compensation function automatically deletes the created payments and their links. Source code

Examples

Cart Completion Workflow

packages/modules/b2c-core/src/workflows/cart/workflows/split-and-complete-cart.ts

import { createSplitOrderPaymentsStep } from "../../split-order-payment/steps";

// ... inside splitAndCompleteCartWorkflow

const splitPaymentsToCreate = transform(
  { createdOrders, payment },
  ({ createdOrders, payment }) => {
    return createdOrders.map((order) => ({
      order_id: order.id,
      status: "pending",
      currency_code: order.currency_code,
      authorized_amount: MathBN.convert(
        order.summary?.accounting_total || 0
      ).toNumber(),
      payment_collection_id: payment!.payment_collection_id,
    }));
  }
);

parallelize(
  createSplitOrderPaymentsStep(splitPaymentsToCreate),
  // ... other parallel steps
);

Input

input

CreateSplitOrderPaymentsDTO[]

required

Array of split order payments to create.

Show properties

order_id

string

required

The ID of the order this payment is for.

status

string

required

The initial status of the payment (typically “pending”).

currency_code

string

required

The currency code (e.g., “usd”).

authorized_amount

number

required

The authorized payment amount.

payment_collection_id

string

required

The ID of the payment collection.

Output

SplitOrderPaymentDTO[]

Array of created split order payments.

selectAndValidatePaymentRefundStep

Validates that a refund amount is valid for a split order payment by checking the refundable amount against captures and previous refunds. Returns the payment details needed for processing the refund. Source code

Input

input

RefundSplitOrderPaymentsDTO

required

The refund validation details.

Output

object

Show properties

payment_id

string

The ID of the payment to refund.

currency_code

string

The currency code.

amount

number

The validated refund amount.

order_id

string

The ID of the associated order.

updateSplitOrderPaymentsStep

Updates split order payment records. This step includes a compensation function that restores the previous payment state if a subsequent step in the workflow fails. Source code

Input

input

UpdateSplitOrderPaymentsDTO[]

required

Array of split order payment updates.

Show properties

string

required

The ID of the split order payment to update.

status

string

The new payment status (e.g., “captured”, “partially_refunded”, “refunded”).

authorized_amount

number

The new authorized amount.

captured_amount

number

The new captured amount.

refunded_amount

number

The new refunded amount.

Output

SplitOrderPaymentDTO[]

Array of updated split order payments.

validateRefundSplitOrderPaymentStep

Validates a refund request by checking that the refund amount is positive and does not exceed the refundable amount (captured - already refunded). Calculates the new status based on whether the full amount is being refunded. Source code

Input

input

RefundSplitOrderPaymentsDTO

required

The refund validation details.

Output

UpdateSplitOrderPaymentsDTO

The validated update payload.

Show properties

string

The ID of the split order payment.

refunded_amount

number

The new total refunded amount.

status

string

The new status (“partially_refunded” if amount remains, “refunded” if fully refunded).

Quick start

Components

Core Concepts

Product

Integrations

Deployment

Help

Split Order Payment Workflows

Workflows

markSplitOrderPaymentsAsCapturedWorkflow

Examples

Steps

Input

Output

partialPaymentRefundWorkflow

Examples

Steps

Input

Output

refundSplitOrderPaymentWorkflow

Examples

Steps

Input

Output

Steps

createSplitOrderPaymentsStep

Examples

Input

Output

selectAndValidatePaymentRefundStep

Input

Output

updateSplitOrderPaymentsStep

Input

Output

validateRefundSplitOrderPaymentStep

Input

Output

Quick start

Components

Core Concepts

Product

Integrations

Deployment

Help

​Workflows

​markSplitOrderPaymentsAsCapturedWorkflow

​Examples

​Steps

​Input

​Output

​partialPaymentRefundWorkflow

​Examples

​Steps

​Input

​Output

​refundSplitOrderPaymentWorkflow

​Examples

​Steps

​Input

​Output

​Steps

​createSplitOrderPaymentsStep

​Examples

​Input

​Output

​selectAndValidatePaymentRefundStep

​Input

​Output

​updateSplitOrderPaymentsStep

​Input

​Output

​validateRefundSplitOrderPaymentStep

​Input

​Output

Workflows

markSplitOrderPaymentsAsCapturedWorkflow

Examples

Steps

Input

Output

partialPaymentRefundWorkflow

Examples

Steps

Input

Output

refundSplitOrderPaymentWorkflow

Examples

Steps

Input

Output

Steps

createSplitOrderPaymentsStep

Examples

Input

Output

selectAndValidatePaymentRefundStep

Input

Output

updateSplitOrderPaymentsStep

Input

Output

validateRefundSplitOrderPaymentStep

Input

Output