Skip to Content
better-auth-nuvion

Payments

Create a hosted checkout for a merchant, follow the payment through its statuses, and read its legs.

Create a payment

This is client code: it uses the typed client you create in Mount the handler and add the client. The Nuvion key never leaves your server.

const { data, error } = await authClient.nuvion.payments({
  organizationId: merchant.id,          // the leaf organization the customer pays
  amountMinor: 10_000,                  // £100.00
  currency: "GBP",                      // 3 letters
  redirectUrl: "https://shop.example.com/done", // https; where the customer returns
});

The plugin quotes the split from the merchant's chain, creates a Nuvion funding session (open-banking) on the merchant's entity and account, saves a nuvionPayment in status pending together with its legs (one per parent, state pending), so the split is fixed from this moment, and returns:

{
  "paymentId": "9c3a0e06-37f5-42d6-a6bc-c308e5030070",
  "checkoutUrl": "https://app.nuvion.dev/checkout/01M...",
  "chargedMinor": 10000,
  "legs": [
    { "organizationId": "org_merchant", "amountMinor": 9700 },
    { "organizationId": "org_reseller", "amountMinor": 150 },
    { "organizationId": "org_platform", "amountMinor": 150 }
  ]
}

Redirect the customer to checkoutUrl. The funding session's unique_reference (and narration) is the payment's reference, pay_<uuid>, which is how the inflow is matched later.

The merchant organization must be bound. The caller must be an owner or admin of it.

What happens next

When the customer pays, Nuvion sends inflows.completed. The plugin then:

  1. verifies the webhook signature,
  2. finds the payment by the reference in the event,
  3. checks the amount equals the quoted chargedMinor (a different amount is not split),
  4. executes the legs saved at checkout as book transfers from the merchant's account. Rules or parents changed since checkout do not affect them.

Nuvion then confirms each transfer with an outflows.completed (or outflows.failed) event.

Statuses

StatusMeaning
pendingCheckout created and the split fixed as pending legs, nothing received yet
receivedInflow confirmed, not executing yet
splittingAt least one leg has been sent and not all are confirmed
settledEvery leg completed
partialAt least one leg failed. Retry it
refund_partialA refund started and some reversal legs are still outstanding
refundedRefund finished: every reversal completed

Legs have their own states (pending, sent, completed, failed, cancelled) and a kind (split or reversal). See Statuses.

Reading payments

The plugin stores payments in nuvionPayment and legs in nuvionLeg (see the schema). It does not expose list endpoints yet; read them through your Better Auth adapter or database, scoped to the organizations the user administers. The example app shows one way to do it.

On this page