Guides

Apply Wizard Traditional

Onboarding a Traditional Merchant with Apply Wizard

This guide is for developers using the Payarc Apply Wizard API to submit and manage Traditional merchant applications.

Overview

This guide walks through the complete Apply Wizard flow for Traditional merchant onboarding — from submitting an initial Lead record to receiving confirmation that the merchant's account is fully activated and ready to process payments.

Prerequisites

Before you begin, make sure you have:

  • A valid Bearer token from Partner Hub — see API Authentication
  • Access to the Payarc API sandbox or production environment — see here
  • Merchant business and owner information ready for the Lead application (legal business name, address, EIN, ownership details, and estimated processing volume)
  • A configured webhook endpoint to receive the Merchant Onboarded event. Unlike Payfac, there is no Merchant Activated event.

Step 1: Submit a Lead Application

The Apply Wizard flow starts by registering the merchant as a Lead. This creates a record in the system and signals your intent to onboard a new Traditional merchant under your account. No underwriting happens yet — this step simply establishes the merchant's identity, and creates the Lead record in the Payarc system. This call returns the MerchantCode you'll use throughout the rest of the process.

To create a Traditional Lead Application, see the API Reference: here

What you get back: The response includes a MerchantCode — a unique identifier for this merchant's application used in all subsequent calls.

💡

Tip: Store the MerchantCode as soon as it's returned. It links every downstream step — application submission, status checks, and any Lead corrections — back to this specific merchant record.

Step 2: Submit the Full Application

With the MerchantCode in hand, the application is submitted via an API call. Next, both the Terms and Conditions and the Full Application are emailed to the merchant for signature. Once the signature is done, the application is submitted automatically for processing, ready for underwriting review. This is where business details, ownership information, processing estimates, and any required documentation are sent to Payarc.

To submit the application, see the API Reference: here

To submit documents, see the API Reference: here

What you get back: Payarc processes the application and returns either a successful boarding response or an error response indicating the submission failed and needs correction.

💡

Tip: If any documents are needed after this step, it will be done in coordination with Underwriting. Refer to the Underwriting Team with any questions.

💡

Tip: Thoroughly validate all required fields before submitting. Incomplete or incorrect data will cause a submission failure that requires a Lead update and resubmission cycle, adding unnecessary delay to the merchant's activation timeline.

Step 3: Get Lead Status

While the application is in processing, the developer can use 2 methods to check the status of the application.

Option 1: Receive Webhook Notifications

When the merchant account is created and boarded in Merchant Dashboard, Payarc automatically sends a webhook event (Merchant Onboarded) to your configured endpoint. This is your definitive signals that the Traditional merchant's account is ready.

Merchant Onboarded — Fires when the merchant has been boarded and their Merchant Dashboard account has been created. The merchant exists in the system and has a live MID, but may not yet be fully cleared for payment processing.

💡

Tip: For Traditional merchants, the Merchant Onboarded webhook is the only webhook that is used.

💡

Tip: Even though Payarc automatically sends the webhook event, you still need to configure it. Please contact the support team in order to configure the desired webhook event. You will need to setup a webhook listener on your end and provide the team with the URL you wish to have configure. Refer to this page for help in configuring your webhook.

Option 2: Poll for Merchant Account Status

Payarc offers the Lead Status API endpoint to poll the merchant account status.

To poll the merchant account status, see the API Reference: here

What you get back: The current status of the merchant's account creation.

💡

Tip: Continue polling until the status confirms the Merchant Dashboard account has been created, or until the webhook from Option 1 arrives. If Option 1 fails, then Option 2 should be used.

Handle a Failed Submission

Validation of the Full Application happens when the Lead is submitted. If Payarc returns a submission failure, there's no need to start the process from scratch. The existing Lead record stays intact — simply correct the flagged data, update the Lead, and resubmit. This can be done in 2 ways:

Step 1: Update the Lead Record

Patch the Lead with the corrected application data by using the MerchantCode as the id in the Update Traditional Lead API call.

To update the Traditional Lead Application, see the API Reference: here

Step 2: Resubmit the Application

Once the Lead is updated, resubmit the application using the same endpoint from Step 2, and continue to follow the subsequent steps.

💡

Tip: Review all fields flagged in the error response and address them together in a single update call before resubmitting — this keeps the correction loop as short as possible.

What's Next

Now that your Traditional merchant is onboarded through Apply Wizard, you can:

Updated about 2 hours ago