Documentation
kompliant.com

ProPay Account Provisioning After Application

Suggest Edits

This integration pattern demonstrates how to provision a merchant account with ProPay (Global Payments) 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, and sales information.

A typical ProPay account provisioning workflow involves the following steps:

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

Prerequisites

Before starting ProPay 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. Complete Business Information: Business entity with legal name, tax number, MCC, registration type, and addresses
  4. Business Owner Information: At least one business owner with complete details including SSN, date of birth, and ownership percentage
  5. Bank Account: A bank account associated with the business with routing number, account number, and account type
  6. Sales Information: Sales details including monthly volume, average ticket, and highest ticket amounts
  7. Partner Configuration: ProPay provisioning enabled with Tier Code configured (contact support)

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 ProPay Provisioning Entity

Create an account provisioning entity to track the provisioning activities 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 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/propay.canExecute

Request Body:

{
  "propay_id": "ape_from_propay_create"
}

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

Response Example with Missing Requirements:

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_6zNzQZHSf26V83BO3uW6dS",
    "version": "2025-03-24"
  },
  "data": {
    "can_execute": false,
    "missing_requirements": [
      {
        "code": "OWNER_SSN_REQUIRED",
        "entity_type": "BusinessOwner",
        "entity_id": "p_7h1EpxerrZQyLnRC1EQ9Ck",
        "message": "Business owner Social Security Number is required",
        "related_methods": [
          "person.create",
          "person.update"
        ]
      }
    ]
  }
}

If the response shows can_execute: false, review the missing_requirements array and address each issue using the suggested API methods. See ProPay Validation Reference for detailed resolution steps.

Step 4: Execute Provisioning Operations

Once validation confirms all requirements are met (can_execute: true), execute the provisioning operations:

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 5: 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 flow for ProPay provisioning after a business application:

Business Application Complete (Subject Record has all required data)
    ↓
workflow.create
    ↓
propay.create
    ↓
propay.canExecute
    ↓
[If missing requirements, fix them and retry propay.canExecute]
    ↓
propay.execute
    ↓
[Receive webhook notification of completed onboarding]
    OR
propay.get

Best Practices

  1. Verify Application Completion: Ensure the BUSINESS_APPLICATION workflow has been completed before starting provisioning
  2. Collect SSN and DOB: ProPay requires SSN and date of birth for all business owners. Ensure this information is collected during the application process
  3. Validate Registration Type: Ensure the business registration type is one of ProPay's supported types (Corporation, LLC, Sole Proprietorship, Partnership, Government, Non-Profit)
  4. 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
  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. 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
  7. Handle Errors Gracefully: Check meta.status in all responses and handle ERROR responses appropriately. Refer to ProPay Validation Reference for detailed error handling guidance
  8. Verify Partner Configuration: Ensure ProPay is enabled for your account and that Tier Code is configured. Contact support if you encounter PROVISIONER_DISABLED or TIER_CODE_REQUIRED 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
  • SSN and DOB Mandatory: Business owner SSN and date of birth are required for ProPay (may be optional in other workflows)
  • Registration Type Required: Business registration type must be specified and valid
  • Single Operation: Currently, only ONBOARDING operation is supported (no separate document sync)
  • Account Types: Bank account type must be one of: savings, checking, or general_ledger
  • Configuration Requirements: Tier Code must be pre-configured by Kompliant support

Updated 4 months ago