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 escrow to marketplace
  2. Transfer of seller payout (50€) from escrow to seller A
  3. Transfer of seller payout (40€) from escrow to seller B

The below examples use basic auth for authentication.

Allow transfers

You also have to ensure that you enable transfers between accounts in the Viva Wallet banking app (for the escrow 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 an escrow, 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:

Redirect 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 escrow to marketplace

For this example you need first to find the wallet IDs of your escrow account and marketplace account. The marketplace owner has access to both the escrow 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/{escrow wallet ID}/balancetransfer/{marketplace wallet ID}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic [Base64-encoded Merchant ID and API Key (escrow 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/{escrow 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 (escrow account)]'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Run in Postman

Example response

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

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

For this example you need first to find the wallet IDs of your escrow account and the account of seller A. The marketplace owner has access to the escrow account, so it is straightforward to find the ID for the escrow 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/{escrow wallet ID}/balancetransfer/{seller A wallet ID}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic [Base64-encoded Merchant ID and API Key (escrow 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/{escrow 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 (escrow account)]'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Run in Postman

Example response

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

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

For this example you need first to find the wallet IDs of your escrow account and the account of seller B. The marketplace owner has access to the escrow account, so it is straightforward to find the ID for the escrow 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/[escrow wallet ID]/balancetransfer/[seller B wallet ID]' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic [Base64-encoded Merchant ID and API Key (escrow 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/{escrow 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 (escrow account)]'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Run in Postman

Example response

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