This integration pattern demonstrates how to provision a merchant account with an external payment processor after a business has completed the application process.

Overview

This pattern assumes you have already completed a Business Application workflow that collected all required merchant information. The Subject Record from that workflow contains complete business information, business owners, bank account information, sales information, and any required supporting documents.

A typical account provisioning workflow involves the following steps:

1. Create Account Provisioning Workflow
2. Create MBTrust Provisioning Entity
3. Validate Provisioning Requirements
4. Execute Provisioning Operations
5. Monitor Operation Status

Prerequisites

Before starting account provisioning, ensure you have:

1. Completed Business Application Workflow: A BUSINESS_APPLICATION workflow that has been completed or approved
2. Subject Record ID: The subject_record_id from the completed business application
3. Merchant ID (MID): The MID must be added to the business entity's additional_fields. If not added during the application process, add it now using business.update
4. Supporting Documents (Optional): Documents are only needed for DOCUMENT_SYNC operations. For basic onboarding, no documents are required

Adding the MID (If Not Already Present)

If the MID wasn't added during the business application process, add it now:

POST https://api.kompliant.com/business.update

Request Body:

{
  "business_id": "b_from_application_workflow",
  "business": {
    "additional_fields": [
      {
        "field_name": "merrick_mid",
        "field_value": "123456789012345"
      }
    ]
  }
}

For more details on this API, see business.update

Step 1: Create Account Provisioning Workflow

Create a new workflow of type ACCOUNT_PROVISIONING using the subject_record_id from your completed business application:

POST https://api.kompliant.com/workflow.create

Request Body:

{
  "account_id": "your_account_id",
  "workflow": {
    "type": "ACCOUNT_PROVISIONING",
    "subject_record_id": "sr_from_business_application"
  }
}

For more details on this API, see workflow.create.

Step 2: Create MBTrust Provisioning Entity

Create an account provisioning entity to track the provisioning activities with Merrick Bank:

POST https://api.kompliant.com/mbtrust.create

Request Body:

{
  "workflow_id": "w_from_workflow_create",
  "provisioning_sponsor": "MERRICK"
}

For more details on this API, see mbtrust.create.

Step 3: Validate Provisioning Requirements

Before executing provisioning operations, validate that all requirements are met using the existing Subject Record data:

POST https://api.kompliant.com/mbtrust.canExecute

Request Body:

{
  "mbtrust_id": "ape_from_mbtrust_create"
}

For more details on this API, see mbtrust.canExecute.

Step 4: Execute Provisioning Operations

Once validation confirms all requirements are met, execute the provisioning operations:

POST https://api.kompliant.com/mbtrust.execute

Request Body (Basic):

{
  "mbtrust_id": "ape_from_mbtrust_create"
}

Request Body (With Specific Documents):

To sync only specific documents (instead of all eligible documents), provide their IDs:

{
  "mbtrust_id": "ape_from_mbtrust_create",
  "documents": {
    "uploaded_documents": [
      "d_document_id_1",
      "d_document_id_2"
    ]
  }
}

For more details on this API, see mbtrust.execute.

For more details on document selection, see MBTrust Document Selection .

Step 5: Monitor Operation Status

Monitor the status of provisioning operations using webhooks (recommended) or polling with the mbtrust.get endpoint.

Webhook Notifications (Recommended)

When provisioning operations complete, the system sends webhook notifications with real-time status updates. Webhooks provide immediate notification when operations complete, eliminating the need for polling.

📘

Webhook Configuration Required

To receive webhook notifications, you must contact the Kompliant team to configure your webhook endpoint. You cannot set up webhooks through the API directly.

For more information about webhooks, see Webhook Notifications .

Polling with mbtrust.get (Alternative)

f webhooks are not configured or you need to check status on-demand, you can use the mbtrust.get endpoint.

POST https://api.kompliant.com/mbtrust.get

Request Body:

{
  "mbtrust_id": "ape_from_mbtrust_create"
}

For more details on this API, see mbtrust.get.

Complete Integration Flow

This diagram shows the complete flow for provisioning after a business application:

Business Application Complete (Subject Record has all data including MID)
    ↓
workflow.create
    ↓
mbtrust.create
    ↓
mbtrust.canExecute
    ↓
mbtrust.execute
    ↓
[Receive webhook notification of completed onboarding]
    OR
mbtrust.get

Best Practices

1. Verify Application Completion: Ensure the BUSINESS_APPLICATION workflow has been completed before starting provisioning
2. Add MID Early: Include the MID during the business application process to eliminate an extra step
3. Validate Before Executing: Always call mbtrust.canExecute before mbtrust.execute to catch missing requirements early. Address all items in the missing_requirements array before executing operations.
4. Use Webhooks for Monitoring: Configure webhook notifications to receive real-time updates when operations complete. This is more efficient than polling and ensures immediate notification.
5. Store Entity IDs: Save all entity IDs returned from API responses (workflow_id, subject_record_id, business_id, person_id, mbtrust_id, etc.). You'll need these for subsequent operations and troubleshooting.
6. Handle Errors Gracefully: Check meta.status in all responses and handle ERROR responses appropriately. Refer to Error Code Reference for detailed error handling guidance.