Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

15.4 KB
Raw Blame
import { ExecArgs } from "@medusajs/framework/types"
import {
  ContainerRegistrationKeys,
  MathBN,
  Modules,
} from "@medusajs/framework/utils"
import {
  addToCartWorkflow,
  createCartWorkflow,
  createOrderFulfillmentWorkflow,
  createPaymentCollectionForCartWorkflow,
  createPaymentSessionsWorkflow,
  refundPaymentWorkflow,
} from "@medusajs/medusa/core-flows"
import {
  addSellerShippingMethodToCartWorkflow,
  completeCartWithSplitOrdersWorkflow,
  splitCapturedCartPaymentWorkflow,
} from "@mercurjs/core/workflows"
import { MercurModules } from "@mercurjs/types"
import { getStripeClient } from "@mercurjs/stripe-connector-plugin/lib/stripe-client"
import { AdjustmentType, JobTrigger, STRIPE_CONNECTOR_MODULE } from "@mercurjs/stripe-connector-plugin/types"
import { runJob } from "@mercurjs/stripe-connector-plugin/utils/run-job"
import { jobWorkflow } from "@mercurjs/stripe-connector-plugin/workflows/jobs"

import { requireStripeTestKey } from "./utils/stripe-test-key"

/**
 * Walks one Sole Society order through the whole Stripe pipeline against the
 * sandbox: Stripe-authorized checkout, fulfilment, capture, transfer, a
 * partial refund with its reversal, and a settlement that pays the seller
 * out. The connected account must already be active.
 *
 * Run with the API on the same database and Redis, and scripts/stripe-listen.sh
 * forwarding webhooks (the cart is completed by the payment webhook):
 *   bun --cwd apps/api run stripe:simulate
 */
const SELLER_NAME = process.env.SELLER_NAME ?? "Sole Society"
const SHIPPING_OPTION_NAME = "Standard Shipping"
const PAYMENT_PROVIDER_ID = "pp_stripe-connector_stripe"
// Test card whose funds skip the pending balance, so the payout has money to move.
const TEST_PAYMENT_METHOD = "pm_card_bypassPending"
const REFUND_SHARE = 0.25
// Set to an existing order id to skip checkout and fulfilment and re-run the pipeline on it.
const RESUME_ORDER_ID = process.env.RESUME_ORDER_ID
const SKIP_REFUND = process.env.SKIP_REFUND === "1"
const DIRECT_CHECKOUT = process.env.DIRECT_CHECKOUT === "1"
const SKIP_ADJUSTMENTS = process.env.SKIP_ADJUSTMENTS === "1"
const CURRENCY = process.env.CURRENCY?.toLowerCase()

const providerIdOf = (data: unknown) => (data as { provider?: { id?: string } } | null)?.provider?.id

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default async function simulateStripePayouts({ container }: ExecArgs) {
  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
  const query = container.resolve(ContainerRegistrationKeys.QUERY)
  const link = container.resolve(ContainerRegistrationKeys.LINK)
  const regionModule = container.resolve(Modules.REGION)
  const salesChannelModule = container.resolve(Modules.SALES_CHANNEL)
  const fulfillmentModule = container.resolve(Modules.FULFILLMENT)
  const payoutService = container.resolve(MercurModules.PAYOUT)

  const stripe = getStripeClient(requireStripeTestKey())

  // 1. seller, account, shipping option
  const {
    data: [seller],
  } = await query.graph({
    entity: "seller",
    fields: ["id", "name", "payout_account.id", "payout_account.status", "payout_account.external_id"],
    filters: { name: SELLER_NAME },
  })
  if (!seller) throw new Error(`Seller ${SELLER_NAME} not found`)
  if (seller.payout_account?.status !== "active") {
    throw new Error(`${SELLER_NAME}'s payout account is ${seller.payout_account?.status ?? "missing"}; finish onboarding first`)
  }
  logger.info(`Seller ${seller.name} (${seller.id}) on ${seller.payout_account.external_id}`)

  const { data: shippingOptions } = await query.graph({
    entity: "shipping_option",
    fields: ["id", "name", "seller.id", "service_zone.id", "service_zone.fulfillment_set_id"],
    filters: { name: SHIPPING_OPTION_NAME },
  })
  const shippingOption = shippingOptions.find((so) => so.seller?.id === seller.id)
  if (!shippingOption?.service_zone?.id) throw new Error(`${SELLER_NAME} has no "${SHIPPING_OPTION_NAME}" option`)

  const geoZones = await fulfillmentModule.listGeoZones(
    { type: "country", service_zone_id: shippingOption.service_zone.id },
    { take: null }
  )
  const optionCountries = new Set(geoZones.map((g) => g.country_code?.toLowerCase()).filter(Boolean) as string[])

  // 2. region covering one of those countries, with the Stripe provider enabled
  const regions = await regionModule.listRegions({}, { relations: ["countries", "payment_providers"] })
  let region = regions.find(
    (r) => (!CURRENCY || r.currency_code === CURRENCY) && r.countries?.some((c) => c.iso_2 && optionCountries.has(c.iso_2.toLowerCase()))
  )
  if (!region) throw new Error("No region covers the shipping option's countries")
  const country = region.countries!.find((c) => c.iso_2 && optionCountries.has(c.iso_2.toLowerCase()))!.iso_2!.toLowerCase()

  if (!region.payment_providers?.some((p) => p.id === PAYMENT_PROVIDER_ID)) {
    await link.create({
      [Modules.REGION]: { region_id: region.id },
      [Modules.PAYMENT]: { payment_provider_id: PAYMENT_PROVIDER_ID },
    })
    logger.info(`Enabled ${PAYMENT_PROVIDER_ID} on region ${region.name}`)
  }

  const [salesChannel] = await salesChannelModule.listSalesChannels({ name: "Default Sales Channel" }, { take: 1 })
  if (!salesChannel) throw new Error("Default sales channel not found")

  const fulfillmentSetId = shippingOption.service_zone.fulfillment_set_id
  const { data: stockLocations } = await query.graph({
    entity: "stock_locations",
    fields: ["id", "fulfillment_sets.id"],
  })
  const locationId = stockLocations.find((sl) => (sl.fulfillment_sets ?? []).some((fs) => fs?.id === fulfillmentSetId))?.id
  if (!locationId) throw new Error("Seller stock location not found")
  await link
    .create({
      [Modules.SALES_CHANNEL]: { sales_channel_id: salesChannel.id },
      [Modules.STOCK_LOCATION]: { stock_location_id: locationId },
    })
    .catch(() => null)

  // 3. one published offer with stock
  const { data: offers } = await query.graph({
    entity: "offer",
    fields: ["id", "sku", "variant_id"],
    filters: { seller_id: seller.id },
  })
  const productModule = container.resolve(Modules.PRODUCT)
  const variants = await productModule.listProductVariants(
    { id: offers.map((o) => o.variant_id).filter(Boolean) as string[] },
    { relations: ["product"], take: null }
  )
  const published = new Set(variants.filter((v) => v.product?.status === "published").map((v) => v.id))
  const offer = offers.find((o) => o.variant_id && published.has(o.variant_id))
  if (!offer) throw new Error(`${SELLER_NAME} has no offer on a published product`)

  const run = async (job: Parameters<typeof runJob>[1], scope: Parameters<typeof jobWorkflow>[2] = {}) => {
    const result = await runJob(container, job, JobTrigger.MANUAL, jobWorkflow(job, container, scope))
    logger.info(`${job}: ${result?.status} ${JSON.stringify(result?.stats ?? {})}${result?.error ? ` error=${result.error}` : ""}`)
    return result
  }

  let order: { id: string; display_id: number; total: unknown; items?: { id: string; quantity: number }[] | null }
  let groupId: string

  if (RESUME_ORDER_ID) {
    const {
      data: [existing],
    } = await query.graph({
      entity: "order",
      fields: ["id", "display_id", "total", "items.id", "items.quantity"],
      filters: { id: RESUME_ORDER_ID },
    })
    if (!existing) throw new Error(`Order ${RESUME_ORDER_ID} not found`)
    order = existing as never
    const { data: links } = await query.graph({ entity: "order_group_order", fields: ["order_group_id"], filters: { order_id: order.id } })
    groupId = links[0]?.order_group_id
    logger.info(`Resuming on order #${order.display_id} (${order.id})`)
  } else {
  // 4. cart → Stripe session → confirm with the test card → complete
  const address = {
    first_name: "Stripe",
    last_name: "Tester",
    address_1: "1 Test Street",
    city: "Testville",
    country_code: country,
    postal_code: "10000",
  }
  const { result: cart } = await createCartWorkflow(container).run({
    input: {
      email: "[email protected]",
      region_id: region.id,
      sales_channel_id: salesChannel.id,
      currency_code: region.currency_code,
      shipping_address: address,
      billing_address: address,
    },
  })
  await addToCartWorkflow(container).run({
    input: {
      cart_id: cart.id,
      items: [{ variant_id: offer.variant_id, quantity: 2, offer_id: offer.id, metadata: { offer_id: offer.id } } as never],
    },
  })
  await addSellerShippingMethodToCartWorkflow(container).run({
    input: { cart_id: cart.id, options: [{ id: shippingOption.id }] },
  })
  const { result: paymentCollection } = await createPaymentCollectionForCartWorkflow(container).run({
    input: { cart_id: cart.id },
  })
  const { result: sessions } = await createPaymentSessionsWorkflow(container).run({
    input: { payment_collection_id: paymentCollection.id, provider_id: PAYMENT_PROVIDER_ID },
  })
  const session = Array.isArray(sessions) ? sessions[0] : sessions
  const intentId = (session.data as { id?: string })?.id
  if (!intentId) throw new Error("Stripe session has no PaymentIntent id")

  await stripe.paymentIntents.confirm(intentId, {
    payment_method: TEST_PAYMENT_METHOD,
    return_url: "http://localhost:9000",
  })
  logger.info(`Confirmed ${intentId} with ${TEST_PAYMENT_METHOD} (authorized, not captured)`)

  let orderGroupId: string | undefined
  if (DIRECT_CHECKOUT) {
    const { result: completion, errors } = await completeCartWithSplitOrdersWorkflow(container).run({
      input: { cart_id: cart.id },
      throwOnError: false,
    })
    if (errors?.length) throw errors[0].error
    orderGroupId = completion?.order_group_id
  } else {
    // A storefront that drops the customer mid-redirect relies on
    // payment_intent.amount_capturable_updated to complete the cart.
    // The order group is written midway through completion; completed_at
    // marks the end, after which capturing cannot race checkout's own split.
    for (let attempt = 0; attempt < 30 && !orderGroupId; attempt++) {
      await sleep(2000)
      const {
        data: [completed],
      } = await query.graph({ entity: "cart", fields: ["completed_at"], filters: { id: cart.id } })
      if (!completed?.completed_at) continue
      const { data: groups } = await query.graph({ entity: "order_group", fields: ["id"], filters: { cart_id: cart.id } })
      orderGroupId = groups[0]?.id
    }
    if (!orderGroupId) {
      throw new Error("The payment webhook did not complete the cart; is scripts/stripe-listen.sh running? (DIRECT_CHECKOUT=1 skips it)")
    }
    logger.info(`Cart ${cart.id} completed by the payment webhook`)
  }
  const {
    data: [group],
  } = await query.graph({
    entity: "order_group",
    fields: ["id", "display_id", "orders.id", "orders.display_id", "orders.total", "orders.items.id", "orders.items.quantity"],
    filters: { id: orderGroupId },
  })
  order = group.orders![0] as never
  groupId = group.id
  logger.info(`Order group #${group.display_id}: order #${order.display_id} (${order.id}) total ${order.total} ${region.currency_code}`)

  // 5. fulfil → the group is decided
  await createOrderFulfillmentWorkflow(container).run({
    input: {
      order_id: order.id,
      location_id: locationId,
      items: (order.items ?? []).map((item) => ({ id: item.id, quantity: item.quantity })),
      no_notification: true,
    },
  })
  logger.info(`Fulfilled order #${order.display_id}`)
  }

  // 6. capture
  await run("payout-validate-captures", { order_group_id: groupId })

  // The captured cart payment is split into per-order payments by a subscriber.
  const capturedOrderPayment = async () => {
    const {
      data: [fresh],
    } = await query.graph({
      entity: "order",
      fields: ["id", "payment_collections.payments.id", "payment_collections.payments.captured_at"],
      filters: { id: order.id },
    })
    return (fresh?.payment_collections ?? []).flatMap((c) => c?.payments ?? []).find((p) => p?.captured_at)?.id ?? null
  }
  let orderPaymentId: string | null = null
  for (let attempt = 0; attempt < 20 && !orderPaymentId; attempt++) {
    await sleep(1500)
    orderPaymentId = await capturedOrderPayment()
  }
  if (!orderPaymentId) {
    const { data: carts } = await query.graph({ entity: "order_cart", fields: ["cart_id"], filters: { order_id: order.id } })
    logger.warn(`The payment.captured subscriber did not split cart ${carts[0]?.cart_id}'s payment; splitting it here`)
    await splitCapturedCartPaymentWorkflow(container).run({ input: { cart_id: carts[0].cart_id } })
    orderPaymentId = await capturedOrderPayment()
  }
  if (!orderPaymentId) throw new Error("Order payment was not captured and split")
  logger.info(`Order payment ${orderPaymentId} captured`)

  // 7. transfer
  await run("payout-process-transfers", { order_id: order.id })

  // 8. partial refund → reversal
  if (!SKIP_REFUND) {
    const refundAmount = Number(MathBN.convert(MathBN.mult(order.total as never, REFUND_SHARE)).toFixed(2))
    await refundPaymentWorkflow(container).run({
      input: { payment_id: orderPaymentId, amount: refundAmount, note: "Simulated partial refund" },
    })
    logger.info(`Refunded ${refundAmount} ${region.currency_code} on ${orderPaymentId}`)
  }
  await run("payout-process-reversals", { order_id: order.id })

  // 9. operator adjustments, netted by the settlement
  const connector = container.resolve(STRIPE_CONNECTOR_MODULE)
  if (!SKIP_ADJUSTMENTS) {
    await connector.createAdjustments([
      { account_id: seller.payout_account.id, type: AdjustmentType.EXTRA_CREDIT, amount: 15, currency_code: region.currency_code, reason: "Simulated goodwill credit" },
      { account_id: seller.payout_account.id, type: AdjustmentType.EXTRA_INVOICE, amount: 5, currency_code: region.currency_code, reason: "Simulated listing fee" },
    ])
    logger.info(`Added a 15 ${region.currency_code} credit and a 5 ${region.currency_code} invoice`)
  }

  // 10. settlement + payout
  await run("payout-process-settlements", { seller_id: seller.id })

  // 11. summary
  const payouts = await payoutService.listPayouts({ order_id: order.id }, { relations: ["reversals"] })
  for (const payout of payouts) {
    logger.info(`payout ${payout.id} ${payout.amount} ${payout.currency_code} → ${payout.status}${providerIdOf(payout.data) ? ` ${providerIdOf(payout.data)}` : ""}${payout.status_reason ? ` (${payout.status_reason})` : ""}`)
    for (const reversal of payout.reversals ?? []) {
      logger.info(`  reversal ${reversal.id} ${reversal.amount} → ${reversal.status}${providerIdOf(reversal.data) ? ` ${providerIdOf(reversal.data)}` : ""}${reversal.status_reason ? ` (${reversal.status_reason})` : ""}`)
    }
  }
  for (const adjustment of await connector.listAdjustments({ account_id: seller.payout_account.id }, { order: { created_at: "DESC" }, take: 2 })) {
    logger.info(`adjustment ${adjustment.id} ${adjustment.type} ${adjustment.amount} → ${adjustment.status}${adjustment.provider_transfer_id ? ` ${adjustment.provider_transfer_id}` : ""}${adjustment.status_reason ? ` (${adjustment.status_reason})` : ""}`)
  }
  const [settlement] = await connector.listSettlements({ account_id: seller.payout_account.id }, { order: { period_end: "DESC" }, take: 1 })
  if (settlement) {
    logger.info(`settlement ${settlement.id}: payouts ${settlement.payouts_total} − reversals ${settlement.reversals_total} + adjustments ${settlement.adjustments_total} = ${settlement.amount} ${settlement.currency_code} → ${settlement.status}${settlement.provider_payout_id ? ` ${settlement.provider_payout_id}` : ""}${settlement.status_reason ? ` (${settlement.status_reason})` : ""}`)
  }
}