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

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, 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. creates one leg per parent and executes them as book transfers from the merchant's account.

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

Statuses

StatusMeaning
pendingCheckout created, nothing received yet
receivedInflow confirmed, legs computed, 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