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:
- verifies the webhook signature,
- finds the payment by the reference in the event,
- checks the amount equals the quoted
chargedMinor(a different amount is not split), - 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
| Status | Meaning |
|---|---|
pending | Checkout created, nothing received yet |
received | Inflow confirmed, legs computed, not executing yet |
splitting | At least one leg has been sent and not all are confirmed |
settled | Every leg completed |
partial | At least one leg failed. Retry it |
refund_partial | A refund started and some reversal legs are still outstanding |
refunded | Refund 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.