Skip to main content

Tenant Management

Tenants are onboarded and managed by Stitch directly, however a tenant that has been registered as a parent tenant may onboard and manage their own tenants via the Stitch API.

A parent tenant may have an aggregation relationship with Stitch and onsell some of Stitch services to their own customers that have their own merchants.

A parent tenant can create tenants of the following types:

  • rki_only - only requires Stitch RKI (Remote Key Injection) services for their terminals.
  • transactional - requires all transactional services to process a transaction (which may or may not include RKI as well).

A parent tenant can not create other parent tenants and thus may not create arbitrary levels of tenant hierarchies.

This payload sample below shows how to create a new tenant via the Management API, and contains essential configuration details for the tenant.

  • Basic Information: Sets the tenant type, name, and contact details.
  • Regional Settings: Configures default currency, timezone, country, and language settings that will apply to all merchants under this tenant unless overridden.
  • Feature Configuration: The config object contains various configurations and feature flags which control tenant behavior.
  • Hierarchy: The parentTenantId establishes this as a sub-tenant under the specified parent tenant.
  • Data Retention: transactionOffloadAfterDays defines how long transaction data is retained before archiving.
POST /v/1/tenants
{
    "tenantType": "transactional",
    "name": "Parent Tenant Name",
    "aggregatorName": "",
    "defaultCurrency": "ZAR",
    "defaultTimeZone": "Africa/Johannesburg",
    "defaultCountryCode": "ZA",
    "defaultLanguageCode": "en",
    "defaultMerchantType": "iso",
    "config": {
        "webhookConfigs": [],
        "featureFlags": {
            "suppressReplayAttackNotification": false,
            "refundsDisabled": false,
            "cardNotPresentRefundsDisabled": false,
            "rulesDisabled": false,
            "switchFileEnabled": false,
            "eightDigitBinSupported": false,
            "cardHmacEnabled": false
        },
        "cnpRefundEncryptionKeyAlias": "",
        "appleTerminalProfileId": ""
    },
    "systemAccount": false,
    "address": "1 ACME Road",
    "contactNo": "0123456789",
    "transactionOffloadAfterDays": 180,
    "parentTenantId": "68af47fe-2a46-4b6d-b397-a9cd42c23a52"
}

The tenantType field indicates what kind of sub-tenant is being created as explained previously. The parentTenantId should match the Stitch tenant ID assigned to the parent tenant.