API reference

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 charachter, optional): An optional, unique reference id that identifies an organization in your system.
  • supportEmail (string, max 100 characters, optional): Organization's supoort 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 horizontal logo.

Example: Creating Big Smile organization

Request

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

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 80 characters): Looks up a single organization by reference id.
  • pageSize (number): Number of records to return, max 1000.
  • pageIndex (number): 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": {
          "displayName": "Big Smile",
          "logoFileName": "BigSmileLong.png",
          "smallLogoFileName": "SmallLogo.png",
          "primaryColorHex": "#2191C9",
          "phoneNumber": "+1 800 BIGSMIL",
          "email": "support@bigsmile.com",
          "logoUrl": "https://zentact-dev.imgix.net/organizations/bf368afb-ed57-4345-a04a-7c7213431a99/images/BigSmileLong.png",
          "smallLogoUrl": "https://zentact-dev.imgix.net/organizations/bf368afb-ed57-4345-a04a-7c7213431a99/images/SmallLogo.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": {
          "displayName": "Little - Bartoletti",
          "logoFileName": null,
          "smallLogoFileName": null,
          "primaryColorHex": "#2191C9",
          "phoneNumber": "+16617136234",
          "email": "test+0ozq@rocketparts.io",
          "logoUrl": null,
          "smallLogoUrl": null
        },
        "merchantAccounts": []
      }
    ]
  }
}

Get an organization by reference id

GET /api/v1/organizations?referenceId=xxx232

Response

{
  "status": "ok",
  "data": {
    "pagination": {
      "pageIndex": 0,
      "pageSize": 50,
      "pageCount": 1,
      "total": 1,
      "hasPrevPage": false,
      "hasNextPage": false
    },
    "rows": [
      {
        "id": "97c4529f-77b6-4375-84f0-9949be996604",
        "referenceId": "xxx232",
        "name": "Pediatric Dental",
        "brandConfiguration": {
          "displayName": "Little - Bartoletti",
          "logoFileName": null,
          "smallLogoFileName": null,
          "primaryColorHex": "#2191C9",
          "phoneNumber": "+16617136234",
          "email": "test+0ozq@rocketparts.io",
          "logoUrl": null,
          "smallLogoUrl": null
        },
        "merchantAccounts": []
      }
    ]
  }
}

Update an organization

PATCH /api/v1/organizations/97c4529f-77b6-4375-84f0-9949be996604

Required Parameters

  • organizationName (string, max 100 characters): Name of the organization. Must be unique.

Request

{
  "organizationName": "Pediatric Dentistry"
}

Response

{
  "status": "ok",
  "data": {
    "id": "97c4529f-77b6-4375-84f0-9949be996604",
    "referenceId": "xxx232",
    "name": "Pediatric Dentistry",
    "brandConfiguration": {
      "displayName": "Little - Bartoletti",
      "logoFileName": null,
      "smallLogoFileName": null,
      "primaryColorHex": "#2191C9",
      "phoneNumber": "+16617136234",
      "email": "test+0ozq@rocketparts.io",
      "logoUrl": null,
      "smallLogoUrl": null
    },
    "merchantAccounts": []
  }
}
Previous
Getting started
Next
Merchant Accounts