Testing your integration
Test your splits, hooks and webhook route without calling Nuvion, using the engine's in-memory store and a fake provider.
You can test most of your integration with no network and no Nuvion account. Two pieces make that possible: the engine, which holds the split logic and is usable on its own, and the plugin's webhook route, which you can call with a request you sign yourself.
The examples use Node's built-in test runner. Any runner works.
Test the split and your hooks
The engine takes a store and a provider. Use MemoryStore for the store and a few lines of your own for the provider, so your test decides what Nuvion "answers".
import { test } from "node:test";
import assert from "node:assert/strict";
import {
MemoryStore,
SplitService,
type PaymentProvider,
type TransferRequest,
} from "@umohpyro/better-auth-nuvion/engine";
// A fake rail: records the transfers and always accepts them.
const sent: TransferRequest[] = [];
const provider: PaymentProvider = {
createCheckout: async (r) => ({
sessionId: "fs_1",
checkoutUrl: `https://checkout.test/${r.reference}`,
}),
transfer: async (t) => {
sent.push(t);
return { providerRef: `tr_${sent.length}` };
},
};
test("a payment splits to the parents and settles", async () => {
const store = new MemoryStore();
store.parents.set("merchant", "platform").set("platform", null);
store.rules.set("merchant", {
organizationId: "merchant",
flatMinor: 0,
bps: 300,
bearer: "merchant",
}); // the platform takes 3%
const settled: string[] = [];
const svc = new SplitService(
store,
provider,
{
onPaymentSettled: async ({ payment }) => {
settled.push(payment.id);
},
},
{ confirm: false },
);
const { payment } = await svc.createPayment({
organizationId: "merchant",
baseMinor: 10_000,
currency: "GBP",
redirectUrl: "https://x.test/done",
});
await svc.onInflowCompleted({
eventId: "evt_1",
reference: payment.reference,
amountMinor: 10_000,
currency: "GBP",
});
assert.deepEqual(
sent.map((t) => [t.toOrganizationId, t.amountMinor]),
[["platform", 300]],
);
for (const leg of await store.legsOf(payment.id)) {
await svc.onTransferEvent({
eventId: `evt_${leg.id}`,
reference: `${leg.id}-a${leg.attempt}`,
ok: true,
});
}
assert.equal((await store.getPayment(payment.id))?.status, "settled");
assert.deepEqual(settled, [payment.id]);
});{ confirm: false } skips the "ask Nuvion first" step, because your fake provider has no funding session to look up. To test that step, add confirmInflow to the fake and return "confirmed", "not-settled" or "mismatch".
To test a failure, make transfer throw new ProviderError("rejected", "insufficient funds") (exported from the same entry point). The payment then becomes partial, and svc.executeLegs(paymentId) (what the retry endpoint calls) sends the failed share again with a new reference.
Test the webhook route
The route lives inside the Better Auth handler, so you can call auth.handler with a Request. Nuvion signs each delivery with HMAC-SHA256 over <timestamp>.<raw body>; do the same in the test.
import { createHmac } from "node:crypto";
import { test } from "node:test";
import assert from "node:assert/strict";
import { auth } from "../lib/auth";
const SECRET = process.env.NUVION_WEBHOOK_SECRET!;
// Build a request signed the way Nuvion signs it.
function delivery(body: object, secret = SECRET) {
const raw = JSON.stringify(body);
const ts = new Date().toISOString();
const signature = createHmac("sha256", secret)
.update(`${ts}.${raw}`)
.digest("hex");
return new Request("http://localhost:3000/api/auth/nuvion/webhook", {
method: "POST",
headers: {
"content-type": "application/json",
"x-nuvion-event-id": `evt_${Date.now()}`,
"x-nuvion-event-timestamp": ts,
"x-nuvion-event-signature": signature,
},
body: raw,
});
}
const inflow = {
event: "inflows.completed",
data: { unique_reference: "pay_unknown", amount: 100, currency: "GBP" },
};
test("a wrong signature is refused", async () => {
assert.equal(
(await auth.handler(delivery(inflow, "nv_wsk_wrong"))).status,
401,
);
});
test("a signed event for a payment we do not have is acknowledged and ignored", async () => {
const res = await auth.handler(delivery(inflow));
assert.equal(res.status, 200);
assert.equal((await res.json()).status, "unknown-payment");
});Run these against a throwaway database (a SQLite file you create with the migration is enough). With confirmEvents on, an event for a payment that exists would make the plugin call Nuvion to confirm it. For a full test of that path, point baseUrl at a small fake server, or use the test environment (Local development).
What to test
- Your hooks: that
onPaymentSettledis safe to run twice, and thatonRefundedundoes what you granted. - Your fee rules: with
quote(Recipes), which is pure and fast. - Your webhook mounting: that a bad signature gets
401, so a proxy or body parser did not break the raw body (Troubleshooting). - One real payment in the test environment before you go live, with a webhook through a tunnel.
The plugin's own tests cover the split, retries, refunds, de-duplication and confirm logic. You do not need to repeat them.
Local development
Run the plugin on your machine against the Nuvion test environment, receive real webhooks through a tunnel, and complete the sandbox bank step.
Troubleshooting
What you see, why it happens and how to fix it, for a stuck payment, a webhook that fails, and the errors the plugin returns.