All pages
Powered by GitBook
1 of 10

Automated Merchant Onboarding

Automated Merchant Onboarding solution offers a lightweight and efficient way of adding new merchants while ensuring good user experience. With streamlined onboarding and automated payment processing, businesses can quickly and efficiently integrate new merchants. This solution eliminates the need for complex development or manual paperwork, ensuring a hassle-free onboarding process.

Note: Automated Merchant Onboarding was previously known as Launch for Integrator (L4I). You might still see references to L4I in some systems or materials.

For more information on the Automated Merchant Onboarding solution, refer to the following articles:

Prerequisites

To begin with Automated Merchant Onboarding, you must complete an account setup and integration with the system. This includes:

  1. Gaining access to the test environment.

  2. Configuring specific settings with the help of a support team.

  3. Providing key URLs to ensure smooth communication and updates throughout the process.

Working with Automated Merchant Onboarding

Working with Automated Merchant Onboarding involves:

Generating a Merchant Application

Note: The following steps are performed by the Partner, who is responsible for collecting merchant details and initiating the onboarding process.

To generate a merchant application:

1

Create a Merchant Application

To initiate merchant onboarding, collect the required details during your sign-up process. This includes the merchant’s email, business name, and Merchant Category Code (MCC).

{
    "merchantInformation": {
        "dbaName": "Stark Industries",
        "emailAddress": "tstark@starkindustries.com"
    },
    "salesProfile": {
        "mccCode": "5085"
    }
}

With these basic details, a merchant can initiate the onboarding process. The Automated Merchant Onboarding tool allows merchants to onboard into the system with minimal input, reducing integration efforts and streamlining the application process.

To further optimize the onboarding process, include all essential information upfront when passing data to the associated API (Launch for Integrators API). By providing comprehensive client-specific details in the POST request, you ensure that the generated application URL is pre-filled with relevant data. This minimizes redundant data entry for merchants, accelerates the onboarding process, and reduces potential delays.

{
    "merchant": {
        "merchantInformation": {
            "dbaName": "Stark Industries",
            "merchantNumber": "6588949992012345",
            "emailAddress": "tstark@starkindustries.com",
            "website": “starkindustries.com”,
            "phones": null,
            "acceptsPaperStatements": false,
            "acceptsPaperTaxForms": false,
            "companyTypeId": 0,
            "seasonalSchedule": null,
            "salesInformation": null
        },
        "mailingAddress": null,
        "physicalAddress": null,
        "bankAccounts": null,
        "businessContacts": null,
        "salesProfile": {
            "useExtraCnpValidation": true,
            "mccCode": "5085",
            "cardPresentPercentage": 0.0,
            "motoKeyedPercentage": 0.0,
            "eCommercePercentage": 0.0,
            "returnRefundPolicy": null,
            "productsSold": null,
            "previouslyAcceptedPaymentCards": false,
            "previouslyTerminatedOrIdentifiedByRiskMonitoring": false,
            "reasonPreviouslyTerminatedOrIdentifiedByRisk": null,
            "currentlyOpenForBusiness": false,
            "annualVolume": 0.0,
            "averageTicket": 0.0,
            "highTicket": 0.0,
            "ownsProduct": false,
            "ordersProduct": false,
            "sellsFirearms": false,
            "sellsFirearmAccessories": false,
            "futureDeliveryTypeId": null,
            "otherDeliveryType": null,
            "futureDeliveryPercentage": 0.0,
            "fireArmsLicense": null,
            "cardBrands": null,
            "ebtNumber": null,
            "amexMID": null,
            "sellsCBD": false,
            "cbdSalesTypeID": null,
            "salesProfileCBD": null
        },
        "taxpayer": null,
        "externalCustomerId": null,
        "pricingPlan": {
            "pricingFees": [
                {
                    ...
                }
            ],
            "pricingPlanID": 13539,
            "pricingPlanTemplateID": 1060,
            "pricingTypeCode": "D",
            "isAdvancedPricing": false,
            "isEMF": false,
            "isDailySettle": true,
            "includeAssessments": false
        }
    },
    "applicationURL": "https://boarding-sb.clearent.net/launch-integrator-setup/merchant/4c87c74b-a483-4d4f-8656-b412345abcde",
    "errors": [],
    "metadata": {
        "exchangeId": "ID-clearent-security-edge-proxy-service-2-64e45785-eedd-40ae-a580-7d7709930004",
        "timestamp": "2024-06-28T15:10:53.7273247Z"
    }
}
2

Redirecting to the Application URL

After generating the application, the system generates an Application URL. You can either redirect the merchant automatically or send the link via email for them to complete the process.

{
…
"applicationURL": "https://boarding-sb.clearent.net/launch-integrator-setup/merchant/4c87c74b-a483-4d4f-8656-b46a59e2e3d4",
…
}

Once redirected, the merchant lands on the Automated Merchant Onboarding hosted application page, where they can enter additional details, verify their identity, and sign required documents digitally, ensuring a fast and seamless onboarding experience.

The applicant has seven days from the creation date to complete the application. If the application is not completed within seven days, the application will expire, and a new application will need to be created and completed.

Completing the Application

Note: The following steps are performed by the Merchant. After receiving the application link, the Merchant completes and submits their application through the Automated Merchant Onboarding tool.

To complete a merchant application:

1

Set an Acceptance PIN

To protect sensitive merchant data, Automated Merchant Onboarding requires users to set a 4-digit security PIN when starting an application. This PIN prevents unauthorized access to in-progress applications.

If the application session is abandoned, users must enter their previously created PIN to resume the process. After entering the PIN, they can click Continue to proceed with the application.

2

Enter an Existing PIN

If a user returns to an incomplete application, they will be prompted to enter their previously configured PIN to continue from where they left off.

3

Reset an Invalid or Forgotten PIN

If the PIN entry is invalid or forgotten, users can click Forgot PIN? to reset it.

After selecting Forgot PIN? users will receive a reset link via email. Clicking the reset link invalidates the old PIN and prompts the user to create a new PIN before accessing the application.

The PIN reset email is sent to the primary email address provided in the emailAddress object within the merchantInformation array during the initial merchant creation request to the Automated Merchant Onboarding web service.

When users click the reset link, they will be redirected to the Automated Merchant Onboarding application to create a new PIN. Once set, they can continue the application from where they left off.

4

Completing the Application

Automated Merchant Onboarding ensures data integrity and security by validating all submitted information before finalizing the application. The platform performs comprehensive input validation, checking data formats like email addresses and phone numbers and verifying that inputs meet the required criteria.

These security measures help maintain accuracy, compliance, and a smooth user experience throughout the onboarding process.

5

Signing the Merchant Agreement

Each designated contact signer must provide electronic consent before signing application documents. This consent enables the use of digital signatures and electronic records, replacing traditional paper-based processes.

Once the user reviews and agrees to the terms, they can sign electronically to confirm their acceptance of the agreement.

6

Finalizing Application Terms

After providing consent, users can proceed to review and sign all required application documents. Automated Merchant Onboarding guides them through the process, ensuring all necessary steps are completed.

Once the application is finalized, users can be automatically redirected to a designated URL for a seamless transition. This feature allows businesses to guide users to a confirmation page, additional resources, or any custom destination, optimizing the onboarding journey.

Modifying Default Merchant Pricing

Automated Merchant Onboarding offers flexible pricing options, enabling software partners to modify predefined pricing structures to match their business needs and sales strategies. Instead of using a static pricing model, software partners can retrieve existing pricing templates, modify fees, and apply customized pricing plans at the merchant level.

For more information on modifying default merchant pricing, refer to the following articles:

Retrieving Existing Pricing Templates

To modify merchant pricing, you must first retrieve the available pricing templates from the Automated Merchant Onboarding system. These templates define different pricing structures, which can be assigned to merchants based on their business model and service requirements.

The API (Pricing Plan API) enables integrators to fetch a list of available pricing templates associated with a merchant, which can be used as a base for further modifications.

This includes the following steps:

1

Fetch Available Pricing Templates

To retrieve the pricing templates for a specific merchant, send a GET request to the Pricing Plan API. This will return a list of all pricing templates that are currently available for the merchant.

  • API Endpoint: GET /api/pricing/v2/PricingPlan/{merchantNumber}/templates

  • Request Parameter: merchantNumber - It identifies the merchant whose pricing templates need to be retrieved.

2

Understand the API Response

A successful response provides a list of available pricing templates, allowing integrators to select the most suitable plan for each merchant.

[
    {
      "pricingPlanTemplateID": 101,
      "hierarchyNodeKey": "987654321",
      "templateName": "Standard Pricing Plan",
      "pricingTypeCode": "STANDARD",
      "isAdvancedPricing": false,
      "isDefaultTemplate": true,
      "isDisabled": false,
      "templateFees": [
        {
          "clearentPricingFeeID": 2001,
          "clearentPricingFeeDescription": "Transaction Fee",
          "isEditable": true,
          "isRequired": true,
          "isVisible": true,
          "isFee": true,
          "isRate": true,
          "isPayInMonthRequired1": false,
          "isPayInMonthRequired2": false,
          "defaultRate": 2.5,
          "minRate": 2.0,
          "maxRate": 3.5,
          "defaultFee": 0.30,
          "minFee": 0.25,
          "maxFee": 0.50,
          "rateLabel": "Percentage Rate",
          "feeLabel": "Fixed Fee"
        }
      ],
      "templateSettings": [
        {
          "pricingPlanSettingID": 5001,
          "settingName": "Daily Settlement",
          "description": "Enable daily settlement for transactions.",
          "isVisible": true,
          "isEditable": true,
          "defaultValue": true
        }
      ],
      "attributes": [
        {
          "name": "Region",
          "value": "USA",
          "type": "String"
        },
        {
          "name": "Currency",
          "value": "USD",
          "type": "String"
        }
      ]
    }
]

Modifying Pricing Fees & Completing Merchant Application Record

Once you have selected a pricing template, you can apply and modify the pricing fees before finalizing the merchant application. Use the Create a Merchant endpoint to:

  • Assign a pricing plan to the merchant.

  • Modify the pricing fees under the selected plan.

  • Complete the merchant application process with the required pricing details.

Adjusting pricing at this stage ensures that each merchant receives a tailored pricing structure that aligns with their business requirements.

This includes the following steps:

1

Submit Merchant Pricing Details

To onboard a merchant and apply pricing fees, send a POST request with the pricing details.

  • API Endpoint:

POST /api/launchIntegratorSetup/v1.0/integrateMerchant/{hierarchyNodeKey}

  • Path Parameter: hierarchyNodeKey - It identifies the hierarchy level under which the merchant is being onboarded.

{
  "pricingPlan": {
    "pricingFees": [
      {
        "clearentPricingFeeID": 101,
        "pricingFeeDescription": "Transaction Fee",
        "rate": 2.5,
        "fee": 0.30,
        "payInMonth1": 12,
        "payInMonth2": 24
      }
    ],
    "pricingPlanID": 2001,
    "pricingPlanTemplateID": 3001,
    "pricingTypeCode": "STANDARD",
    "isAdvancedPricing": true,
    "isEMF": true,
    "isDailySettle": true,
    "includeAssessments": true
  }
}
2

Understand the API Response

A successful response confirms that the pricing plan has been applied and returns the merchant’s pricing details.

{
  "merchantNumber": "123456789",
  "status": "Active",
  "pricingPlan": {
    "pricingFees": [
      {
        "clearentPricingFeeID": 101,
        "pricingFeeDescription": "Transaction Fee",
        "rate": 2.5,
        "fee": 0.30,
        "payInMonth1": 12,
        "payInMonth2": 24
      }
    ],
    "pricingPlanID": 2001,
    "pricingPlanTemplateID": 3001,
    "pricingTypeCode": "STANDARD",
    "isAdvancedPricing": true,
    "isEMF": true,
    "isDailySettle": true,
    "includeAssessments": true
  },
  "message": "Merchant pricing plan successfully applied."
}

After the successful modification of the pricing plan, the merchant application record is updated, and the new pricing structure is applied automatically. This ensures that merchants receive the correct pricing without requiring manual intervention.

Merchant Onboarding Status Webhooks

The Automated Merchant Onboarding solution allows software partners to track their merchants' application progress using Application Status webhooks. By subscribing to these webhooks, integrators receive updates on any changes to a merchant’s application status. This eliminates the need for manual follow-ups and provides a seamless, automated tracking system.

For more information on merchant onboarding status webhooks, refer to the following document:

Configuring Automated Merchant Onboarding

The Automated Merchant Onboarding solution offers various configuration options to customize the merchant onboarding experience, ensuring seamless integration with your business operations. These settings help you tailor branding, communication, user management, and merchant support, creating a streamlined and efficient onboarding process.

Branding Options

Add Logo: Enhance brand recognition by adding your company’s logo to the onboarding interface. A branded experience builds trust and ensures consistency across all touchpoints, giving merchants a familiar and professional environment.

Communication Settings

Set a Postback URL: Define a Postback URL to receive real-time updates on merchant application status changes. This ensures that onboarding-related events—such as application approval, decline, or completion—are automatically communicated to your system, enabling timely and seamless updates.

Modify Support Contact Information

Customize the support email and phone number displayed in automated emails sent during the merchant application process. This ensures that merchants always have the correct contact details when they need assistance.

User Management

Automatically Create User Accounts: Enable automatic user account creation for the Merchant Portal and Virtual Terminal to simplify onboarding. This eliminates manual setup and ensures that merchants gain immediate access to their accounts upon approval.

Reminder Email Configuration

Set Automatic Reminder Intervals: Configure automated reminder emails to encourage merchants to complete their applications before the 7-day expiration period. The default reminder is sent 3 days before expiration, with options to send additional reminders 2 days or 1 day prior.

Application Completion

Predefine Completion of Application Field: Consult with a Xplor Pay representative to determine the best strategy for defining application completion. This ensures that onboarding requirements align with your business model and industry standards.