☰

Navigation:

Marketplaces

Find out how your marketplace (whether omni-channel, online only, or in-store only) can integrate with Viva Wallet.

Who can benefit from Viva Wallet’s marketplace solution?

In any of the above cases, you need to use our marketplace solution, in order to comply with PSD2. Customer payments are processed by Viva Wallet, which are in turn paid to the marketplace owner and the sellers through a platform account. It is a great solution for marketplace owners who need an efficient way to handle commission fees and seller payouts, while offering a multitude of payment methods and additional features to their customers.

Overview

The Viva Wallet marketplace solution allows for a simple payment process in situations in which a customer may purchase multiple items from multiple sellers. The customer makes one single payment, with all sellers and the marketplace owner being paid accordingly.

Our marketplace solution comprises four elements:

Features and benefits

There are a number of benefits to using our marketplace solution, including:

Process flow

With the Viva Wallet marketplace solution:

Marketplace

Setup guide

To use the Viva Wallet marketplace solution you need to perform the setup steps, as below.

Prior to the below steps, we strongly recommend that you initially set up and test payment flows between a test platform account, a test marketplace owner, and a test seller in the Demo environment, in order to make sure that the payout and refund flows are functioning properly before moving further with the implementation of a fully-fledged marketplace.

Set up your accounts

The first stage of the process is to set up and link the platform and marketplace owner accounts. This process differs, depending on the environment:

Demo
  1. Firstly, as the marketplace owner, you should sign up for a Viva Wallet account - this will be your platform account
  2. Then, provide your account details (such as the phone number used for sign-up) to Viva Wallet via your Sales representative or via the Live Chat option (which can be found at the bottom-right of the Developer Portal and main Viva Wallet site, or in your Production Viva Wallet self-care account)
  3. Viva Wallet will configure your platform account and provide you with the relevant credentials
  4. Once the platform account is ready, you need to connect it with a marketplace owner account. To do this, use the provided platform account credentials with the Create a connected account API, noting the accountId provided in the response (do not follow the redirectUrl, as this is not functional in the Demo environment):
    • If creating a new account, you will need to input this accountId in the ‘Connected account id’ field when signing up for an account
    • If linking an existing account, you will need to provide this accountId to Viva Wallet to connect the accounts

The same process (step 4, above) applies when creating connected Seller accounts in the Demo environment. This is also outlined in the blue Note box in the below Onboard sellers section.

All three accounts (Platform, Marketplace Owner & Seller) are required to complete testing in the Demo environment

Production
  1. Firstly, as the marketplace owner, you should sign up for a Viva Wallet account - this will be your marketplace owner account
  2. Then, provide your account details (such as the phone number used for sign-up) to Viva Wallet via your Sales representative or via the Live Chat option (which can be found at the bottom-right of the Developer Portal and main Viva Wallet site, or in your Production Viva Wallet self-care account)
  3. Viva Wallet will create your platform account and provide you with the relevant credentials
  4. Once the platform account is ready, you need to connect it with the marketplace owner account. To do this, use the provided platform account credentials with the Create a connected account API, follow the redirectUrl and complete the process to link the platform account with the marketplace owner account you created in step 1

Onboard sellers

Each seller needs to register for an account with Viva Wallet in order to function as a seller for the marketplace and to receive payouts

Please see the steps below, or refer to our Create a connected account tutorial for further details.

Important notes:

- A seller will not be able to receive any payouts until they are fully onboarded
- The marketplace solution does not support the onboarding of sellers with different currencies

The following steps are needed:

  1. The marketplace owner initiates the creation of a seller via API (seller invite) and receives an onboarding URL
  2. The marketplace owner then shares the onboarding URL with the seller to register with Viva Wallet
  3. The seller registers with Viva Wallet. Viva Wallet handles the entire process, with no action or input required by the marketplace owner

If completing this process in the Demo environment, the seller will not be able to follow the onboarding URL mentioned above, as the onboarding flow only applies to the Production environment. Instead, you will need to note the accountId provided in the response of the Create a connected account API call.

  • If creating a new account, the seller will need to input this accountId in the ‘Connected account id’ field when signing up for an account
  • If linking an existing account, you will need to provide this accountId to Viva Wallet to connect the accounts

Accept payments and make transfers

Depending on your business needs, there are different processes for accepting payments and subsequently transferring payouts to sellers and the marketplace owner.

Please see our use cases below, or refer to our Manage transfer fees and payouts tutorial for further details.

For use cases A and B (using online customer payments), you can integrate with our Smart Checkout solution to accept payments

Use Case A - manual transfers (online customer payments)

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

Process:

  1. Acquiring performed on platform account via customer payment
  2. Funds transfers to sellers are triggered manually after the payment, specifying the associated customer payment
  3. Viva Wallet’s acquiring commission is applied for the transaction and deducted from the platform account
  4. The funds transfer from the platform account to the marketplace owner must be executed manually, ensuring the transactionId parameter is left empty. These transfers should be made in ‘batches’ after the settlement process has taken place, rather than on a per-payment basis

Information:

Use Case B - automatic transfers (online customer payments)

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

Process:

  1. Acquiring performed on platform account via customer payment
  2. Funds transfers to sellers are triggered automatically by using the transfer parameter of the payment order.
    Please note: if using amount parameter, one transaction will be made (funds from Platform to Seller), if using 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)
  3. Viva Wallet’s acquiring commission is applied for the transaction and deducted from the platform account
  4. The funds transfer from the platform account to the marketplace owner must be executed manually, ensuring the transactionId parameter is left empty. These transfers should be made in ‘batches’ after the settlement process has taken place, rather than on a per-payment basis

Information:

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

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

Process:

  1. Acquiring performed within the POS device or app (either standalone, via Android inter-app integration, via iOS inter-app integration or via Cloud REST API integration)
  2. Funds transfers to sellers are triggered manually after the payment, specifying the associated customer payment
  3. Viva Wallet’s acquiring commission is applied for the transaction and deducted from the platform account
  4. The funds transfer from the platform account to the marketplace owner must be executed manually, ensuring the transactionId parameter is left empty. These transfers should be made in ‘batches’ after the settlement process has taken place, rather than on a per-payment basis

Information:

Perform refunds

The refund process can also differ, depending on the use cases above.

Please see our use cases below, or refer to our Issue a marketplace refund tutorial for further details.

Use Case A - manual transfers (online customer refunds)

For online refunds with manual transfers, please follow the steps below:

  1. To perform a refund to an end customer, you will need to use the Cancel transaction API call, specifying the transactionId of the original payment
  2. To retrieve funds back from the seller accounts, you will need to use Create a transfer reversal, as needed

For the refund to be executed successfully, the platform account must have adequate balance

Use Case B - automatic transfers (online customer refunds)

For online refunds with automatic transfers (i.e. for when the transfer parameter of the initial payment order was used to trigger automatic seller transfers), please follow the steps below:

  1. To perform a refund to an end customer, you will need to use the Cancel transaction API call, specifying the transactionId of the original payment. The related transfer reversal can be triggered automatically by using the reverseTransfers parameter in the above Cancel transaction call, with the option to return the commission to the seller with the refundPlatformFee parameter

For the refund to be executed successfully, the platform account must have adequate balance

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

For in-store refunds with manual transfers, please follow the steps below:

  1. Refund/cancellation performed within the POS device or app (either standalone, via Android inter-app integration, via iOS inter-app integration or via Cloud REST API integration)
  2. To retrieve funds back from the seller accounts, you will need to use Create a transfer reversal, as needed

For the refund to be executed successfully, the platform account must have adequate balance

Go-Live

After reviewing the above information, please see the below checklists to ensure you’re ready to go live.

Pre-Go-Live Checklist

Go-Live Steps

  1. Register for a live Viva Wallet account
  2. Set up a payment source in your production account
  3. Authenticate using production credentials
    • See OAuth2 authentication method for further details

  4. Update base URLs to live
    • Replace demo.vivapayments.com with www.vivapayments.com in your code

  5. Final live testing with a real payment card
    • Make a test purchase for a small amount using a supported card. Afterwards, you can cancel the transaction from your Viva Wallet account

For businesses migrating to Viva Wallet from another payment provider, please note the following:

  • Initially, follow the ‘Onboard marketplace owner’, ‘Allow transfers’, ‘Integrate with Viva Wallet’, ‘Set up your payment methods’ and ‘Ensure webhooks are functioning correctly’ steps of the Pre-Go-Live Checklist - i.e. everything but the ‘Onboard seller(s)’ step

  • Then, start onboarding sellers to Viva Wallet. This process can follow a big-bang approach (onboard all sellers before switching to Viva Wallet) or a phased approach (onboard sellers gradually, and accordingly switch to Viva Wallet). The latter (phased) approach will require the marketplace owner to check - whenever a customer attempts to make a purchase - if all sellers associated with this customer purchase are onboarded to Viva Wallet. If so, the customer payment can be accepted via Viva Wallet

Further information

Check out the related tutorials below for more details that may be relevant:

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!