This reference helps you resolve MBTrust validation errors returned by mbtrust.canExecute. When validation fails, follow the troubleshooting steps below to identify and fix the issues.

Quick Troubleshooting

When mbtrust.canExecute returns can_execute: false, follow this workflow:

1. Check the error codes: Review the missing_requirements array in the response
2. Look up error meanings: Use the MBTRUST_MISSING_REQUIREMENTS reference for each error code
3. Fix using API endpoints: Each error description includes links to the relevant API endpoints
4. Retry validation: Call mbtrust.canExecute again until can_execute: true

Key Resources

Error Code Reference

MBTRUST_MISSING_REQUIREMENTS - Complete list of validation error codes with descriptions and resolution links.

Integration Guides

Choose the guide that matches your workflow:

• Account Provisioning After Application - When you've completed a Business Application workflow first
• Direct Account Provisioning - When building all entities programmatically
• MBTrust Document Selection - When specifying documents to be syunched.
  
  

API Documentation

For detailed field requirements and examples:

• business.create - Business entity fields
• person.create - Person entity fields
• bankAccount.create - Bank account fields
• business.addOwner - Ownership associations
• business.addBankAccount - Bank account associations
• business.salesInfo.create - Sales information
• Uploading Documents via API - Document upload workflow

MBTrust-Specific Requirements

Unlike standard API calls where many fields are optional, MBTrust validation requires specific data to be populated:

Merchant ID (MID)

• Required for all operations: Must be added to business entity's additional_fields array
• Field name: Use merrick_mid
• When to add: During business.create or via business.update
• Related API methods: business.create, business.update

Required Entity Completeness

While API endpoints allow partial data, MBTrust requires:

• Complete business information (legal name, tax ID, addresses, MCC, phone, email)
• At least one business owner with full personal details
• Bank account with routing and account numbers
• Sales information with volume projections and method breakdowns

Common Validation Patterns

Missing Core Entities

Error: ENTITY_REQUIRED
Fix: Create missing entities using the create endpoints listed above

Incomplete Field Data

Error: FIELDS_REQUIRED
Fix: Check the fields array in the error response, then populate missing fields using the appropriate update endpoints

Configuration Issues

Errors: ACCOUNT_PROVISIONING_DISABLED, ACCOUNT_PROVISIONING_ONBOARDING_DISABLED, ACCOUNT_PROVISIONING_DOCUMENT_SYNC_DISABLED
Fix: Contact support to enable the required provisioning features

Merchant ID Issues

Error: MERCHANT_ID_REQUIRED
Fix: Add Merchant ID to business additional_fields using field name merrick_mid

Error: MERCHANT_ID_NOT_MATCHING
Fix: The onboarded Merchant ID does not match the current Merchant ID. Either complete a new onboarding with the current MID or update to the correct MID.

Error: MERCHANT_NOT_ONBOARDED
Fix: Complete merchant onboarding before attempting document sync operations. Document sync requires a successful onboarding first.

Document Requirements

Errors: DOCUMENT_REQUIRED, NO_DOCUMENTS_REQUIRED
Fix: Follow the document upload workflow to upload and link required documents. Use document.create or workflow.requiredDocument.fulfillment.batchAdd to fulfill document requirements.

Best Practices

1. Validate early: Call mbtrust.canExecute before attempting operations to catch issues upfront
2. Build complete entities: Populate all required fields during initial entity creation rather than updating later
3. Use integration guides: Follow the step-by-step workflows rather than building ad-hoc API call sequences
4. Test in sandbox: Verify your validation logic works before production deployment

Execution Error Codes

In addition to validation errors from mbtrust.canExecute, you may encounter error codes in the mbtrust.get response after executing operations. These errors appear in the execution_results[].errors array.

Operation Execution Errors

Document Sync Errors

When using the documents parameter with mbtrust.execute, you may encounter these additional errors:

📘

Partial Success

Document sync operations can partially succeed. When some documents upload successfully and others fail, the operation status will be SUCCESS but the errors array will contain details about failed documents. Check uploaded_document_ids in the response to see which documents were successfully uploaded.

For complete details on the mbtrust.get response structure and all error codes, see mbtrust.get.