☰

Navigation:

Create a connected account

How to create a connected marketplace (seller) account.

Overview

Viva’s Marketplace solution requires seller accounts to be ‘connected’ to the main platform account, in order for transfers of funds to take place.

To create a connected seller account, the marketplace owner can utilise our Create a connected account API.

Additionally, information about a connected account can be found by using our Retrieve information about a connected account API.

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

Pre-requisites

Before creating a connected account, we recommend reviewing the following pre-requisites.

Firstly, you - as the marketplace owner - will need to decide upon the branding elements to apply (i.e. primaryColor, partnerName and logoUrl), the latter two of which are mandatory. In addition to this, you will need to define the URL you wish to redirect the seller to once they have completed their onboarding process (the returnUrl parameter).

Secondly, you will need to obtain relevant information from the seller. In particular, the seller’s email address is required. You may also wish to provide additional information - such as the seller’s mobile, legalName, tradeName, taxNumber and address - to be displayed during the onboarding process. However, please note that these parameters are optional, and can be amended by the seller during the onboarding process.

Thirdly, we would strongly recommend to set up the Account Connected and Account Verification Status Changed webhooks, to receive notifications when an account is successfully connected and when its verification status subsequently changes, respectively.

Process

The process to create a connected seller account is as follows:

1. Once you have obtained the seller’s email address and any other relevant information - as per the Pre-requisites section - you will need to use our Create a connected account API, filling in the returnUrl, email, partnerName and logoURL parameters, along with any others as desired [see example request]

You will receive an error message if you attempt to create an account using an email address already associated with an existing connected account. In such cases, we recommend to:

- Use our Retrieve information about a connected account API to find and check the account [see example request]
- Retry creating the new account with a different email address, if needed

2. Once you have successfully created the account, you should be sure to store the response information of the ‘Create a connected account’ API call (i.e. accountId, email, redirectUrl & created). This step is mandatory, as you will need the accountId of the seller to make transfers and payouts to the seller. Additionally, you will need the accountId of the seller to use our Retrieve information about a connected account API to find details of this connected account in the future (as mentioned in the Note box, above)

3. You should then send the redirectUrl from the invitation section of the response to the seller; the seller will follow this URL to initiate the onboarding process to become a seller for the marketplace

4. Once the seller has completed the onboarding process, they will be redirected to the returnUrl you specified in the ‘Create a connected account’ API and you will now be able to make transfers and payouts to this seller

If completing this process in the Demo environment, you 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, 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 to connect the accounts

Example requests

Create a connected account

Environment Method URL
Production POST https://api.vivapayments.com/platforms/v1/accounts
Demo POST https://demo-api.vivapayments.com/platforms/v1/accounts 
curl --location 'https://demo-api.vivapayments.com/platforms/v1/accounts' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "user@example.com",
  "mobile": 6948740000,
  "legalName": "Consulting Detective",
  "tradeName": "Sherlock Holmes",
  "taxNumber": null,
  "returnUrl": "https://example.com/connected",
  "address": {
    "street": "Baker Street",
    "number": "221B",
    "city": "London",
    "postCode": "NW1",
    "countryCode": "GB",
    "secondLine": null
  },
  "branding": {
    "partnerName": "Header/title summary",
    "primaryColor": null,
    "logoUrl": "https://example.com/company-logo"
  },
  "payouts": {
    "statementDescriptor": "Weekly payouts",
    "dayOfWeek": 1,
    "dayOfMonth": null,
    "interval": 2,
    "amountThreshold": 1000,
    "disable": false,
    "bankAccount": {
      "iban": "NL04RABO6360804956",
      "friendlyName": "External account",
      "beneficiaryName": "Sherlock Holmes",
      "branchCode": null,
      "accountNumber": null,
      "countryCode": null
    }
  }
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/platforms/v1/accounts',
  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 =>'{
  "email": "user@example.com",
  "mobile": 6948740000,
  "legalName": "Consulting Detective",
  "tradeName": "Sherlock Holmes",
  "taxNumber": null,
  "returnUrl": "https://example.com/connected",
  "address": {
    "street": "Baker Street",
    "number": "221B",
    "city": "London",
    "postCode": "NW1",
    "countryCode": "GB",
    "secondLine": null
  },
  "branding": {
    "partnerName": "Header/title summary",
    "primaryColor": null,
    "logoUrl": "https://example.com/company-logo"
  },
  "payouts": {
    "statementDescriptor": "Weekly payouts",
    "dayOfWeek": 1,
    "dayOfMonth": null,
    "interval": 2,
    "amountThreshold": 1000,
    "disable": false,
    "bankAccount": {
      "iban": "NL04RABO6360804956",
      "friendlyName": "External account",
      "beneficiaryName": "Sherlock Holmes",
      "branchCode": null,
      "accountNumber": null,
      "countryCode": null
    }
  }
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response
{
  "accountId": "fa176a3b-a7e8-4f3d-abe6-5e65626f5994",
  "invitation": {
    "email": "user@example.com",
    "redirectUrl": "https://example.com/onboardingflow",
    "created": "2023-02-15T09:45:22.406Z"
  }
}

Retrieve information about a connected account

Environment Method URL
Production GET https://api.vivapayments.com/platforms/v1/accounts/{accountId}
Demo GET https://demo-api.vivapayments.com/platforms/v1/accounts/{accountId} 
curl --location -g 'https://demo-api.vivapayments.com/platforms/v1/accounts/{accountId}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/platforms/v1/accounts/%7BaccountId%7D',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response
{
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "email": "user@example.com",
  "payouts": {
    "statementDescriptor": "Weekly payouts '#MP12385'",
    "dayOfWeek": 1,
    "dayOfMonth": null,
    "interval": 2,
    "amountThreshold": 1000,
    "disable": false,
    "bankAccount": {
      "iban": "NL04RABO6360804956",
      "friendlyName": "External account",
      "beneficiaryName": "Sherlock Holmes",
      "branchCode": null,
      "accountNumber": null,
      "countryCode": null
    }
  },
  "verified": true,
  "acquiringEnabled": true,
  "created": "2023-02-15T09:45:22.406Z",
  "invitation": {
    "email": "user@example.com",
    "redirectUrl": "https://example.com/onboardingflow",
    "created": "2023-02-15T09:45:22.406Z"
  }
}

Update connected account attributes

Environment Method URL
Production PATCH https://api.vivapayments.com/platforms/v1/accounts/{accountId}
Demo PATCH https://demo-api.vivapayments.com/platforms/v1/accounts/{accountId} 
curl --location -g --request PATCH 'https://demo-api.vivapayments.com/platforms/v1/accounts/{accountId}' \
--header 'Authorization: Bearer {Bearer_Token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "payouts": {
    "statementDescriptor": "Weekly payouts",
    "dayOfWeek": 1,
    "dayOfMonth": null,
    "interval": 2,
    "amountThreshold": 1000,
    "disable": false,
    "bankAccount": {
      "iban": "NL04RABO6360804956",
      "friendlyName": "External account",
      "beneficiaryName": "Sherlock Holmes",
      "branchCode": null,
      "accountNumber": null,
      "countryCode": null
    }
  }
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/platforms/v1/accounts/%7BaccountId%7D',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PATCH',
  CURLOPT_POSTFIELDS =>'{
  "payouts": {
    "statementDescriptor": "Weekly payouts",
    "dayOfWeek": 1,
    "dayOfMonth": null,
    "interval": 2,
    "amountThreshold": 1000,
    "disable": false,
    "bankAccount": {
      "iban": "NL04RABO6360804956",
      "friendlyName": "External account",
      "beneficiaryName": "Sherlock Holmes",
      "branchCode": null,
      "accountNumber": null,
      "countryCode": null
    }
  }
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer {Bearer_Token}',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response
{
  "Message": "Success."
}

Get Support

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