Navigation:

Manage transfer fees and payouts

How to manage transfer fees and payouts.

Overview
Pre-requisites
- Allow transfers
- Find IDs
  - connectedAccountId
  - transactionId
Process
Example requests
Get Support

Overview

When using the Marketplace schema, acquiring takes place on the Platform account, which acts as a holding account between end users, sellers and the marketplace owner.

The process to transfer funds and fees from this Platform account to the sellers’ and marketplace owner’s accounts can differ, depending on your business needs.

There are two main use cases:

Manual transfers
Automatic transfers

Pre-requisites

Before getting started, please take a look at the below pre-requisites to ensure you are ready to begin transfers:

Allow transfers
Find IDs

Allow transfers

Firstly, please ensure that you enable transfers between accounts in the Viva Wallet banking app (for the platform account only). To do this:

Log in to Viva Wallet, demo or live , and select the required account
Go to Settings > API Access
Ensure the Allow transfers between accounts checkbox is checked, as shown below:

Find IDs

In order to perform marketplace transfers, you will need to specify certain IDs, namely:

connectedAccountId
transactionId

connectedAccountId

The connectedAccountId refers to the account ID of the seller and marketplace owner accounts which are connected to the Platform account.

This account ID can be found within the response of the Create a connected account API call used to create the connected account, or from within the connected account’s self-care.

transactionId

The transactionID refers to the individual transaction (i.e. customer payment) which relates to the transfer being performed.

This can be found within the redirect URL after a successful payment or within the Transaction Payment Created webhook.

Process

The marketplace transfer process varies depending on your use case:

Use Case A - manual transfers (online customer payments)
Use Case B - automatic transfers (online customer payments)
Use Case C - manual transfers (in-store customer payments)

Use Case A - manual transfers (online customer payments

In this scenario, the allocation of funds is specified after the customer payment.

Please note:

The manual transfer process supports both single-seller and multiple-seller transactions (orders with items from single or multiple sellers)
The associated customer payment must be specified, to aid with reconciliation and to ensure availability of funds to perform the funds transfers. The transfers will then be executed when the payment is settled

Please see below for a simplified diagram of the flow: Marketplace transfers - manual

The process for manual transfers is as follows:

1. Acquiring is performed on the Platform account via a customer payment. In this particular example, we will refer to a payment in which the customer has purchased items from multiple sellers (Seller 1 & Seller 2) [see example request]

2. You will then need to calculate the split of funds between Seller 1, Seller 2 and the Marketplace Owner (for the marketplace fees)

3. Next, manually transfer funds to the different sellers via API, specifying the associated customer payment with the transactionId parameter. In this example, you would transfer £55 to Seller 1 and £35 to Seller 2 [see example request]

4. Viva Wallet’s acquiring commission is applied for the transaction and deducted from the platform account

5. Lastly, after the settlement process has taken place, funds transfers from the platform account to the marketplace owner can be executed in batches (rather than on a per-payment basis), using the same API, but this time ensuring the transactionId parameter is left empty. Please bear in mind Viva Wallet’s acquiring fee, which should be taken into consideration when determining how much money is available to transfer from the platform account to the marketplace owner’s account [see example request]

Use Case B - automatic transfers (online customer payments)

In this scenario, the allocation of funds is specified before the customer payment.

Please note:

The automatic transfer process supports only single-seller transactions (orders with items from single seller)
The amount transferred to the seller is either specified explicitly by indicating the actual amount to be sent to the seller, or specified implicitly by indicating the commission of the marketplace owner
The benefit of automatic transfers over manual transfers is that it provides a simple, automatic transfer to the seller, removing the need to perform this manually

Please see below for two simplified diagrams of the flow, depicting the difference between using either the amount or the platformFee parameter within the create a marketplace payment order API: Marketplace transfers - automatic - 1

The process for automatic transfers is as follows:

1. Acquiring is performed on Platform account via a marketplace customer payment, with the transfer parameter of the payment order being used to specify which connected seller account to transfer funds to, as well as how much to be transferred

If using the amount parameter, one transaction will be made (funds from Platform to Seller); if using the platformFee parameter, two transactions will be made (funds from Platform to Seller and fee from Seller back to Platform - giving more fees visibility to the seller) [see example request]

2. Upon settlement of the payment, the funds transfer to the seller is then triggered automatically

3. Viva Wallet’s acquiring commission is applied for the transaction and deducted from the platform account

4. Lastly, after the settlement process has taken place, funds transfers from the platform account to the marketplace owner can be executed in batches (rather than on a per-payment basis), using the transfer funds API, ensuring the transactionId parameter is left empty. Please bear in mind Viva Wallet’s acquiring fee, which should be taken into consideration when determining how much money is available to transfer from the platform account to the marketplace owner’s account [see example request]

Use Case C - manual transfers (in-store customer payments)

In this scenario, the allocation of funds is specified after the customer payment.

Please note:

The manual transfer process supports both single-seller and multiple-seller transactions (orders with items from single or multiple sellers)
The associated customer payment must be specified, to aid with reconciliation and to ensure availability of funds to perform the funds transfers. The transfers will then be executed when the payment is settled

Please see below for a simplified diagram of the flow: Marketplace transfers - manual

The process for manual transfers is as follows:

1. Acquiring is performed within the POS device or app (either standalone, via inter-app integration or via Cloud REST API integration)

2. If the payment relates to multiple sellers, you will then need to calculate the split of funds between Seller 1, Seller 2 and the Marketplace Owner (for the marketplace fees)

4. Viva Wallet’s acquiring commission is applied for the transaction and deducted from the platform account

Create payment order

Environment	Method	URL
Production	POST	https://demo-api.vivapayments.com/checkout/v2/orders
Demo	POST	https://api.vivapayments.com/checkout/v2/orders

curl --location --request POST 'https://demo-api.vivapayments.com/checkout/v2/orders' \
--header 'Content-Type: application/json' \
--data-raw '{
 "amount": 1,
 "customerTrns": "string",
 "customer": {"email": "","fullName": "","phone": "","countryCode": "","requestLang": ""},
 "paymentTimeout": 0,
 "preauth": true,
 "allowRecurring": true,
 "maxInstallments": 0,
 "paymentNotification": true,
 "tipAmount": 1,
 "disableExactAmount": true,
 "disableCash": false,
 "disableWallet": false,
 "sourceCode": "Default",
 "merchantTrns": "string",
 "tags": ["tag 1","tag 2"],
 "paymentMethodFees": [{"paymentMethodId": "35","fee": 250}],
 "cardTokens": ["ct_5d0a4e3a7e04469f82da228ca98fd661"]
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/checkout/v2/orders',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
 "amount": 1,
 "customerTrns": "string",
 "customer": {"email": "","fullName": "","phone": "","countryCode": "","requestLang": ""},
 "paymentTimeout": 0,
 "preauth": true,
 "allowRecurring": true,
 "maxInstallments": 0,
 "paymentNotification": true,
 "tipAmount": 1,
 "disableExactAmount": true,
 "disableCash": false,
 "disableWallet": false,
 "sourceCode": "Default",
 "merchantTrns": "string",
 "tags": ["tag 1","tag 2"],
 "paymentMethodFees": [{"paymentMethodId": "35","fee": 250}],
 "cardTokens": ["ct_5d0a4e3a7e04469f82da228ca98fd661"]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response

{
  "orderCode": 7568594363572609
}

Create marketplace payment order

Environment	Method	URL
Production	POST	https://demo-api.vivapayments.com/checkout/v2/orders/
Demo	POST	https://api.vivapayments.com/checkout/v2/orders/

curl --location --request POST 'https://demo-api.vivapayments.com/checkout/v2/orders/' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 0,
  "preauth": false,
  "tipAmount": null,
  "disableCash": false,
  "disableCard": false,
  "tags": null,
  "sourceCode": null,
  "disableWallet": false,
  "paymentTimeout": 1800,
  "currencyCode": 978,
  "customerTrns": null,
  "merchantTrns": null,
  "allowRecurring": false,
  "maxInstallments": 0,
  "disableExactAmount": false,
  "paymentNotification": false,
  "customer": {
    "email": "example@example.com",
    "phone": "01234567890",
    "fullName": "John Doe",
    "countryCode": "GB",
    "requestLang": null
  },
  "forceMaxInstallments": false,
  "cardTokens": [
    "ct_5d0a4e3a7e04469f82da228ca98fd661"
  ],
  "transfer": {
    "amount": 1000,
    "platformFee": 10,
    "connectedAccountId": "ac03972a-5ca5-43c5-b96f-c519ac843b7a"
  }
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/checkout/v2/orders/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "amount": 0,
  "preauth": false,
  "tipAmount": null,
  "disableCash": false,
  "disableCard": false,
  "tags": null,
  "sourceCode": null,
  "disableWallet": false,
  "paymentTimeout": 1800,
  "currencyCode": 978,
  "customerTrns": null,
  "merchantTrns": null,
  "allowRecurring": false,
  "maxInstallments": 0,
  "disableExactAmount": false,
  "paymentNotification": false,
  "customer": {
    "email": "example@example.com",
    "phone": "01234567890",
    "fullName": "John Doe",
    "countryCode": "GB",
    "requestLang": null
  },
  "forceMaxInstallments": false,
  "cardTokens": [
    "ct_5d0a4e3a7e04469f82da228ca98fd661"
  ],
  "transfer": {
    "amount": 1000,
    "platformFee": 10,
    "connectedAccountId": "ac03972a-5ca5-43c5-b96f-c519ac843b7a"
  }
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response

{
  "orderCode": 1234567890123456
}

Send funds to a connected account

Environment	Method	URL
Production	POST	https://api.vivapayments.com/platforms/v1/transfers
Demo	POST	https://demo-api.vivapayments.com/platforms/v1/transfers

curl --location --request POST 'https://demo-api.vivapayments.com/platforms/v1/transfers' \
--header 'Authorization: Bearer Token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 10,
  "connectedAccountId": "ac03972a-abcd-43c5-b96f-c519acabcdef",
  "transactionId": null
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/platforms/v1/transfers',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "amount": 10,
  "connectedAccountId": "ac03972a-abcd-43c5-b96f-c519acabcdef",
  "transactionId": null
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer Token',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response

{
  "transferId": "fa176a3b-a7e8-4f3d-abe6-5e65626f5994",
  "executed": "2023-02-14T15:53:02.514Z"
}

Cloud REST API - Sales Request

Environment	Method	URL
Production	POST	https://api.vivapayments.com/ecr/v1/transactions:sale
Demo	POST	https://demo-api.vivapayments.com/ecr/v1/transactions:sale

curl --location 'https://demo-api.vivapayments.com/ecr/v1/transactions:sale' \
--header 'Authorization: Bearer Bearer_Token' \
--header 'Content-Type: application/json' \
--data '{
"sessionId": "4bdebe62-c211-4ca0-a994-b2fbea2061c5",
"terminalId": 16000010,
"cashRegisterId": "XDE384678UY",
"amount": 1170,
"currencyCode": 978,
"merchantReference": null,
"preauth": false,
"maxInstalments": 0,
"tipAmount": 0
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/ecr/v1/transactions:sale',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
"sessionId": "4bdebe62-c211-4ca0-a994-b2fbea2061c5",
"terminalId": 16000010,
"cashRegisterId": "XDE384678UY",
"amount": 1170,
"currencyCode": 978,
"merchantReference": null,
"preauth": false,
"maxInstalments": 0,
"tipAmount": 0
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer Bearer_Token',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response

{
  "Message": "Successful Response."
}

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 Contact & Support page to see how we can help!