> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fusioncore.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting Up Custom Payment Types

> Create a custom Payment Type for a payment method that fusionCore does not offer out of the box.

A **Payment Type** is a configuration record that tells fusionCore *how* money can move for a given **Business Unit** (a branded operating division of your organization). It names a payment method, points the pay screen at the right component, and controls who can use it and how refunds behave.

Custom Payment Types cover payment methods that fall outside the ones fusionCore ships out of the box (Card, ACH, Cash, Check, Account Credit, Alipay, WeChat Pay). Use this page when you need a payment method that is not already in the **Payment Method** picklist, or a Payment Type that renders with your own front-end component.

<Info>
  A **Lightning Web Component (LWC)** is a Salesforce front-end component — the small piece of UI that renders on the pay or refund screen. A custom Payment Type usually points at either a fusionCore-supplied component or one you build.
</Info>

## Prerequisites

* You can create and edit `Payment_Type__c` records. This requires the `FC_Commerce_Manage_Config_Data` permission set. It gives full create, read, update, and delete access on Payment Types.
* The **Business Unit** you are configuring already exists.
* The **GL Account** (`GL_Account__c`) you will use as the deposit account already exists for that same Business Unit.

## Plan the Custom Payment Type

Before you create anything, decide:

* What the custom payment method is and how staff or members will use it.
* How it interacts with existing objects such as Accounts, Orders, or your own custom objects.
* Which fields and data points you need to capture, and therefore which front-end component renders at pay and refund time.

## Add the New Payment Method Picklist Value

Skip this step if you are reusing a payment method that already exists in the **Payment Method** picklist.

The **Payment Method** picklist is shared (a global value set), so you add new values once in Setup.

<Steps>
  <Step title="Open the Payment Method value set">
    From **Setup**, go to **Picklist Value Sets**, then open **Payment Method**.
  </Step>

  <Step title="Add the value">
    Scroll to **Values** and click **New**. Enter the new value — for example, `Society of Innovators Credit Card` — and click **Save**.
  </Step>
</Steps>

<Warning>
  If the new payment method is `ACH`, `Alipay`, `Card`, or `WeChat Pay`, it is treated as a payment-provider method and requires a **Payment Provider Account** (`Payment_Provider_Account__c`) on the Payment Type, or the record will not save. This list is data-driven by the `FCORE_BASE__Constant.FC_Payment_Provider_Methods` Custom Metadata record, so an org may extend it. For a true custom (offline-style) method, choose a value outside that list.
</Warning>

## Create the Custom Payment Type Record

<Steps>
  <Step title="Open the Payment Types tab">
    Click the **App Launcher**, type `Payment Types`, and open it. Then click **New**.
  </Step>

  <Step title="Choose the record type">
    Choose the **Payment** (`FC_Payment`) record type for a checkout option that staff or members select at pay time. Click **Next**.
  </Step>

  <Step title="Fill in the core fields">
    Complete at least the following:

    * **Payment Type Name** — a descriptive label. For example, `Society of Innovators Credit Card` or `SOI ACH`.
    * **Business Unit** (`Business_Unit__c`) — the Business Unit this Payment Type belongs to.
    * **Payment Method** (`Payment_Method__c`) — the medium of payment. Select the value you added above, or an existing one.
    * **Deposit Account** (`Deposit_Account__c`) — the GL Account that receives the funds. This lookup is filtered to GL Accounts of the same Business Unit.
    * **Display Payment Type** (`Display_Payment_Type__c`) — controls where the Payment Type appears. The values are `Portal and Staff`, `Portal`, `Staff`, and `Disabled`. Only `Staff` and `Portal and Staff` Payment Types appear in the staff pay and refund flows.
    * **Refund Behavior** (`Refund_Behavior__c`) — controls how refunds work. The values are `Cannot Refund`, `Refund only if original payment`, and `Valid for All Refunds`.
    * **Staff Order** (`Staff_Order__c`) — the sort position of this Payment Type in the **Payment Method** dropdown when staff pay an order.
  </Step>

  <Step title="Set the front-end components">
    In the **System Information** section, set the components that render at runtime:

    * **Payment Component** (`Payment_Component__c`) — the component shown when paying. This can be a fusionCore-supplied component (for example `FCORE_PAY/orderPaymentCashOrCheck`) or your own custom one.
    * **Refund Component** (`Refund_Component__c`) — the component shown when refunding (for example `FCORE_PAY/orderRefundCash`) or your own custom one.

    <Info>
      These component fields are not on the Payment Type page layout by default. Administrators can view and edit them, by adding to the layout, or with a tool such as Salesforce Inspector Reloaded (pending your IT approval).
    </Info>
  </Step>

  <Step title="Save">
    When every section is complete, click **Save**.
  </Step>
</Steps>

## Limitations and Common Pitfalls

fusionCore enforces these rules in code (not as declarative validation rules), so they will not appear under **Setup > Validation Rules**. A blocked save returns an on-screen error.

* **Provider methods require a Payment Provider Account.** A Payment Type whose **Payment Method** is `ACH`, `Alipay`, `Card`, or `WeChat Pay` will not save unless **Payment Provider Account** is set. For a custom offline-style method, use a payment method outside that provider list.
* **`Valid for All Refunds` cannot be combined with a Payment Provider Account.** Provider-backed refunds are expected to use `Refund only if original payment` instead.
* **Auto-succeed flags are for offline methods only.** The **Auto-Update Payment FE To Succeeded** (`Auto_Update_Payment_FE_To_Succeeded__c`) and **Auto-Update Refund FE To Succeeded** (`Auto_Update_Refund_FE_To_Succeeded__c`) checkboxes cannot be checked when a **Payment Provider Account** is set. They exist so offline methods (such as Cash or Check) can auto-mark their financial event as succeeded; provider-backed events get their real status from the provider.
* **Only one Account Credit Payment Type per Business Unit.** A second `Payment` record with **Payment Method** `Account Credit` for the same Business Unit is blocked.
* **A deposit account cannot be deleted while in use.** You cannot delete a GL Account that any Payment Type references as its **Deposit Account**; reassign the Payment Type first.
* **Currency filtering applies only in multi-currency orgs.** Leave **Supported Currencies** (`Supported_Currencies__c`) blank to support all currencies. In a multi-currency org, a populated list that omits the order's currency silently hides the Payment Type from the pay screen — a frequent "why is my method missing" cause.
* **Component fields are hidden by default.** Because **Payment Component** and **Refund Component** are not on the default layout, a Payment Type created without them will render nothing at pay or refund time. Confirm both are populated.