Distribute Payments to Marketplace Sellers via Transfers

Create fund transfers and transfer reversals between your marketplace platform and seller accounts using the Marketplace transfers module.

After collecting payments, use marketplace.transfers to distribute funds from the platform account to connected accounts. The public methods are sendFunds() and createTransferReversal().

Consider subscribing to webhook events via marketplace.webhooks and creating transfers only after your platform has confirmed the payment state.

Send funds to a connected account

Call marketplace.transfers.sendFunds(transferData) with the connected account ID and amount to transfer. Use the MPTransfersDatas type to keep the payload aligned with the SDK.

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

const transferData: MPTransfersDatas = {
  connectedAccountId: 'connected-account-id',
  amount: 4500,
  transactionId: 'transaction-id-from-payment',
  description: 'Seller payout for order #789',
};

const result = await marketplace.transfers.sendFunds(transferData);

if (result.success) {
  console.log('Transfer ID:', result.data.transferId);
  console.log('Executed at:', result.data.executed);
}

The platform retains any difference between the collected payment amount and the amount transferred, for example a marketplace commission or platform fee.

transactionId is optional in MPTransfersDatas. When it is omitted, or when the transaction is already settled, VivaWallet can execute an instant balance transfer if the platform account has enough available balance.

Create a transfer reversal

A transfer reversal moves funds back from a connected account to the platform account. Use this when you need to reverse a seller payout because of a refund, dispute, or operational adjustment.

createTransferReversal() takes the original transfer ID as the first argument and an optional options object as the second argument.

const result = await marketplace.transfers.createTransferReversal(
  'original-transfer-id',
  {
    amount: 4500, // Omit or pass null to reverse the full transfer
  }
);

if (result.success) {
  console.log('Reversal transfer ID:', result.data.transferId);
}

You can reverse a transfer partially by passing an amount smaller than the original transfer value.

Cancel a Marketplace transaction

Use marketplace.transactions.cancelTransaction(transactionId, refundOptions) to cancel or refund a Marketplace transaction. This method is separate from transfer reversal: transaction cancellation handles the payment transaction, while transfer reversal handles funds that were already sent to a connected account.

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

const refundOptions: MPTransactionCancelOptions = {
  amount: 5000,
  reverseTransfers: true,
  refundPlatformFee: true,
};

const result = await marketplace.transactions.cancelTransaction(
  'transaction-id',
  refundOptions
);

if (result.success) {
  console.log('Cancelled transaction:', result.data.transactionId);
}

When reverseTransfers is true, VivaWallet can return the proportional connected-account funds to the platform account as part of the refund flow. Use createTransferReversal() manually when you need a standalone transfer reversal.