Organizations API

In Zentact, "Organizations" play a critical role in structuring and managing multiple sub-merchant accounts under a single, unified company identity. This feature is particularly beneficial for businesses operating in multiple locations or different functions, each needing its distinct merchant account.

Understanding Organizations

Imagine a company named 'Big Smile Canada,' a dental corporate chain with offices in Vancouver, Toronto East, and Toronto West. While each office operates its merchant account to handle transactions specific to its location, they all are a part of the larger 'Big Smile Canada' organization. This setup allows them to maintain a cohesive brand identity and centralized control over operations. The Organizations feature in Zentact encapsulates this structure, enabling businesses like 'Big Smile Canada' to:

Consolidate Control: Administer and oversee all linked merchant accounts from a single, unified merchant portal.
Unified View: Access and manage transactions, statements, and other critical business details across all accounts.
Brand Cohesion: Maintain a consistent brand identity and operational standard across all branches or departments.

Capabilities of the Organizations API

The Organizations API in Zentact is designed to provide more control over automatic organization creating during merchant onboarding. Through our API, you can:

Create Organizations: Establish a new organization and define its structure.
View Organizations: Retrieve details about existing organizations, including all linked sub-merchant accounts.
Update Organizations: Modify the details and structure of an existing organization as your business evolves.

Whether you're a large enterprise with multiple branches or a growing business expanding into new areas, our Organizations API is equipped to support your growth and streamline your operations. Let's dive into how you can leverage this powerful feature in your Zentact integration.

Every merchant account belongs to an organization

Even if your customer's business operates with a single merchant account, Zentact ensures that its account is neatly integrated within an organizational structure. This approach provides you with the flexibility to expand effortlessly in the future and benefits from the organizational features right from the start.

Create organization

POST /api/v1/organizations

Parameters

organizationName (string, max 100 characters): Name of the organization. Must be unique.
referenceId (string, max 50 characters, optional): An optional, unique reference ID that identifies an organization in your system.
supportEmail (string, max 50 characters, optional): Organization's support email address. This will be visible on the checkout page and email communications with payer.
businessPhoneNumber (string, optional): An optional phone number to be displayed on the checkout page and email communications.
logoFileUrl (string, optional): An optional url for horizontal logo. Must be a WHATWG-compatible URL.
pspMerchantAccountName (string, optional): The name of the parent Adyen merchant account under which this organization and its sub-merchant accounts will be created. If not provided, the default merchant account will be used. This is recommended when you have more than one merchant account configured in Adyen and Zentact to ensure the correct account is used.
businessPhoneNumber (string, optional): The business phone number. Must follow the E.164 format (e.g., +12345678900). Phone numbers are validated for format.

Example: Creating Big Smile organization

Request

{
  "referenceId": "CF8mBKpN24SvvQm",
  "organizationName": "Big Smile",
  "supportEmail": "support@bigsmile.com",
  "businessPhoneNumber": "+16617136234",
  "pspMerchantAccountName": "DentalSolutions_US"
}

Response

{
  "status": "ok",
  "data": {
    "organizationName": "Big Smile",
    "referenceId": "USB",
    "id": "97c4529f-77b6-4375-84f0-9949be996604"
  }
}

Get all organizations and merchant accounts (paginated)

Optional URL Query Parameters:

referenceId (string, max 50 characters, optional): Looks up a single organization by reference ID.
pageSize (number, optional, default 50, max 1000): Number of records to return.
pageIndex (number, optional, min 0): Page index beginning with 0.

GET /api/v1/organizations

Response

{
  "status": "ok",
  "data": {
    "pagination": {
      "pageIndex": 0,
      "pageSize": 2,
      "pageCount": 2,
      "total": 3,
      "hasPrevPage": false,
      "hasNextPage": true
    },
    "rows": [
      {
        "id": "bf368afb-ed57-4345-a04a-7c7213431a99",
        "referenceId": null,
        "name": "Big Smile",
        "brandConfiguration": {
          "logoFileName": "BigSmileLong.png",
          "primaryColorHex": "#2191C9",
          "supportPhoneNumber": "+1 800 BIGSMIL",
          "supportEmail": "support@bigsmile.com",
          "logoUrl": "https://zentact-dev.imgix.net/organizations/bf368afb-ed57-4345-a04a-7c7213431a99/images/BigSmileLong.png"
        },
        "merchantAccounts": [
          {
            "id": "12bb40d2-94ee-494c-a5d7-4b6f29428491",
            "referenceId": null,
            "businessName": "Big Smile LLC",
            "status": "ACTIVE"
          },
          {
            "id": "0f922ad3-a5ca-4213-9d1b-f943e95831c4",
            "referenceId": null,
            "businessName": "Big Smile Europe",
            "status": "ACTIVE"
          }
        ]
      },
      {
        "id": "97c4529f-77b6-4375-84f0-9949be996604",
        "referenceId": "xxx232",
        "name": "Pediatric Dental",
        "brandConfiguration": {
          "logoFileName": null,
          "primaryColorHex": "#2191C9",
          "supportPhoneNumber": "+16617136234",
          "supportEmail": "test+0ozq@rocketparts.io",
          "logoUrl": null
        },
        "merchantAccounts": []
      }
    ]
  }
}

Get an organization by organization ID

GET /api/v1/organizations/dd08fc84-b313-465b-b2b2-8e4b639b3342

Response

{
  "status": "ok",
  "data": {
    "id": "dd08fc84-b313-465b-b2b2-8e4b639b3342",
    "referenceId": null,
    "name": "Big Smile",
    "brandConfiguration": {
      "logoFileName": "BigSmileLong.png",
      "primaryColorHex": "#327bb4",
      "supportPhoneNumber": "+18004842148",
      "supportEmail": "support+1763502098581@bugbug-inbox.com",
      "logoUrl": "https://zentact-dev.imgix.net/organizations/dd08fc84-b313-465b-b2b2-8e4b639b3342/images/BigSmileLong.png"
    },
    "merchantAccounts": [
      {
        "id": "MER9WE4HDPTNY",
        "referenceId": "b319e95f-09be-4f2b-9e8a-da622c1043we5",
        "businessName": "Predovic, Miller and Rogahn",
        "status": "ACTIVE"
      }
    ]
  }
}

Update an organization

PATCH /api/v1/organizations/7c20ba7c-6cb6-4222-a005-976875441fe3

Required Parameters

organizationName (string, max 100 characters): Name of the organization. Must be unique.
supportEmail (string, max 50 characters, optional): Organization's support email address. This will be visible on the checkout page and email communications with payer.

Request

{
  "organizationName": "Pediatric Dentistry",
  "supportEmail": "support@mail.com"
}

Response

{
  "status": "ok",
  "data": {
    "id": "7c20ba7c-6cb6-4222-a005-976875441fe3",
    "referenceId": null,
    "name": "Pediatric Dentistry",
    "brandConfiguration": {
      "logoFileName": null,
      "primaryColorHex": "#2191C9",
      "supportPhoneNumber": null,
      "supportEmail": "support@mail.com",
      "logoUrl": null
    },
    "merchantAccounts": [
      {
        "id": "MERZBKMVZI545",
        "referenceId": "5kfbHkb4oZHs8Hsr-FyFr",
        "businessName": "Wilkinson - Dickinson NG",
        "status": "PENDING"
      }
    ]
  }
}