Merchant Accounts API

The Merchant Accounts API is designed to streamline the onboarding of new merchant accounts. These accounts are linked to specific organizations. For instance, a SaaS platform like Dental Solutions might have multiple locations, such as 'Big Smile Denver' and 'Big Smile LA', all nested under the umbrella of the 'Big Smile' organization.

Key Features:

• Organization Grouping: Group multiple merchant accounts under a single organization.
• Invitation and Account Management: Manages invitations and user account creation seamlessly. If an external identity provider is used, it can be assigned to an organization, ensuring streamlined user access and security.
• Merchant Specific Webhook Management: Involves setting up, configuring, and maintaining webhooks that are specific to the merchant account.

This API simplifies the management and categorization of merchant accounts, making it easier to maintain a structured and organized system for your clients.

Authentication

After configuring an API key in the Zentact admin, include it in requests by adding an X-API-Key header. For example:

curl https://test.api.zentact.com/api/v1/merchant-accounts
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \

Create New Merchant Account - Initiate Onboarding

Before creating merchant accounts, ensure you have established an organization and possess the organization ID.

POST /api/v1/merchant-accounts

• Email-Specific Invitation: Merchant account invitation will be linked to the provided user email.
• Registration Session: Starts a unique/secure registration session which remains valid for 7 days. The duration can be configured as needed.

Use this endpoint to seamlessly begin the process of adding new merchant accounts to your system.

Required Parameters:

• email (string, max 100 characters): The email address of the signatory or business owner, the person who will be filling out the merchant application and who will become an admin of the new merchant account. Must be in a valid email format.
• businessName* (string, max 100 characters): A unique business name for the merchant account, used solely within Zentact to identify their account. This name is separate from the legal business name and/or DBA provided by the merchant on their application during the onboarding process.
• organizationId (string, max 36 characters): The ID of the organization within Zentact to which the merchant account will be assigned.

Optional Parameters:

Optional parameters are used to prefil the merchant application form.

• locale (string, max 5 characters, defaults to en-US): The local language and country code.
• firstName (string, max 50 characters): The first name of the signer.
• lastName (string, max 50 characters): The last name of the signer.
• legalBusinessName (string, max 100 characters): The merchant's legal business name.
• businessPhoneNumber (string): The business phone number. Must follow the E.164 format (e.g., +12345678900). Phone numbers are validated for format.
• legalEntityType (enum): The type of legal entity. Possible values: 'organization', 'soleProprietorship'.
• businessAddress (object):
  • line1 (string, max 100 characters): Address line 1.
  • line2 (string, optional, max 100 characters): Address line 2.
  • city (string, max 50 characters): City.
  • state (string, max 30 characters): State or province.
  • postalCode (string, max 20 characters): Postal code.
  • country (string, max 2 characters): Country code (must be 2 characters).
• website (string, max 100 characters): The URL of the business website. Must be a valid URL.
• shopperStatement (string, max 22 characters): Short description of the merchant that will be displayed on a customer's credit card statement.
• merchantReferenceId (string, max 36 characters): A unique reference ID for the merchant. Use this field to associate a merchant account with an id in your system.
• returnUrl (string, max 200 characters): The URL to which the user will be redirected after registration. Must be a valid URL.
• splitConfigurationGroupId (string): The ID of the split configuration (Transaction Fees) that will be assigned the merchant account.
• recurringFeesGroupId (string): The ID of the recurring fee configuration that will be assigned to the merchant account.
• initiateOnly (boolean): When set to true, this property initializes a merchant account without sending an invite. This is useful if you need to associate a merchant reference ID with an account in your system, while still allowing someone to use Zentact UI to select a price group and send invitation.

Example: New Merchant Account Under Existing Organization

The following will initiate a new merchant account (sub-merchant) registration under existing organization with provided id. Request

{
  "email": "tim@bigsmile.com",
  "businessName": "Big Smile Denver",
  "organizationId": "c68e84fa-1d19-4cbb-a4f7-3f6bc6445462"
}

Response

{
  "status": "ok",
  "data": {
    "redirectUrl": "https://payments.dentalsolutions.site/signup?locale=en-US&invitation=BOF7G0PG59tpwHsCkcWJWBdp6HRbTJ9q&organization=org_RSk09pzqyc5f1rOe&organization_name=dental-solutions#sid=zTS2QeDDKBvyoFn2i-Som",
    "merchantAccountId": "MERP3PFH5NJZ6",
    "merchantReferenceId": "c24b9d8f-43a2-4712-ae76-51643ff467a3"
  }
}

Example: New Organization/Merchant account with all data prefilled in merchant application

{
  "email": "tamar@bigsmile.com",
  "phone": "+15283751645",
  "locale": "en-US",
  "legalEntityType": "organization",
  "businessName": "Big Smile - LA",
  "businessPhoneNumber": "+18183599309",
  "businessAddress": {
    "line1": "264 Kuphal Lodge",
    "city": "Jessyberg",
    "state": "CA",
    "postalCode": "91364",
    "country": "US"
  },
  "website": "https://bigsmiledental.com",
  "shopperStatement": "BigSmileDental",
  "merchantReferenceId": "0f43fff8-c395-4b42-971b-1d85953ad243",
  "organizationId": "c68e84fa-1d19-4cbb-a4f7-3f6bc6445462"
}

Errors

Understanding the error codes returned by our API is crucial for diagnosing and resolving issues during integration. Here are some common error scenarios and their associated error codes:

Data Validation Errors (4xx HTTP status codes)

When there is a data validation issue, the API responds with a 422 HTTP status code, indicating that the input data does not meet the required schema or format. The response includes detailed information about the validation errors.

Example Response for Data Validation Error:

{
  "status": "error",
  "errorCode": "SCHEMA_VALIDATION_ERROR",
  "validationErrors": [
    {
      "code": "custom",
      "message": "Invalid phone number format. Please ensure your phone number follows the E.164 format (e.g., +12345678900).",
      "path": ["businessPhoneNumber"]
    }
  ]
}

Get a list of all merchant accounts (paginated)

Optional URL Query Parameters:

• referenceId (string, max 80 characters): Looks up a single merchant account by reference id.
• status (enum): Filter by merchant account status. See status table below.
• pspMerchantAccountName (string): Filter by payment service provider merchant account name.
• pageSize (number): Number of records to return, max 1000.
• pageIndex (number): Page index beginning with 0.

Merchant Account Status Values

GET /api/v1/merchant-accounts

Response

{
  "status": "ok",
  "data": {
    "pagination": {
      "pageIndex": 0,
      "pageSize": 2,
      "pageCount": 2,
      "total": 3,
      "hasPrevPage": false,
      "hasNextPage": true
    },
    "rows": [
      {
        "businessName": "Howe, Schaden and Walsh",
        "merchantAccountId": "MERH6HTCRRF89",
        "organizationName": "Big Smile LLC",
        "organizationId": "bf368afb-ed57-4345-a04a-7c7213431a99",
        "referenceId": "00973265-2734-4d1c-83f3-5a2d10091b9e",
        "status": "INVITED",
        "inviteeEmail": "test+rb9o@rocketparts.io",
        "accountHolderId": "AH3227C223222K5JDZCBHCJL6",
        "balanceAccountId": "BA32272223222K5JDZCH7DLSZ",
        "stores": [
          {
            "storeId": "ST3224Z22322425JDZCB69NWZ",
            "storeReferenceId": "yyy92999yyyy",
            "balanceAccountId": "BA32272223222K5JDZCH7DLSZ",
            "splitConfigurationId": "SCNF4224Q223223W5K9BKK88X557JG"
          }
        ],
        "storeId": "ST3224Z22322425JDZCB69NWZ", // deprecated
        "storeReferenceId": "yyy92999yyyy", // deprecated
        "splitConfigurationId": "SCNF4224Q223223W5K9BKK88X557JG" // deprecated
      },
      {
        "businessName": "Big Smile Europe",
        "merchantAccountId": "0f922ad3-a5ca-4213-9d1b-f943e95831c4",
        "organizationName": "Big Smile LLC",
        "organizationId": "bf368afb-ed57-4345-a04a-7c7213431a99",
        "referenceId": null,
        "status": "ACTIVE",
        "inviteeEmail": "test+rb9o@rocketparts.io",
        "accountHolderId": "AH32272223222L5JMNXX564CP",
        "balanceAccountId": "BA3227C223222L5JMNZ6R3JHP",
        "stores": [
          {
            "storeId": "ST3224Z22322425JDZCB69NWZ",
            "storeReferenceId": "escHKIbdspMS9vmjzoARo",
            "balanceAccountId": "BA3227C223222L5JMNZ6R3JHP",
            "splitConfigurationId": "SCNF4224P223225J5JJGM6G6BM572V"
          }
        ],
        "storeId": "ST3224Z22322425JDZCB69NWZ", // deprecated
        "storeReferenceId": "escHKIbdspMS9vmjzoARo", // deprecated
        "splitConfigurationId": "SCNF4224P223225J5JJGM6G6BM572V" // deprecated
      }
    ]
  }
}

Response Description