Introduction

Subaccounts are a resource that allows customers to create segregations of Cards within an account and define the configurations of the Cards of those groupings.

As a Platform, our API is used by many different customers. Customers are owners of Account(s). Accounts are the primary resource representing a tenant in our API. Customers' actions (create, read, update, delete) are specific to the context of a given Account.

Whenever a request arrives in our systems, we need to de determine the Tenant (Account) that the request is intended for. To do this, we are leveraging Token claims. We use OAuth 2.0 for clients to authenticate with our API where every client, when authenticated, contains a set of claims that allows our services to identify to which Account the request is targeting and with which permissions.

We are not offering tenancy per subaccount. Subaccounts provide customers with segmentation for their customers based on their desired parameters and the ability to push this segmentation concept into our system which enables cost control and other context-specific configuration.

Using simple terms, we see subaccounts as buckets, each bucket has a set of conditions, and other resources (card subscriptions, transaction/transaction messages, etc) are placed under a given bucket.

Common Use

The most common use of Subaccounts is in B2B2C use cases, where customers are serving numerous business clients. If Customer A is serving Acme Corp, John's Pizzeria, and XYZ Plumbing, it may decide to create three Subaccounts, each corresponding to one of the afore-mentioned businesses. Acme Corp's cards will be enrolled into the Acme Corp Subaccount and all transaction data from those cards will be contained with the Acme Corp Subaccount as well.

You may create these groupings however you see fit.

Subaccount Resource

Field Name	Required/Optional	Description	Type
id	required	The Subaccount identifier	string `uuid` format
name	required	A human readable description of this Subaccount	string
createdAt	required	Subaccount creation date	string ISO 8601, `YYYY-MM-DDThh:mm:ss.sssZ`
updatedAt	required	Subaccount updated date	string ISO 8601, `YYYY-MM-DDThh:mm:ss.sssZ`
accountId	required	The account identifier	string `uuid` format
configurations	required	Array with configurations that determine what rights a Subaccount has; this in turn affects the cards that can be enrolled in this Subaccount	array object

Configurations

In addition to simply being a segregation layer, Subaccounts also define the privileges that enrolled cards will be able to access.

Configuration	Required	Description	Type
countries	required	List of permitted countries relating to where the card was issued	string array ISO 3166 ALPHA-3
networks	required	List of permitted card networks	string array enum: `VISA MASTERCARD`

Configurations at a Subaccount level cannot permit greater access than as allowed at the account level, per your contract. For instance, if your contract permits you to support cards issued in the United States and Canada, you will not be able to permit a given Subaccount to allow United States, Canada and the United Kingdom. However, you may limit the Subaccounts to cards issued in only Canada, for example, if you see fit.

The same is true for the supported networks. Note that you're able to configure specific countries only on specific networks. For example, you can configure a Subaccount to only support the United States on Visa, and Canada on Mastercard.