Documentation
kompliant.com

Direct MBTrust Account Provisioning

Suggest Edits

This integration guide demonstrates how to provision merchant accounts with external payment processing partners when you have all the necessary Subject Record data and want to execute the Account-Provisioning workflow directly.

This approach is ideal for automated merchant migrations, or headless API implementations where you're programmatically creating all entities without needing a prior Business-Application workflow.

Overview

Account provisioning in Kompliant enables seamless integration with payment processors by submitting merchant data and supporting documents to external sponsors. The system uses an Account-Provisioning Workflow to manage the provisioning process with partners like MBTrust via the Merrick Bank sponsor.

A typical account provisioning workflow involves the following steps:

  1. Create Account Provisioning Workflow
  2. Add business details include the Merchant ID (MID)
  3. Add business owners
  4. Add bank accounts
  5. Add sales information
  6. Upload required documents (optional)
  7. Create MBTrust provisioning entity
  8. Validate provisioning requirements
  9. Execute provisioning operations
  10. Monitor operation status

This guide walks you through the sequence of API calls needed to complete these steps.

Step 1: Create an Account Provisioning Workflow

The first step is to create a workflow of type ACCOUNT_PROVISIONING. This will automatically create a Subject Record for you. The Account ID is supplied to you when you receive your credentials.

Create a workflow of type ACCOUNT_PROVISIONING to serve as the container for all provisioning activities. The workflow must be in STARTED state for provisioning operations.

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

Request Body:

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

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

Step 2: Add Business Information Including Merchant ID

Once you have the subject record ID from the previous step, you can add business details. Include the Merchant ID (MID) in the additional_fields array. The MID is required for all MBTrust provisioning operations.

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

Request Body:

{
  "subject_record_id": "sr_from_previous_step",
  "business": {
    "legal_name": "Example Business LLC",
    "operating_name": "Example Business",
    "registration_type": "LLC_PRIVATE",
    "tax_id": "123456789",
    "phone_number": "(555) 123-4567",
    "industry_category_codes": [
      {
        "type": "MCC",
        "code": "5734",
        "details": {
          "mcc_details": {
            "card_brand": "MASTERCARD"
          }
        }
      }
    ],
    "addresses": [
      {
        "type": "LEGAL",
        "line1": "123 Business Street",
        "city": "Businessville",
        "state": "CA",
        "postal_code": "90210",
        "country": "US"
      }
    ],
    "additional_fields": [
      {
        "field_name": "merrick_mid",
        "field_value": "123456789012345"
      }
    ]
  }
}

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

Step 3: Add Business Owners

Now you will need to add the owners. At minimum you will need to add the control prong but can also include ownership prong owners as well.

For each owner do the following:

3.1 Create the Person

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

Request Body:

{
  "subject_record_id": "sr_from_previous_step",
  "person": {
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1980-01-15",
    "tax_id": "123456789",
    "citizenship": "US",
    "phone_number": "(555) 987-6543",
    "addresses": [
      {
        "type": "PRIMARY_RESIDENCE",
        "line1": "456 Controller Lane",
        "city": "Businessville",
        "state": "CA",
        "postal_code": "90210",
        "country": "US"
      }
    ]
  }
}

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

3.2 Associate Person as Control Prong or Ownership Prong

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

Request Body:

{
  "business_id": "b_from_business_create",
  "business_owner": {
    "person_id": "p_from_person_create",
    "ownership_type": "CONTROL_PRONG", // or OWNERSHIP_PRONG
    "ownership_percentage": 15,
    "ownership_year_month": "2020-01",
    "business_person_position": "PRESIDENT"
  }
}

For more details on this API, see business.addOwner.

Step 4: Add Bank Accounts

For each bank account associated with the business:

4.1 Create the Bank Account

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

Request Body:

{
  "subject_record_id": "sr_from_workflow_create",
  "bank_account": {
    "bank_account_ownership_type": "BUSINESS",
    "bank_account_type": "CHECKING",
    "bank_routing_number": "021000021",
    "bank_account_number": "1234567890123",
    "bank_name": "Example Bank"
  }
}

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

4.2 Associate Bank Account with Business

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

Request Body:

{
  "business_id": "b_from_business_create",
  "business_bank_account": {
    "bank_account_id": "ba_from_bank_account_create",
    "bank_account_purposes": ["PRIMARY", "FEES", "SETTLEMENT"]
  }
}

For more details on this API, see business.addBankAccount.

Step 5: Add Sales Information

Next add sales information for the business, including card brands, sales methods, and volume amounts. 

POST https://api.kompliant.com/business.salesInfo.create

Request Body:

{
  "business_id": "b_from_business_create",
  "sales_info": {
    "card_brands": [
      "AMEX"
    ],
    "sales_method": {
      "retail": 25,
      "telephone": 25,
      "online": 25,
      "keyed": 25
    },
    "sales_amount": [
      {
        "type": "AVERAGE_MONTHLY_CREDIT_SALES",
        "value": 999,
        "currency": "USD"
      },
      {
        "type": "AVERAGE_INDIVIDUAL_SALE",
        "value": 99,
        "currency": "USD"
      },
      {
        "type": "HIGHEST_TICKET_SALE",
        "value": 199,
        "currency": "USD"
      }
    ]
  }
}

For more details on this API, see business.salesInfo.create.

Step 6: Upload Required Documents (Optional)

Upload any required documents for the provisioning process. Documents are only needed if you plan to execute DOCUMENT_SYNC operations in addition to ONBOARDING operations.

Documents are not required for basic merchant onboarding. You can complete the ONBOARDING operation without uploading any documents. Only upload documents if your integration requires DOCUMENT_SYNC operations for additional compliance or verification purposes.

For complete details on uploading documents, including creating document records, uploading files to S3, and linking documents to workflow requirements, see Uploading Documents via API.

Step 7: Create MBTrust Provisioning Entity

Once all entities are created, associated, and documents are uploaded, create the account provisioning entity. This initiates the provisioning process with Merrick Bank. Using the workflow ID from the first step, do the following:

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 8: Validate Provisioning Requirements

Before executing provisioning operations, validate that all requirements are met. This endpoint checks for missing or incomplete information.

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 9: Execute Provisioning Operations

Once validation confirms all requirements are met, execute the provisioning operations. This queues the operations for asynchronous processing.

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.

Step 10: 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)

If 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 end-to-end flow for provisioning a merchant account:

workflow.create
    ↓
business.create
    ↓
person.create (Control Prong)
    ↓
business.addOwner (Control Prong)
    ↓
person.create (Ownership Prong 1)
    ↓
business.addOwner (Ownership Prong 1)
    ↓
[Repeat for additional owners if needed]
    ↓
bankAccount.create
    ↓
business.addBankAccount
    ↓
[Repeat for additional bank accounts if needed]
    ↓
business.salesInfo.create
    ↓
[Document uploads, if needed]
    ↓
mbtrust.create
    ↓
mbtrust.canExecute
    ↓
mbtrust.execute
    ↓
[Receive webhook notification of completed onboarding]
    OR
mbtrust.get

Best Practices

Follow these recommendations to ensure a smooth account provisioning experience:

  1. Complete All Entity Setup First: Create and associate all required entities (business, person, bank account, sales info) before creating the MBTrust provisioning entity. This ensures validation passes on the first attempt.

  2. Always Include MID: The Merchant ID (MID) must be included in the business entity's additional_fields array with the field name merrick_mid. This is required for both ONBOARDING and DOCUMENT_SYNC operations.

  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. Upload Documents Before Provisioning: Ensure all required documents are uploaded successfully before creating the MBTrust entity. This includes both creating document records and completing the file upload to S3. See Uploading Documents via API for complete upload workflow and best practices.

  5. 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.

  6. Handle Asynchronous Processing: Operations are processed asynchronously. Don't expect immediate completion after calling mbtrust.execute. Plan your integration to handle delays and status checking.

  7. 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.

  8. Handle Errors Gracefully: Check meta.status in all responses and handle ERROR responses appropriately. Refer to Error Code Reference for detailed error handling guidance.

  9. Test in Sandbox First: Test your complete integration flow in the sandbox environment before moving to production. This allows you to verify your implementation without affecting real merchant accounts.

  10. Monitor Entity Status: After successful provisioning, the account provisioning entity status will change to ACTIVE. Monitor this status to confirm the account is ready for use.

  11. Keep Entity Data Current: Use business.update to keep business information current, including MID if it changes. This ensures document sync operations continue to work correctly.

  12. Requirement Codes: Familiarize yourself with the MBTRUST_MISSING_REQUIREMENTS enum to quickly identify and resolve validation errors.

Updated about 2 months ago