> For the complete documentation index, see [llms.txt](https://docs.xplorpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/onboard-merchant/pricing-plan-and-reference/pricing-plans.md).

# Pricing Plans

Use the Pricing Plan API endpoints to configure and apply merchant pricing during onboarding.

### Pricing plan steps

The steps below help you configure pricing plan:

{% stepper %}
{% step %}

#### Retrieve available pricing templates

{% endstep %}

{% step %}

#### Select a pricing template

{% endstep %}

{% step %}

#### Customize fees and settings (if required)

{% endstep %}

{% step %}

#### Submit the pricing plan in the onboarding request

{% endstep %}
{% endstepper %}

### Default pricing

Merchant Onboarding supports a default pricing configuration that simplifies merchant setup and reduces integration effort. Default pricing automatically applies a predefined pricing plan associated with your partner hierarchy.

This option simplifies merchant onboarding by eliminating the need to create or customize pricing plans during application submission. Pricing structure is preconfigured Merchants automatically inherit the pricing configuration assigned to your hierarchy.

Use default pricing when merchant-specific pricing customization is not required.

To onboard a merchant using default pricing:

1. Include the required merchant details in the onboarding request:
   1. Doing Business As (DBA) Name
   2. E-mail Address
   3. Merchant Category Code (MCC)
2. Submit the onboarding request using the [Hosted Merchant Onboarding Setup](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/hosted-merchant-onboarding) API. This request initializes the onboarding application using the default pricing plan associated with your hierarchy.
3. The system automatically applies the default pricing template associated with your hierarchy.

### Custom pricing

Custom pricing allows you to configure merchant-specific rates and fees using predefined pricing templates. A pricing template defines the supported fee types, fee settings, required pricing fields, and allowed minimum and maximum values.

You can implement custom pricing by:

* Modifying fee values in an existing pricing template, or
* ​Creating a completely customized pricing plan based on retrieved templates.

All merchant and pricing information must be submitted in a single onboarding API request.

Use pricing templates to configure merchant-specific pricing while maintaining supported fee validation and allowed pricing ranges.

These templates are configured under your portfolio and contain default fee structures that can be modified to match the needs of different business models. This approach supports advanced pricing options while ensuring compliance with allowed fee ranges.

The Hosted Merchant Onboarding Setup API supports submitting merchant onboarding details and pricing configuration in a single request.

The onboarding request must include:

* ​All standard fields (DBA name, email, MCC)
* `pricingPlanTemplateID`
* Pricing fee configuration from the selected template

{% stepper %}
{% step %}

#### **Retrieve pricing templates**

Use the [Available Pricing Plan Template](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/onboard-merchant/pricing-plan-and-reference/pricingplanv2#get-api-pricing-v2-pricingplan-merchantnumber-templates) endpoint to retrieve available pricing templates assigned to your hierarchy.

The response includes template details, supported fees, editable fields, and allowed minimum and maximum values.

Use this information to select an appropriate pricing template for the merchant.
{% endstep %}

{% step %}

#### Select and customize template

Review the fee structure and select an appropriate template to assign to the merchant. Use the template as-is with default values, or modify the editable fields (for example, rates or fixed fees) within the permitted limits. Make sure all required values are populated and remain within the allowed ranges.
{% endstep %}

{% step %}

#### **Configure pricing plan**

Select an appropriate pricing and configure merchant pricing. Depending on the template configuration, you can use the default template values or modify editable fee and rate fields within allowed limits.

Ensure all required pricing fields are included before submitting the onboarding request.
{% endstep %}

{% step %}

#### **Submit merchant application**

Submit the [onboarding request](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/hosted-merchant-onboarding/merchant#post-api-launchintegratorsetup-v1.0-integratemerchant-hierarchynodekey) with the configured pricing plan along with the merchant’s details in a single request.

Include the selected `pricingPlanTemplateID` and pricing fee configuration, and merchant onboarding details in onboarding request. The `hierarchyNodeKey` path parameter identifies the hierarchy under which the merchant is onboarded.

{% hint style="warning" %}
If no pricing template is submitted in the onboarding request, the system automatically applies the default pricing template assigned to your hierarchy.
{% endhint %}
{% endstep %}
{% endstepper %}

### Empower pricing

Empower Pricing allows you to offset credit card payment processing fees by legally passing a portion of those fees to customers. Empower supports multiple compliant billing models depending on the merchant’s business type, location, and accepted card types.

Supported models include:

* **Cash discount with dual pricing** - A discount is offered to customers who pay via cash, check, or store-branded gift cards.
* ​**Surcharging** - An additional fee is applied to credit card transactions to recover processing costs.
* ​**Convenience fees** - Fees charged for payments made through alternative channels, like online or phone.
* ​**Service fees** - Applied to specific industries (such as government or education) based on Merchant Category Code (MCC).

Choose Empower Pricing if your merchant wants to recover payment processing costs in a legally supported way. Empower is ideal for merchants in states and industries where compliant fee recovery programs are allowed.

Empower Pricing onboarding is handled via the Hosted Merchant Onboarding Setup API. The process includes two validation checkpoints to ensure compliance with eligibility rules.

#### **Assign empower template**

Assign an Empower Pricing Template to start onboarding process. This template must have the IsEmpower attribute set to true. The template can be associated with a specific Hierarchy Node Key (HNK), but this is optional.

Empower templates are configured by the Xplor Pay team and include all required eligibility criteria.

#### **Required fields for eligibility**

When using an Empower pricing template, include the following fields in the [merchant onboarding](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/hosted-merchant-onboarding/merchant#post-api-launchintegratorsetup-v1.0-integratemerchant-hierarchynodekey) request:

* `salesProfile.mccCode`
* `physicalAddress.stateCode`
* `salesProfile.cardBrands`
* `salesProfile.isECommerce`
* `physicalAddress.countryCode`

These fields are used to validate merchant eligibility for the selected Empower pricing template during onboarding.

{% hint style="info" %}
The selected pricing template must be configured as an Empower-enabled template.
{% endhint %}

#### **E-commerce classification**

Set `salesProfile.isECommerce` to indicate whether the merchant processes e-commerce or in-person transactions.

If a merchant processes both E-Commerce and in-person transactions, they must be onboarded as two separate MIDs (Merchant IDs), each with the appropriate classification.

This classification is required for eligibility validation during onboarding.

#### **Validation**

After the initial API call to the [Hosted Merchant Onboarding Setup](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/hosted-merchant-onboarding/merchant#post-api-launchintegratorsetup-v1.0-integratemerchant-hierarchynodekey) endpoint, the system checks if the selected or default template is Empower. If **not Empower**, the system proceeds with the default pricing template associated with the HNK.

And if is **Empower**, the system calls the [Check Merchant Eligibility](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/onboard-merchant/pricing-plan-and-reference/pricingplanv2#get-api-pricing-v2-pricingplan-merchantnumber-templates-pricingplantemplateid-eligibility) endpoint to validate eligibility.

* If validation **fail**, the onboarding is blocked, and the API returns an error.
* ​If validation **pass**, the system returns a hosted onboarding application URL.

#### **Hosted application launch**

Use the application URL from the [Hosted Merchant Onboarding API](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/hosted-merchant-onboarding/merchant#post-api-launchintegratorsetup-v1.0-integratemerchant-hierarchynodekey) response to redirect the merchant to the hosted onboarding page or Xplor Pay send a welcome email to the merchant with the URL.

The application form may lock or pre-fill certain eligibility-related fields (such as MCC, State, etc.) to prevent editing and preserving data integrity.

#### **Final submission**

Once the merchant completes all required fields in the application, it will proceed to a Review and Sign page where the system performs a second validation of the Empower eligibility fields.

This step ensures that no critical fields (such as `MCC`, `State`, `Card Types`, or `E-Commerce` status) are altered during onboarding, which can make the merchant ineligible for the Empower pricing template.

If the merchant edits the locked fields or eligibility is violated, the following error message appears on the UI, and the application cannot proceed until corrected.

"*We’re unable to submit your application at this time. Your data has been saved. Please contact your software provider for assistance.*"

#### **Submit application**

Once all eligibility fields pass the final validation, the merchant can proceed to submit the application. Upon submission, the merchant proceeds to the e-signature process, where they can review and sign the merchant agreement.

The user is then redirected either to Xplor Pay or to a return URL configured by the partner.

The application status is updated and returned via API. If your integration supports webhooks, status updates will also be sent automatically to the configured [webhook](https://docs.xplorpay.com/api-reference/webhooks) URL.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xplorpay.com/api-reference/api/merchant-onboarding/onboard-merchant/pricing-plan-and-reference/pricing-plans.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.