Skip to Content
better-auth-nuvion

Build a marketplace

Several sellers under one platform. Onboard vendors, take a commission on every sale, show each vendor their sales and handle refunds.

In a marketplace the customer pays a vendor, and the platform takes a commission. The plugin models that as a tree: each vendor is an organization under the platform's organization, and the platform's cut is a fee rule on the vendor.

platform (you)
├── vendor A
├── vendor B
└── vendor C

Add a level for agents or resellers when you need it (Choosing a structure). Everything below works the same.

What you need first

  • A Nuvion entity and account for the platform, and one entity and account per vendor. Every organization needs its own account, because a book transfer needs somewhere else to land.
  • The vendors' entities must be approved by Nuvion before they can hold money. That can take time, so design onboarding as a state ("pending review") not a single step (Before you start).

1. Onboard a vendor

When a vendor signs up, create their organization under the platform and give it a commission. The sequence is in Recipes. Bind it when Nuvion approves the vendor's entity, which you can react to instead of polling:

lib/auth.ts
hooks: {
  onEntityUpdated: async ({ entityId, status }) => {
    if (status !== "approved") return;
    const vendor = await db.vendor.findFirst({ where: { nuvionEntityId: entityId } });
    if (!vendor || vendor.bound) return;
    const accountId = await createVendorAccount(entityId); // your call to Nuvion's accounts API
    await auth.api.bindEntity({ headers: adminHeaders, body: { organizationId: vendor.organizationId, entityId, accountId } });
    await db.vendor.update({ where: { id: vendor.id }, data: { bound: true } });
  },
}

The hook receives only the entity id and its status. It is confirmed with Nuvion before it runs, and it can run more than once, hence the bound check (Entity approval). Until a vendor is bound, do not let customers check out from them: a payment for an unbound organization is refused.

2. Set the commission

await authClient.nuvion.feeRule({
  organizationId: vendor.organizationId,
  bps: 1000, // the platform takes 10% of each sale
  flatMinor: 30, // plus 30p
  capMinor: 2_500, // but never more than £25.00
  bearer: "merchant",
});

bearer: "merchant" takes the commission out of the vendor's share. With "payer" the customer pays it on top. Preview what a sale would split into before showing a price, with quote (Recipes). The legs always add up to the amount charged, and rounding goes to the platform.

3. Check out from one vendor

A payment belongs to one vendor. The customer pays the vendor's organization, and the plugin sends the platform's commission to the platform's account.

app/actions.ts
export async function buyFromVendor(vendorOrgId: string, cart: CartItem[]) {
  const h = await headers();
  const totalMinor = await priceCart(vendorOrgId, cart); // from your database
  const order = await db.order.create({
    data: { vendorOrgId, totalMinor, status: "awaiting_payment" },
  });
  const payment = await auth.api.createPayment({
    headers: h,
    body: {
      organizationId: vendorOrgId,
      amountMinor: totalMinor,
      currency: "GBP",
      redirectUrl: `https://market.example.com/orders/${order.id}`,
    },
  });
  await db.order.update({
    where: { id: order.id },
    data: { paymentId: payment.paymentId },
  });
  redirect(payment.checkoutUrl);
}

A cart with items from several vendors becomes one payment per vendor, each with its own checkout. Either charge them one after another, or ask the customer to check out vendor by vendor. The plugin has no single payment that fans out to unrelated vendors.

The shop guide covers the order, the hook and abandoned checkouts, which are the same here: Accept payments for an online shop.

4. Show a vendor their sales

A vendor sees the payments of their own organization, with each share and its state. The caller must be an owner or admin of that organization.

app/vendor/page.tsx
const { payments } = await auth.api.listPayments({
  headers: await headers(),
  query: { organizationId: vendorOrgId },
});
// each payment has .status, .chargedMinor and .legs (who got what, and whether it moved)

Let them see partial payments too: a share that failed (for example because of a low balance) is theirs and yours to retry (Failures and retries).

5. Refunds and disputes

A refund reverses the shares: the platform and any reseller send their part back to the vendor. If a vendor has already withdrawn the money, a reversal can fail for lack of funds, and the refund stays refund_partial until it is retried. Decide your policy for that in your vendor terms. As everywhere, the customer is paid back outside the plugin (Refunds).

How vendors get paid out

The plugin moves money between Nuvion accounts. A vendor's share sits in their own Nuvion account. Paying it to their bank is a Nuvion payout that the vendor, or you on their behalf, starts in Nuvion. The plugin does not create payouts.

Before you launch

  • A vendor is bound only after Nuvion has approved their entity.
  • Commission is set on every vendor, and you checked a sale's split with quote.
  • Orders and the settle hook are idempotent, as in the shop guide.
  • Vendors can see their own payments and nobody else's.
  • You tested one sale end to end with the smallest amount, with a platform and a vendor on separate accounts (Going to production).

On this page