Skip to Content
better-auth-nuvion

Counterparties

The Nuvion counterparty and payment detail each book transfer needs, created for you on first use or ahead of time.

A Nuvion book transfer moves money between two Nuvion accounts. Before the sending entity can transfer to another account, Nuvion needs a counterparty for the recipient and a book-transfer payment detail whose account_number is the recipient's nuvion_ban. Counterparties belong to the sending entity, so every (source, destination) pair needs its own.

You do not have to create these. The plugin does it.

On first use

The first time a transfer needs a pair that does not exist yet, the plugin:

  1. reads the receiving account (GET /accounts/{id}) for its nuvion_ban and currency,
  2. creates a business counterparty on the sending entity (POST /counterparties), named after the receiving organization,
  3. attaches a book-transfer payment detail (POST /payment-details),
  4. saves both ids in nuvionDestination and carries on with the transfer.

The same thing happens for the reverse pair (parent to child) the first time a refund needs it. Later transfers reuse the saved ids.

Ahead of time

Creating them on the first transfer means a problem would show up as a failed leg after a customer has already paid. Provision earlier instead:

const { data } = await authClient.nuvion.organization.destinations({
  organizationId: merchant.id,
});
// { results: [
//   { toOrganizationId: "org_reseller", status: "ready" },
//   { toOrganizationId: "org_platform", status: "error", message: "the paying and receiving organizations use the same Nuvion account; ..." },
// ] }

It prepares the organization's splits (it to each ancestor) and reports each pair as ready or error. Calling it again reuses pairs that exist. You must be an owner or admin of the organization.

Contact details

Nuvion requires an email and an address on a counterparty. Set the ones to use with the counterparty option:

nuvion({
  // ...
  counterparty: {
    email: "payments@your-platform.example",
    relationship: "supplier",
    address: { line1: "1 High Street", city: "London", country: "GB", postal_code: "EC1A 1BB" },
  },
});

The defaults are placeholders

Without the option, counterparties are created with book-transfers@counterparty.invalid and an address of "Not provided". Nuvion accepts them in the sandbox. Set real values before you go live.

Requirements and limits

  • Different accounts. Both organizations must be bound, to different Nuvion accounts. The same account is rejected before anything is created.
  • Currency. The payment detail takes the currency of the receiving account.
  • Failures are classified like any provider call: a Nuvion 4xx is a definitive rejection, a network error or 5xx is ambiguous and is retried.
  • Unused records. If creation fails after the counterparty exists but before its payment detail does, or two first transfers for the same pair run at once, the retry can leave an unused counterparty in Nuvion. This is harmless. Re-provisioning a pair after losing the saved row simply creates another counterparty; Nuvion does not reject it as a duplicate.

On this page