Marketplace Payment Orders: Accept Payments for Sellers

Create and retrieve Marketplace payment orders for your platform. Collect buyer payments and route funds to sellers using the payments module.

The Marketplace client’s payments module creates payment orders under your platform account. Once the buyer completes payment, your platform can distribute funds to connected accounts with marketplace.transfers.sendFunds().

Initialize the Marketplace client

Instantiate the Marketplace client with your platform’s OAuth credentials and merchant Basic Auth details. All modules — source, payments, sellers, transfers, transactions, and webhooks — are available as properties on this single instance.

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

const marketplace = new Marketplace({
  clientId: 'your-smartcheckout-client-id',
  clientSecret: 'your-smartcheckout-client-secret',
  merchantId: 'your-merchant-uuid',
  apikey: 'your-api-key',
});

Create a Marketplace payment order

Call marketplace.payments.createOrder(orderData) with the buyer details and order amount. On success, the response includes an orderCode you use to redirect the buyer to SmartCheckout.

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

const result = await marketplace.payments.createOrder({
  amount: 5000,
  customerTrns: 'Marketplace Order #789',
  customer: {
    email: '[e-mail]',
    fullName: 'Alice Buyer',
    phone: '[phone]',
    requestLang: 'en-GB',
  },
});

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

const checkoutUrl = getSmartCheckout({
  orderCode: String(result.data.orderCode),
});

// Redirect the buyer to the SmartCheckout hosted payment page.

The Marketplace order payload extends the standard payment order payload. When you already know the connected account split at order creation time, you can include the optional transfer object supported by MPOrdersOptions.

const result = await marketplace.payments.createOrder({
  amount: 5000,
  customerTrns: 'Marketplace Order #789',
  transfer: {
    connectedAccountId: 'connected-account-id',
    amount: 4500,
    platformFee: 500,
  },
});

Cancel an unpaid Marketplace order

marketplace.payments.cancelOrder() is available through the shared payment-order cancellation helper. It takes the order code directly.

const cancelResult = await marketplace.payments.cancelOrder(String(orderCode));

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

Marketplace webhooks

Subscribe to VivaWallet events using marketplace.webhooks so your platform is notified when payments complete or fail. Use these notifications to trigger downstream actions such as fund transfers to connected accounts.

const subscriptionResult = await marketplace.webhooks.addSubscription({
  url: 'https://yourplatform.com/webhooks/viva',
  secret: process.env.VIVA_WEBHOOK_SECRET!,
  events: ['SaleTransactionsFileGenerated'],
});

You can retrieve your webhook verification key at any time:

const keyResult = await marketplace.webhooks.retrieveWebhookKey();

if (keyResult.success) {
  console.log('Webhook key:', keyResult.data);
}

After a payment is completed, use marketplace.transfers.sendFunds() to distribute funds to the appropriate connected account. See the Transfers guide for details.