Using the Subaccounts API
Overview
This topic describes a use case where a partner uses the Subaccounts API to successfully manage end customers.
Prerequisites
You should be familiar with the main concepts associated with the Subaccounts API.
Creating a subaccount
A Partner decides to create a subaccount for each end customer and is therefore able to use distinct API credentials for each of the end customers and see their spending. This is illustrated in the following diagram:
To create a subaccount the following code can be used:
Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
Create a file named CreateSubaccount and add the following code to the main method:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.subaccounts with the package containing CreateSubaccount:
Prerequisites
Add the following to build.gradle:
Create a file named CreateSubaccount and add the following code to the main method:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.subaccounts with the package containing CreateSubaccount:
Prerequisites
Create a file named CreateSubAccountRequest.cs and add the following code:
using Vonage;
using Vonage.Request;Add the following to CreateSubAccountRequest.cs:
var credentials = Credentials.FromApiKeyAndSecret(vonageApiKey, vonageApiSecret);
var client = new VonageClient(credentials);Write the code
Add the following to CreateSubAccountRequest.cs:
var request = Vonage.SubAccounts.CreateSubAccount.CreateSubAccountRequest.Build()
.WithName(newSubAccountName)
.WithSecret(newSubAccountSecret)
.Create();
var response = await client.SubAccountsClient.CreateSubAccountAsync(request);Prerequisites
Create a file named create-subaccount.php and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named create-subaccount.rb and add the following code:
Run your code
Save this file to your machine and run it:
Transferring credit
The Partner could not control spending among its end customers because they all shared the same balance. One end customer used to occasionally consume all shared balance effectively blocking access to the Vonage APIs for other Partner’s end customers. The Partner decided to set individual balance and allocate a credit limit to that end customer.
NOTE: The Partner could have made their accounts prepaid.
Each subaccount can be allocated an individual balance, and a credit limit, as show in the following diagram:
The following code snippet illustrates allocating a specified amount of credit to a subaccount:
Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
Create a file named TransferCredit and add the following code to the main method:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.subaccounts with the package containing TransferCredit:
Prerequisites
Add the following to build.gradle:
Create a file named TransferCredit and add the following code to the main method:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.subaccounts with the package containing TransferCredit:
Prerequisites
Create a file named TransferCreditRequest.cs and add the following code:
using Vonage;
using Vonage.Request;
using Vonage.SubAccounts.TransferAmount;Add the following to TransferCreditRequest.cs:
var credentials = Credentials.FromApiKeyAndSecret(vonageApiKey, vonageApiSecret);
var client = new VonageClient(credentials);Write the code
Add the following to TransferCreditRequest.cs:
var request = TransferAmountRequest.Build()
.WithFrom(vonageApiKey)
.WithTo(subAccountKey)
.WithAmount(amount)
.Create();
var response = await client.SubAccountsClient.TransferCreditAsync(request);Prerequisites
Create a file named transfer-credit.php and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named transfer-credit.rb and add the following code:
Run your code
Save this file to your machine and run it:
Checking the balance of all subaccounts
The Partner decides to put monitoring in place. It is possible to periodically check the balance of all of subaccounts using the following code snippet:
Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
Create a file named ListSubaccounts and add the following code to the main method:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.subaccounts with the package containing ListSubaccounts:
Prerequisites
Add the following to build.gradle:
Create a file named ListSubaccounts and add the following code to the main method:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.subaccounts with the package containing ListSubaccounts:
Prerequisites
Create a file named GetSubAccountsRequest.cs and add the following code:
using Vonage;
using Vonage.Request;Add the following to GetSubAccountsRequest.cs:
var credentials = Credentials.FromApiKeyAndSecret(vonageApiKey, vonageApiSecret);
var client = new VonageClient(credentials);Write the code
Add the following to GetSubAccountsRequest.cs:
var response = await client.SubAccountsClient.GetSubAccountsAsync();Prerequisites
Create a file named get-subaccounts.php and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named list-subaccounts.rb and add the following code:
Run your code
Save this file to your machine and run it:
Additional credit allocation
After some time, the Partner noticed that the end customer 1 (subaccount1) used up all of its credit (40 out of 40) and could not make any more API calls. The Partner had a choice of either waiting for the end customer 1 to pay them (and then in turn making a payment to Vonage and transferring a corresponding balance to the subaccount) or increasing the end customer’s credit limit immediately so that end customer 1 can continue using the Vonage API. The Partner decided to allocate additional credit. The Partner has 40 = |-60| - |-20| available credit, and decides to allocate 20 to the subaccount. This is illustrated in the following diagram:
End of month balance transfers
At the end of the month the Partner received a |-20| + |-50| = €70 invoice from Vonage (for all spending from all its accounts). End customer 1 (subaccount1) covered 45 out of €50 that it had spent. Thus, the Partner transferred €45 to subaccount1's balance. This is illustrated in the following diagram:
The following code shows how to transfer balance to a subaccount:
Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
Create a file named TransferBalance and add the following code to the main method:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.subaccounts with the package containing TransferBalance:
Prerequisites
Add the following to build.gradle:
Create a file named TransferBalance and add the following code to the main method:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.subaccounts with the package containing TransferBalance:
Prerequisites
Create a file named TransferBalanceRequest.cs and add the following code:
using Vonage;
using Vonage.Request;
using Vonage.SubAccounts.TransferAmount;Add the following to TransferBalanceRequest.cs:
var credentials = Credentials.FromApiKeyAndSecret(vonageApiKey, vonageApiSecret);
var client = new VonageClient(credentials);Write the code
Add the following to TransferBalanceRequest.cs:
var request = TransferAmountRequest.Build()
.WithFrom(vonageApiKey)
.WithTo(subAccountKey)
.WithAmount(amount)
.Create();
var response = await client.SubAccountsClient.TransferBalanceAsync(request);Prerequisites
Create a file named transfer-balance.php and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named transfer-balance.rb and add the following code:
Run your code
Save this file to your machine and run it:
Suspending a subaccount
The Partner liked the ability to control the spending of the subaccount and decided to assign individual balance and €30 credit to the end customer 2 (subaccount2). The Partner, who was monitoring the spending of its subaccounts spending, noticed that subaccount2 consumed €25 of its balance. Alarmed by subaccount2's spending rate, the Partner decided to temporarily suspend subaccount2. The code to suspend a subaccount is shown here:
Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
Create a file named SuspendSubaccount and add the following code to the main method:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.subaccounts with the package containing SuspendSubaccount:
Prerequisites
Add the following to build.gradle:
Create a file named DeactivateSubaccount and add the following code to the main method:
Write the code
Add the following to the main method of the DeactivateSubaccount file:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.subaccounts with the package containing DeactivateSubaccount:
Prerequisites
Create a file named SuspendAccountRequest.cs and add the following code:
using Vonage;
using Vonage.Request;
using Vonage.SubAccounts.UpdateSubAccount;Add the following to SuspendAccountRequest.cs:
var credentials = Credentials.FromApiKeyAndSecret(vonageApiKey, vonageApiSecret);
var client = new VonageClient(credentials);Write the code
Add the following to SuspendAccountRequest.cs:
var request = UpdateSubAccountRequest.Build().WithSubAccountKey(subAccountKey)
.SuspendAccount()
.Create();
var response = await client.SubAccountsClient.UpdateSubAccountAsync(request);Prerequisites
Create a file named suspend-subaccount.php and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named suspend-subaccount.rb and add the following code:
Run your code
Save this file to your machine and run it:
Reactivating a subaccount
After discussions with subaccount2, the Partner decides to reactivate subaccount2's account. This can be achieved using the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
Create a file named ReactivateSubaccount and add the following code to the main method:
Write the code
Add the following to the main method of the ReactivateSubaccount file:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.subaccounts with the package containing ReactivateSubaccount:
Prerequisites
Add the following to build.gradle:
Create a file named ReactivateSubaccount and add the following code to the main method:
Write the code
Add the following to the main method of the ReactivateSubaccount file:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.subaccounts with the package containing ReactivateSubaccount:
Prerequisites
Create a file named EnableAccountRequest.cs and add the following code:
using Vonage;
using Vonage.Request;
using Vonage.SubAccounts.UpdateSubAccount;Add the following to EnableAccountRequest.cs:
var credentials = Credentials.FromApiKeyAndSecret(vonageApiKey, vonageApiSecret);
var client = new VonageClient(credentials);Write the code
Add the following to EnableAccountRequest.cs:
var request = UpdateSubAccountRequest.Build().WithSubAccountKey(subAccountKey)
.EnableAccount()
.Create();
var response = await client.SubAccountsClient.UpdateSubAccountAsync(request);Prerequisites
Create a file named reactivate-subaccount.php and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named reactivate-subaccount.rb and add the following code:
Run your code
Save this file to your machine and run it:
Summary
In this topic you have seen how to use the Subaccounts API to manage end customers in typical scenarios.