API reference

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

Your Zentact contact will provide your API key. To connect to the API, add an X-API-Key header with the API key as the value. 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.
  • sendInvitationEmail (boolean): Setting this property to true will trigger an invitation email to the email provided in the request.

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.
  • pageSize (number): Number of records to return, max 1000.
  • pageIndex (number): Page index beginning with 0.

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"
            },
            {
                "businessName": "Big Smile Europe",
                "merchantAccountId": "0f922ad3-a5ca-4213-9d1b-f943e95831c4",
                "organizationName": "Big Smile LLC",
                "organizationId": "bf368afb-ed57-4345-a04a-7c7213431a99",
                "referenceId": null,
                "status": "ACTIVE"
            }
        ]
    }
}

Merchant Account Level Webhooks (Optional)

Merchant Account Level Webhooks are optional, but powerful, feature of configuring merchant-specific webhooks. These webhooks, when set up, override our standard default webhook settings. Unlike our standard webhook setup, this functionality allows you to tailor webhook interactions for each merchant. It's particularly handy for those requiring unique HMAC keys, enabling a more personalized and secure integration.

To get started, you'll first need to request an HMAC key generation, which can then be assigned to these webhooks. This flexibility allows for the reuse of the same key across multiple merchants, particularly useful within organizations with several merchants.

Generate a unique HMAC key

Use this API endpoint to create HMAC keys for authenticating merchant-specific webhooks. When you send a POST request to this endpoint, the response will include two key fields: hmacKey and id.

POST /api/v1/webhook-hmac-keys

Response

{
  "status": "ok",
  "data": {
    "hmacKey": "40FBAEC6C5A7ADAC7188870F24581C8ECBF446988845743F7AE7EC3253198C83",
    "id": "1254db88-c404-40ce-b7c1-b2d137927e81"
  }
}
  • You should save hmacKey from the endpoint response. You will not be able to retrieve it again. If you lost your old hmacKey, you should generate a new one.
  • To use the generated HMAC key, you should create new webhook configurations with a reference to the HMAC key entity. The id field from the response is required for this operation.

Create merchant webhook configuration

Note! If you set up merchant-specific webhooks, these will take precedence over the default webhooks. In cases where merchant-specific webhooks exist, the company's default webhooks won't be triggered. However, for all other merchants without specific webhooks, the company's default webhooks will continue to function as normal.

POST /api/v1/merchant-accounts/:merchantAccountId/webhooks

Required Parameters:

  • webhookHmacKeyId (string): id from generate HMAC key request.
  • url (string): Full HTTP URL of your endpoint. E.g https://example.com/smth.
  • eventTypes (array of strings): list of supported webhook events. Include "PAYMENT" for payment updates and "MERCHANT" for merchant account updates.

Example:

POST /api/v1/merchant-accounts/12bb40d2-94ee-494c-a5d7-4b6f29428491/webhooks

Request

{
  "webhookHmacKeyId": "1254db88-c404-40ce-b7c1-b2d137927e81",
  "url": "https://example.com/smth",
  "eventTypes": ["PAYMENT", "MERCHANT"]
}

Response

{
  "status": "ok",
  "data": {
    "webhookId": "O5D1kcZ2OpFSD-1IsTRM_",
    "url": "https://example.com/smth",
    "eventTypes": [
      "PAYMENT",
      "MERCHANT"
    ],
    "merchantAccountId": "12bb40d2-94ee-494c-a5d7-4b6f29428491",
    "webhookHmacKeyId": "1254db88-c404-40ce-b7c1-b2d137927e81"
  }
}

Get merchant webhook configuration list

Get list of webhook configurations for selected merchant account.

GET /api/v1/merchant-accounts/:merchantAccountId/webhooks

Example:

GET /api/v1/merchant-accounts/12bb40d2-94ee-494c-a5d7-4b6f29428491/webhooks

Response

{
  "status": "ok",
  "data": [
    {
      "id": "2783a6f0-1588-4e80-abbe-92ffa0bbc974",
      "merchantAccountId": "12bb40d2-94ee-494c-a5d7-4b6f29428491",
      "hmacKeyId": "1254db88-c404-40ce-b7c1-b2d137927e81",
      "url": "https://example.com/smth",
      "createdAt": "2024-01-10T16:01:30.981Z"
    }
  ]
}

Delete merchant webhook configuration

Delete the selected webhook configuration.

DELETE /api/v1/merchant-accounts/:merchantAccountId/webhooks/:webhookId

Example:

DELETE /api/v1/merchant-accounts/12bb40d2-94ee-494c-a5d7-4b6f29428491/webhooks/2783a6f0-1588-4e80-abbe-92ffa0bbc974

Response

{
  "status": "ok"
}
Previous
Organizations
Next
Checkout