Guides

Apply Wizard Payfac

Onboarding a Merchant with Apply Wizard

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

Overview

This guide walks through the complete Apply Wizard flow for Payfac merchant applications. By the end, the merchant will have a live Merchant ID (MID), a Merchant Dashboard account, and accessible API keys.

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
  • A configured webhook endpoint to receive the Merchant Onboarded and Merchant Activated events

Step 1: Submit a Lead Application

Every Apply Wizard onboarding starts by submitting a Lead application using the Add Payfac Lead endpoint. This step registers the merchant's basic information with Payarc and opens the application on your behalf. Think of it as staking a place in the boarding queue — no processing yet, just establishing the merchant's identity.

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

What you get back: The response includes a MerchantCode — a unique identifier for this merchant's application that will be used in subsequent steps.

💡

Tip: Store the MerchantCode immediately. It ties every subsequent step — application submission, status polling, and Lead updates — back to this specific merchant record.

Step 2: Show Terms and Conditions To Merchant

With the MerchantCode in hand, partners MUST show their merchants the Terms and Conditions via the Get Terms and Conditions API endpoint. Once the Terms and Conditions are returned from the merchant, then the Full Application is submitted.

To send Terms and Conditions, see the API Reference: here

What you get back: Gets the Terms and Conditions that MUST be sent to the merchant to sign.

Step 3: Submit the Full Application

Once the Terms and Conditions are returned from the merchant, the complete merchant application is submitted. This is where all business details, owner information, processing estimates, and any required documentation are sent for underwriting review.

To submit the Full Application, see the API Reference: here

What you get back: Payarc processes the application and returns either a success response — confirming the merchant is boarded and a MID has been created — or an error response indicating the submission failed.

💡

Tip: Validate all required fields on your end before submitting. A failed submission requires you to update the Lead record and resubmit. See Step 3 if that happens.

Step 4: Get Lead Status

Payarc offers 2 methods to check the Lead Status that was sent.

Option 1: Receive Webhook Notifications

When the merchant's onboarding is complete and the merchant's full account created in the Merchant Dashboard, Payarc automatically sends two webhook events to your configured endpoint — no polling required at this stage.

Merchant Onboarded — Sent when the merchant has been boarded and their Merchant Dashboard account has been created. This confirms the full account exists in the system.

Merchant Activated — Sent when the merchant's account is fully activated and ready to process live payments. At this point, you can also retrieve the merchant's API keys programmatically.

💡

Tip: Use the Merchant Activated event as your definitive signal to provision the merchant's API keys and grant them access to your platform. Acting on Merchant Onboarded alone may be premature — the account exists but may not yet be ready for transactions.

💡

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

Option 2: Poll for Merchant Account Status

Payarc additionally offers a way for merchants to track the status of the submitted application via an API Call. This option should also be used if Option 1 fails.

To track the status of their applications, see the API Reference: here

What you get back: The current status of the merchant's account creation. Continue polling until the status reflects that the Merchant Dashboard account has been created.

💡

Tip: Use a reasonable polling interval (e.g., every 30–60 seconds) and set a timeout threshold for your implementation. Webhook notifications in Step 5 are the most reliable signal that the merchant is ready — polling is best used as a fallback or for real-time UI updates.

Handling a Failed Lead Submission

If the application submission fails — due to missing fields, validation errors, or data issues — Payarc returns an error response. Instead of starting over, update the existing Lead record with the correct data, and resubmit.

Step 1: Update the Lead Record

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

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

Step 2: Resubmit the Application

Once the Lead is updated, resubmit using the same endpoint from Step 2.

The application re-enters processing. Repeat this step as needed until you receive a successful boarding response.

💡

Tip: The error response from a failed submission will indicate which fields need correction. Address all flagged fields in a single update call before resubmitting to minimize the number of cycles.

What's Next

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

Updated about 2 hours ago