Manage Marketplace Seller Accounts and Payout Settings

Onboard, update, and configure connected seller accounts on your marketplace platform using the Marketplace sellers module and connected account types.

Sellers on your marketplace are represented as connected accounts. Use marketplace.sellers to create connected accounts, retrieve their onboarding state, and update payout-related account settings.

Create a seller account

Call marketplace.sellers.createAccount(accountData) with the seller’s business details. The MPCreateAccountDatas type includes email, return URL, branding, address, and optional payout settings.

import type { MPCreateAccountDatas } from '@nkhind/vivawallet-sdk';

const accountData: MPCreateAccountDatas = {
  email: '[e-mail]',
  returnUrl: 'https://yourplatform.com/sellers/onboarding-return',
  branding: {
    partnerName: 'Your Marketplace',
    logoUrl: 'https://yourplatform.com/logo.png',
    primaryColor: '000000',
  },
};

const result = await marketplace.sellers.createAccount(accountData);

if (!result.success) {
  console.error(result.message);
  return;
}

console.log('Connected account ID:', result.data.accountId);
console.log('Invitation URL:', result.data.invitation.redirectUrl);

Store the returned accountId. You will use it with marketplace.sellers.retrieveConnectedAccount(), marketplace.sellers.updateConnectedAccount(), and marketplace.transfers.sendFunds().

Retrieve a seller account

Retrieve a connected account profile with retrieveConnectedAccount(accountId). This is useful for displaying seller details in your dashboard or checking onboarding and acquiring status.

const result = await marketplace.sellers.retrieveConnectedAccount(
  'connected-account-id'
);

if (result.success) {
  const account = result.data;
  console.log('Verified:', account.verified);
  console.log('Can accept payments:', account.acquiringEnabled);
}

Update a seller account

Use updateConnectedAccount(accountId, options) to update mutable connected-account attributes. MPUpdateConnectedAccountOptions currently focuses on payout settings.

import type { MPUpdateConnectedAccountOptions } from '@nkhind/vivawallet-sdk';

const options: MPUpdateConnectedAccountOptions = {
  payouts: {
    interval: 2, // weekly
    dayOfWeek: 2, // monday
    bankAccount: {
      iban: 'GR1601101250000000012300695',
      beneficiaryName: 'Seller Legal Name',
    },
  },
};

const result = await marketplace.sellers.updateConnectedAccount(
  'connected-account-id',
  options
);

if (!result.success) {
  console.error(result.message);
}

Payout settings

Payout configuration is part of the connected-account create or update payload. The SDK exposes these Marketplace payout types:

Type	Purpose
MPCreateConnectedAccountPayouts	Required payout shape when configuring payouts during account creation.
MPConnectedAccountPayouts	Payout shape returned by VivaWallet or used during account updates.
MPPayoutInterval	Numeric payout interval: 1 daily, 2 weekly, 3 monthly.
MPPayoutDayOfWeek	Numeric day of week: 1 sunday through 7 saturday.

const accountData: MPCreateAccountDatas = {
  email: '[e-mail]',
  returnUrl: 'https://yourplatform.com/sellers/onboarding-return',
  branding: {
    partnerName: 'Your Marketplace',
    logoUrl: 'https://yourplatform.com/logo.png',
  },
  payouts: {
    interval: 2,
    dayOfWeek: 2,
    bankAccount: {
      iban: 'GR1601101250000000012300695',
      beneficiaryName: 'Seller Legal Name',
    },
  },
};

Seller onboarding

createAccount() returns an invitation object with a redirectUrl. Send this URL to the seller so they can complete VivaWallet onboarding.

if (result.success) {
  await emailSeller(result.data.invitation.redirectUrl);
}

Track completion by polling marketplace.sellers.retrieveConnectedAccount(accountId) and checking fields such as verified and acquiringEnabled, or by listening to connected-account webhook events via marketplace.webhooks.