Medusa Marketplace #4 | Payments Splitting

Hello everyone!

In this new section, we'll take a look at payments in preparation for what's to come.

What's the goal here?

In the same spirit as Orders, we're going to divide a single Payment into several for each store, or to be more transparent, we're going to create dummy payments for each store.

Let me explain.

The idea behind perseides is to create a marketplace with as little friction as possible. In fact, by creating dummy payments for each child order, we'll be able to calculate the total amount available for each seller on a specific order and we will not have to update a lot of logic. An example is the refund of an order. With this system, the refund will recalculate the child payment (which will be shown to our seller), but also act on the parent payment, which will execute actions on the PaymentProcessor.

Extend the entity

It's always the same recipe when it comes to extending core features: first, you extend the entity :

// src/models/payment.ts
import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from 'typeorm'

import { Payment as MedusaPayment } from '@medusajs/medusa'

@Entity()
export class Payment extends MedusaPayment {
    @Index('PaymentParentId')
    @Column({ nullable: true })
    payment_parent_id?: string

    @ManyToOne(() => Payment, (payment) => payment.children)
    @JoinColumn({ name: 'payment_parent_id', referencedColumnName: 'id' })
    parent?: Payment

    @OneToMany(() => Payment, (payment) => payment.parent)
    @JoinColumn({ name: 'id', referencedColumnName: 'payment_parent_id' })
    children?: Payment[]
}

Create the migration

Once the entity has been extended, it's time to migrate and apply our changes :

npx typeorm migration:create src/migrations/add-payment-children

// src/migrations/<TIMESTAMP>-add-payment-children.ts

// ...
    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`ALTER TABLE "payment" ADD "payment_parent_id" character varying`)
        await queryRunner.query(`CREATE INDEX "PaymentParentId" ON "payment" ("payment_parent_id")`)
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`DROP INDEX "public"."PaymentParentId"`)
        await queryRunner.query(`ALTER TABLE "payment" DROP COLUMN "payment_parent_id"`)
    }
// ...

Then we build before executing the migrations :

yarn build
npx medusa migrations run

When you refresh your database, the new column payment_parent_id should appear:

Override the `OrderService.createRefund` function

Another important aspect concerning refunds with these child payments is that when a refund is made on a child order, the payment used to refund must be the one the parent order (the real payment) :

// src/services/order.ts

class OrderService extends MedusaOrderService {
// ... rest previously implemented
    async createRefund(orderId: string, refundAmount: number, reason: string, note?: string, config?: { no_notification?: boolean }): Promise<Order> {
        const order = await this.retrieveWithTotals(orderId, { relations: ['payments'] })

        if (!order.order_parent_id) {
            // This means we are refunding from the parent order...
            return await super.createRefund(orderId, refundAmount, reason, note, config)
        }

        // Means the refund have occured on a child order,
        // so we need to refund from the parent order and compute the new child order amount
        return await this.atomicPhase_(async (m) => {
            const orderRepo = m.withRepository(this.orderRepository_)
            const refundRepo = m.getRepository(Refund)

            // If the refund amount is greater than the order amount, we can't refund
            if (refundAmount > order.refundable_amount) {
                throw new MedusaError(MedusaError.Types.INVALID_ARGUMENT, 'Refund amount is greater than the order amount')
            }

            // We refund from the parent order
            let parentOrder = await this.retrieve(order.order_parent_id)
            parentOrder = await super.createRefund(order.order_parent_id, refundAmount, reason, `${note}\n\nRefund from child order : ${order.id}`, config)


            // We create a refund for the child order, for future computation (refundable_amount)
            const refund = refundRepo.create({
                order_id: order.id,
                amount: refundAmount,
                reason,
                note: `${note}\n\nRefund from child order : ${order.id}`,
                payment_id: order.payments?.at(0)?.id
            })
            await refundRepo.save(refund)

            // We check if the child order payment is fully refunded
            // If it is, we can set the payment status to REFUNDED
            // Otherwise, we set the payment status to PARTIALLY_REFUNDED
            const childOrderPayment = order.payments?.at(0)

            const amountRefunded = childOrderPayment.amount_refunded + refundAmount

            const isFullyRefunded = amountRefunded === childOrderPayment.amount

            await orderRepo.update(order.id, {
                payment_status: isFullyRefunded ? PaymentStatus.REFUNDED : PaymentStatus.PARTIALLY_REFUNDED
            })

            return await this.retrieve(order.id)
        })
    }

}

In the code snippet above, we make sure to check whether the order is a parent order or a child order, in the case of a parent order, no worries, the original behavior remains the original, on the other hand, in the case where a vendor requests a refund from a child order, the refund must take place on the parent order

We also create "fake" refunds on that "fake" payment, allowing us for a easier computation of the refundable amount later on.

Override the `OrderService.capturePayment` function

In this case, we'll make sure that when the payment for a parent order is captured, the payments for the child orders are also captured.

When we will configure the Stripe plugin, the parent payments will be captured automatically using the medusa-payment-stripe plugin options.

But we also needs to update child order payments :

// src/services/order.ts

class OrderService extends MedusaOrderService {
// ... rest previously implemented

   /**
     * When a parent payment is captured, we capture the parent order payment but also every child order payment
     */
    async capturePayment(orderId: string): Promise<Order> {
        const order = await this.retrieveWithTotals(orderId, { relations: ['payments', 'children'] })

        if (order.order_parent_id) {
            throw new MedusaError(
                MedusaError.Types.NOT_ALLOWED,
                `Order with id ${orderId} is a child order and cannot be captured.`
            )
        }

        return await this.atomicPhase_(async (m) => {
            const orderRepo = m.withRepository(this.orderRepository_)
            const paymentRepo = m.withRepository(PaymentRepository)

            for (const child of order.children) {
                const childOrder = await orderRepo.findOne({
                    where: {
                        id: child.id
                    },
                    relations: ['payments']
                })

                if (!childOrder.payments.at(0).captured_at) {
                    await paymentRepo.update(childOrder.payments.at(0).id, {
                        captured_at: new Date()
                    })
                    await orderRepo.update(child.id, {
                        payment_status: PaymentStatus.CAPTURED
                    })
                }
            }

            return await super.capturePayment(order.id)
        })
    }

}

Update the OrderPlaced subscriber

Once our Payment entity has been modified, we can update our previously created subscriber to create a Payment for each child Order created within the subscriber.

Update your code with the following :

import {
    LineItem,
    Logger,
    OrderService,
    PaymentStatus,
    ShippingMethod,
    type SubscriberArgs,
    type SubscriberConfig
} from '@medusajs/medusa'
import ShippingOptionService from 'src/services/shipping-option'
import { EntityManager } from 'typeorm'

import { Order } from '../../models/order'
import { Product } from '../../models/product'
import { Payment } from '../../models/payment'

import ProductService from '../../services/product'


export default async function handleOrderPlaced({
    data,
    eventName,
    container,
    pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
    const manager = container.resolve<EntityManager>('manager')
    const logger = container.resolve<Logger>('logger')

    await manager.transaction(async (m) => {
        const orderService: OrderService = container.resolve<OrderService>('orderService')
        const productService: ProductService = container.resolve<ProductService>('productService')
        const shippingOptionService: ShippingOptionService =
            container.resolve<ShippingOptionService>('shippingOptionService')


        const orderRepo = m.getRepository(Order)
        const lineItemRepo = m.getRepository(LineItem)
        const shippingMethodRepo = m.getRepository(ShippingMethod)
        const paymentRepo = m.getRepository(Payment)

        const orderActivity = logger.activity(`Splitting order ${data.id} into child orders...`)

        const order = await orderService.retrieveWithTotals(data.id, {
            relations: ['items', 'items.variant', 'items.variant.prices', 'cart', 'payments', 'shipping_methods'],
        })

        if (!order) {
            logger.failure(orderActivity, `OrderPlacedSubscriber | Order not found for order id ${data.id}.`)
            return
        }

        // #1 : Group Items By Store Id

        const storesWithItems = new Map<string, Order['items']>()

        for (const item of order.items) {
            const product: Product = await productService.retrieve(item.variant.product_id)
            const storeId = product.store_id

            if (!storeId) {
                logger.failure(orderActivity, `OrderPlacedSubscriber | product.store_id not found for product ${product.id}.`)
                continue
            }

            if (!storesWithItems.has(storeId)) {
                storesWithItems.set(storeId, [])
            }

            storesWithItems.get(storeId).push(item)
        }

        // #2 : For each store, create a new order with the relevant items and shipping methods
        for (const [storeId, items] of storesWithItems.entries()) {

            // #2.1 : Create a new order
            const childOrder = orderRepo.create({
                ...order,
                order_parent_id: order.id,
                store_id: storeId,
                cart_id: null,
                cart: null,
                id: null,
                shipping_methods: [],
            })

            const savedChildOrder = await orderRepo.save(childOrder)

            // #2.2 : Create a new line item for each item in the order
            let totalItemsAmount: number = 0
            for (const item of items) {
                const lineItem = lineItemRepo.create({
                    ...item,
                    order_id: savedChildOrder.id,
                    cart_id: null,
                    id: null,
                })

                await lineItemRepo.save(lineItem)


                // We compute the total order amount for the child order
                totalItemsAmount += item.total
            }

            // #2.3 : Create a new shipping method for each child order with a matching shipping option that is in the same store
            let totalShippingAmount: number = 0
            for (const shippingMethod of order.shipping_methods) {
                const shippingOption = await shippingOptionService.retrieve(shippingMethod.shipping_option_id)

                if (shippingOption.store_id !== storeId) {
                    continue
                }

                const newShippingMethod = shippingMethodRepo.create({
                    ...shippingMethod,
                    id: null,
                    cart_id: null,
                    cart: null,
                    order_id: savedChildOrder.id,
                })

                await shippingMethodRepo.save(newShippingMethod)

                totalShippingAmount += shippingMethod.total
            }

            const childPayment = paymentRepo.create({
                ...order.payments[0], // In our case, we only have one payment for the order
                payment_parent_id: order.payments[0].id,
                order_id: savedChildOrder.id,
                amount: totalItemsAmount + totalShippingAmount, // This is the total amount of the child order
                cart_id: null,
                cart: null,
                id: null,
            })

            await paymentRepo.save(childPayment)

        }

        // #3 : Capture the payment for the parent order (it will also capture the child orders)
        await orderService.withTransaction(m).capturePayment(order.id)

        logger.success(orderActivity, `Order ${data.id} has been split into ${storesWithItems.size} child orders.`)

    })

}

export const config: SubscriberConfig = {
    event: OrderService.Events.PLACED,
    context: {
        subscriberId: 'order-placed-handler',
    },
}

From now on, for each order placed, a child payment will be created and linked to a child order.

In the screenshot below, here's an example of an order that has been split into several orders.

You can see that the total amount displayed is explicitly that of the products and shipping costs linked to that specific Store only :

   /**
     * When a parent payment is captured, we capture the parent order payment but also every child order payment
     */
    async capturePayment(orderId: string): Promise<Order> {
        const order = await this.retrieveWithTotals(orderId, { relations: ['payments', 'children'] })

        if (order.order_parent_id) {
            throw new MedusaError(
                MedusaError.Types.NOT_ALLOWED,
                `Order with id ${orderId} is a child order and cannot be captured.`
            )
        }

        return await this.atomicPhase_(async (m) => {
            const orderRepo = m.withRepository(this.orderRepository_)
            const paymentRepo = m.withRepository(PaymentRepository)

            for (const child of order.children) {
                const childOrder = await orderRepo.findOne({
                    where: {
                        id: child.id
                    },
                    relations: ['payments']
                })

                if (!childOrder.payments.at(0).captured_at) {
                    await paymentRepo.update(childOrder.payments.at(0).id, {
                        captured_at: new Date()
                    })
                    await orderRepo.update(child.id, {
                        payment_status: PaymentStatus.CAPTURED
                    })
                }
            }

            return await super.capturePayment(order.id)
        })
    }

What's Next ?

In the next section, we'll be integrating Stripe and Stripe Connect, so don't forget to create your Stripe and Stripe Connect account.

GitHub Branch

You can access the complete part's code here.

Contact

You can contact me on Discord and X with the same username : @adevinwild

Medusa Marketplace #4 | Payments Splitting

Comments (1)

Build Your First Marketplace With Medusa.js

Medusa Marketplace #5 | Stripe Connect

More from this blog

Introducing perseides.org

Medusa Marketplace #5 | Stripe Connect

Medusa Marketplace #3 | Orders Splitting

Medusa Marketplace #2.4 | Extending Shipping services

What's the goal here?

Extend the entity

Create the migration

Override the `OrderService.createRefund` function

Override the `OrderService.capturePayment` function

Update the OrderPlaced subscriber

What's Next ?

GitHub Branch

Contact

Command Palette

Comments (1)

Build Your First Marketplace With Medusa.js

Medusa Marketplace #5 | Stripe Connect

More from this blog

What's the goal here?

Extend the entity

Create the migration

Override the OrderService.createRefund function

Override the OrderService.capturePayment function

Update the OrderPlaced subscriber

What's Next ?

GitHub Branch

Contact

Override the `OrderService.createRefund` function

Override the `OrderService.capturePayment` function