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:
- reads the receiving account (
GET /accounts/{id}) for itsnuvion_banand currency, - creates a business counterparty on the sending entity (
POST /counterparties), named after the receiving organization, - attaches a
book-transferpayment detail (POST /payment-details), - saves both ids in
nuvionDestinationand 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
4xxis a definitive rejection, a network error or5xxis 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.