Documentation
kompliant.com

Direct ProPay Account Provisioning

Suggest Edits

This integration guide demonstrates how to provision merchant accounts with ProPay (Global Payments) 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

ProPay account provisioning in Kompliant enables seamless integration with Global Payments by submitting complete merchant data for onboarding. The system uses an Account-Provisioning Workflow to manage the provisioning process.

A typical ProPay account provisioning workflow involves the following steps:

  1. Create Account Provisioning Workflow
  2. Add business details with registration type
  3. Add business owners (with SSN and DOB)
  4. Add bank accounts
  5. Add sales information
  6. Create ProPay provisioning entity
  7. Validate provisioning requirements
  8. Execute provisioning operations
  9. 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 with Registration Type

Once you have the subject record ID from the previous step, you can add business details. Important: ProPay requires a valid registration type and does NOT require a Merchant ID (unlike MBTrust).

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"
      },
      {
        "type": "BUSINESS",
        "line1": "123 Business Street",
        "city": "Businessville",
        "state": "CA",
        "postal_code": "90210",
        "country": "US"
      }
    ]
  }
}

Key ProPay Requirements:

  • registration_type is required (must be one of: Corporation, LLC, Sole Proprietorship, Partnership, Government, Non-Profit)
  • Both LEGAL (primary) and BUSINESS (mailing) addresses are required
  • No Merchant ID needed (unlike MBTrust)

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

Step 3: Add Business Owners

ProPay requires at least one business owner with complete information including SSN, date of birth, and ownership percentage.

For each owner do the following:

3.1 Create the Person

Important: ProPay requires tax_id (SSN) and date_of_birth for all business owners.

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 Business Owner

Important: ProPay requires ownership_percentage for all business owners.

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",
    "ownership_percentage": 25,
    "ownership_year_month": "2020-01",
    "business_person_position": "PRESIDENT"
  }
}

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

📘

Repeat for Additional Owners

If the business has multiple owners, repeat steps 3.1 and 3.2 for each owner. Ensure the total ownership percentage adds up appropriately.

Step 4: Add Bank Accounts

ProPay requires a bank account with routing number, account number, and a valid account type.

4.1 Create the Bank Account

Important: Account type must be one of: SAVINGS, CHECKING, or GENERAL_LEDGER.

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

ProPay requires sales information with monthly volume, average ticket, and highest ticket amounts.

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

Request Body:

{
  "business_id": "b_from_business_create",
  "sales_info": {
    "card_brands": [
      "VISA",
      "MASTERCARD",
      "AMEX"
    ],
    "sales_method": {
      "retail": 25,
      "telephone": 25,
      "online": 25,
      "keyed": 25
    },
    "sales_amount": [
      {
        "type": "AVERAGE_MONTHLY_CREDIT_SALES",
        "value": 50000,
        "currency": "USD"
      },
      {
        "type": "AVERAGE_INDIVIDUAL_SALE",
        "value": 150,
        "currency": "USD"
      },
      {
        "type": "HIGHEST_TICKET_SALE",
        "value": 500,
        "currency": "USD"
      }
    ]
  }
}

Key ProPay Requirements:

  • AVERAGE_MONTHLY_CREDIT_SALES is required
  • AVERAGE_INDIVIDUAL_SALE is required
  • HIGHEST_TICKET_SALE is required

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

Step 6: Create ProPay Provisioning Entity

Once all entities are created and associated, create the ProPay account provisioning entity. This initiates the provisioning process with Global Payments.

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

Request Body:

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

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

Step 7: 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/propay.canExecute

Request Body:

{
  "propay_id": "ape_from_propay_create"
}

Response Example:

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_6zNzQZHSf26V83BO3uW6dS",
    "version": "2025-03-24"
  },
  "data": {
    "can_execute": true,
    "missing_requirements": []
  }
}

If can_execute is false, review the missing_requirements array and fix each issue before proceeding. See ProPay Validation Reference for detailed resolution steps.

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

Step 8: 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/propay.execute

Request Body:

{
  "propay_id": "ape_from_propay_create"
}

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

Step 9: Monitor Operation Status

Monitor the status of provisioning operations using webhooks (recommended) or polling with the propay.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 propay.get (Alternative)

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

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

Request Body:

{
  "propay_id": "ape_from_propay_create"
}

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

Complete Integration Flow

This diagram shows the complete end-to-end flow for ProPay provisioning:

workflow.create
    ↓
business.create (with registration_type, no MID needed)
    ↓
person.create (with SSN and DOB)
    ↓
business.addOwner (with ownership_percentage)
    ↓
[Repeat for additional owners if needed]
    ↓
bankAccount.create (with valid account_type)
    ↓
business.addBankAccount
    ↓
business.salesInfo.create (with all required amounts)
    ↓
propay.create
    ↓
propay.canExecute
    ↓
[If missing requirements, fix them and retry]
    ↓
propay.execute
    ↓
[Receive webhook notification of completed onboarding]
    OR
propay.get

Best Practices

Follow these recommendations to ensure a smooth ProPay account provisioning experience:

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

  2. Include Registration Type: The business registration type is required for ProPay. Valid types include Corporation (private/public), LLC (private/public), Sole Proprietorship, Partnership (private/public), Government, or Non-Profit.

  3. Collect SSN and DOB: ProPay requires SSN (tax_id) and date of birth for all business owners. Ensure you collect this information before starting the provisioning process.

  4. Specify Ownership Percentage: Each business owner must have an ownership_percentage specified. This is required by ProPay for all owners.

  5. Use Valid Account Types: Bank account type must be one of: SAVINGS, CHECKING, or GENERAL_LEDGER. Other account types will fail validation.

  6. Include All Sales Amounts: ProPay requires three specific sales amounts: AVERAGE_MONTHLY_CREDIT_SALES, AVERAGE_INDIVIDUAL_SALE, and HIGHEST_TICKET_SALE. All three must be provided.

  7. Provide Both Addresses: Ensure both LEGAL (primary/physical) and BUSINESS (mailing) addresses are complete with all required fields (line1, city, state, postal_code).

  8. Validate Before Executing: Always call propay.canExecute before propay.execute to catch missing requirements early. Address all items in the missing_requirements array before executing operations.

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

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

  11. Store Entity IDs: Save all entity IDs returned from API responses (workflow_id, subject_record_id, business_id, person_id, propay_id, etc.). You'll need these for subsequent operations and troubleshooting.

  12. Handle Errors Gracefully: Check meta.status in all responses and handle ERROR responses appropriately. Refer to ProPay Validation Reference for detailed error handling guidance.

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

  14. Verify Partner Configuration: Ensure ProPay is enabled for your account and that Tier Code is configured. Contact Kompliant support if you encounter PROVISIONER_DISABLED or TIER_CODE_REQUIRED errors.

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

Key Differences from MBTrust

ProPay provisioning has some important differences from MBTrust:

  • No Merchant ID Required: ProPay does not require a Merchant ID (MID) in the business entity
  • Registration Type Mandatory: Business registration type must be specified and valid for ProPay
  • SSN and DOB Required: Business owner SSN and date of birth are mandatory (not optional)
  • Ownership Percentage Required: Each business owner must have an ownership percentage
  • Specific Account Types: Bank account type must be SAVINGS, CHECKING, or GENERAL_LEDGER
  • Three Sales Amounts Required: Must provide monthly volume, average ticket, and highest ticket
  • Single Operation: Currently, only ONBOARDING operation is supported (no separate document sync)
  • Configuration Requirements: Tier Code must be pre-configured by Kompliant support
  • Address Requirements: Both primary and business addresses must be complete