Transfer fees and payouts (marketplace)

Let us consider the case of a customer who has completed 1 purchase including items from 2 sellers (seller A and seller B), with the total value of the purchase being 100€, which consists of 10€ marketplace fees, 50€ seller payout to seller A and 40€ seller payout to seller B.

Thus, in order to transfer the fees and the payouts, the following payment flows need to be processed:

  1. Transfer of marketplace fees (10€) from platform account to marketplace
  2. Transfer of seller payout (50€) from platform account to seller A
  3. Transfer of seller payout (40€) from platform account to seller B

The below examples use basic auth for authentication.

On this page:

Allow transfers

You also have to ensure that you enable transfers between accounts in the Viva Wallet banking app (for the platform account only). To do this:

  1. Log in to Viva Wallet, demo or live , and select the required account.

  2. Go to Settings > API Access.

  3. Select the Allow transfers between accounts checkbox as shown below:

    Allow transfers between accounts
    The new setting is saved automatically.

Find wallet IDs

The wallet IDs of a platform account, marketplace or seller account can be found in the Viva Wallet banking app as follows:

  1. Log in to Viva Wallet, demo or live , and select the required account.

  2. Click on Accounts in the left navigation.
    The wallet IDs are those indicated below in the Account ID column:

    Find wallet IDs
    You may have only the Primary wallet or have additional wallets set up for specific purposes.

Find transaction IDs

The transaction IDs generated after payment can be found as follows:

Smart Checkout

You can find the transaction ID in the URL displayed in the browser address bar after redirection to the Success URL:

Browser address bar

Balance Transfer: Request information

post    /api/wallets/{walletId}/balancetransfer/{targetWalletId}

The required and optional fields for the request are shown in the table below.

Parameter Description Type Importance
walletId Source ID of the wallet from which you wish to make the transfer. Displayed as Account ID under Accounts in the Viva Wallet banking app. long Required
targetWalletId Destination ID of the wallet to which you wish to make the transfer. Displayed as Account ID under Accounts in the Viva Wallet banking app. long Required
amount Transfer amount in the smallest denomination of your account currency. long Required
description Some text to summarize the transfer reason. Appears on target account statement. string Optional
saleTransactionId The Viva Wallet transaction ID generated during checkout (as a reference only). GUID Optional

Step 1: Transfer of marketplace fees (10€) from platform account to marketplace

For this example you need first to find the wallet IDs of your platform account and marketplace account. The marketplace owner has access to both the platform account and marketplace account, so it is straightforward to find the IDs for these wallets.

Example request

curl -L -X POST 'https://demo.vivapayments.com/api/wallets/{platform account wallet ID}/balancetransfer/{marketplace wallet ID}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic [Base64-encoded Merchant ID and API Key (platform account)]' \
--data-raw '{
  "amount": "1000",
  "description": "[Optional text to show on account statement]",
  "saleTransactionId": "[Optional transaction ID for the related sale]"
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/wallets/{platform account wallet ID}/balancetransfer/{marketplace wallet ID},
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "amount": "1000",
  "description": "[Optional text to show on account statement]",
  "saleTransactionId": "[Optional transaction ID for the related sale]"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic [Base64-encoded Merchant ID and API Key (platform account)]'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Run in Postman

Example response

{
    "DebitTransactionId": "b8ff48b5-a2ac-4c95-a4fe-f4c1c9f5741b", //refers to platform account
    "CreditTransactionId": "9a85d019-6ec6-4e27-be45-84ef320b8d3e" //refers to marketplace account
}

Step 2: Transfer of seller payout (50€) from platform account to seller A

For this example you need first to find the wallet IDs of your platform account and the account of seller A. The marketplace owner has access to the platform account, so it is straightforward to find the ID for the platform account wallet. However, he needs to ask for the seller wallet ID from the seller.

Example request

curl -L -X POST 'https://demo.vivapayments.com/api/wallets/{platform account wallet ID}/balancetransfer/{seller A wallet ID}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic [Base64-encoded Merchant ID and API Key (platform account)]' \
--data-raw '{
  "amount": "5000",
  "description": "[Optional text to show on account statement]",
  "saleTransactionId": "[Optional transaction ID for the related sale]"
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/wallets/{platform account wallet ID}/balancetransfer/{seller A wallet ID},
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "amount": "5000",
  "description": "[Optional text to show on account statement]",
  "saleTransactionId": "[Optional transaction ID for the related sale]"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic [Base64-encoded Merchant ID and API Key (platform account)]'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Run in Postman

Example response

{
    "DebitTransactionId": "ad1a348f-c6f5-47c4-8e2a-7cb68eab1e6a", //refers to platform account
    "CreditTransactionId": "ec4b3a7e-5e03-4c58-b163-741e45d80121" //refers to seller account
}

Step 3: Transfer of seller payout (40€) from platform account to seller B

For this example you need first to find the wallet IDs of your platform account and the account of seller B. The marketplace owner has access to the platform account, so it is straightforward to find the ID for the platform account wallet. However, they need to ask for the seller wallet ID from the seller.

Example request

curl -L -X POST 'https://demo.vivapayments.com/api/wallets/[platform account wallet ID]/balancetransfer/[seller B wallet ID]' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic [Base64-encoded Merchant ID and API Key (platform account)]' \
--data-raw '{
  "amount": "4000",
  "description": "[Optional text to show on account statement]",
  "saleTransactionId": "[Optional transaction ID for the related sale]"
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/wallets/{platform account wallet ID}/balancetransfer/{seller B wallet ID},
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "amount": "4000",
  "description": "[Optional text to show on account statement]",
  "saleTransactionId": "[Optional transaction ID for the related sale]"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic [Base64-encoded Merchant ID and API Key (platform account)]'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Run in Postman

Example response

{
    "DebitTransactionId": "7c588733-3531-4df1-bcb5-1cdf70ce239a", //refers to platform account
    "CreditTransactionId": "5ffc4758-102d-4108-b3bf-bf7a867f7fc9" //refers to seller account
}