Manage transfer fees and payouts

How to manage transfer fees and payouts.

Overview

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

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 an 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:

Demo Browser address bar

Production 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

This API call uses Basic authentication.

post    /api/wallets/{platform account wallet ID}/balancetransfer/{marketplace wallet ID}

Run in Postman

Environment URL
Production https://www.vivapayments.com/api/wallets/{platform account wallet ID}/balancetransfer/{marketplace wallet ID}
Demo https://demo.vivapayments.com/api/wallets/{platform account wallet ID}/balancetransfer/{marketplace wallet ID}
curl '[Environment URL]'
-H 'Content-Type: application/json'
-H 'Authorization: Basic [Base64-encoded Merchant ID and API Key (platform account)]'
-d '{
  "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 => '[Environment URL]',
  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;

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

This API call uses Basic authentication.

post    /api/wallets/{platform account wallet ID}/balancetransfer/{seller A wallet ID}

Run in Postman

Environment URL
Production https://www.vivapayments.com/api/wallets/{platform account wallet ID}/balancetransfer/{seller A wallet ID}
Demo https://demo.vivapayments.com/api/wallets/{platform account wallet ID}/balancetransfer/{seller A wallet ID}
curl '[Environment URL]'
-H 'Content-Type: application/json'
-H 'Authorization: Basic [Base64-encoded Merchant ID and API Key (platform account)]'
-d '{
  "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 => '[Environment URL],
  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;

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

This API call uses Basic authentication.

post    /api/wallets/{platform account wallet ID}/balancetransfer/{seller B wallet ID}

Run in Postman

Environment URL
Production https://www.vivapayments.com/api/wallets/{platform account wallet ID}/balancetransfer/{seller B wallet ID}
Demo https://demo.vivapayments.com/api/wallets/{platform account wallet ID}/balancetransfer/{seller B wallet ID}
curl '[Environment URL]'
-H 'Content-Type: application/json'
-H 'Authorization: Basic [Base64-encoded Merchant ID and API Key (platform account)]'
-d '{
  "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 => '[Environment URL]',
  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;

Example response

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

Get Support

If you would like to integrate with Viva Wallet, or if you have any queries about our products and solutions, please see our Get Support page to see how we can help!