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

# Payment Management

> Configure merchant accounts, card readers, tips, gift card code rules, tax rates, and accepted payment methods.

<Info>
  **Prerequisite:** The Payments module must be enabled for your organization before you can access this page. Contact Decoda support if Payment Management is not visible in your settings.
</Info>

Use Payment Management to set up how your clinic accepts money: bank accounts, tips, gift card code rules, accepted payment methods, card readers, tip displays, taxes, and payment mediums.

Go to **Settings** → **Payment Management** to access all sections on one page.

## Merchant Accounts

Merchant accounts are the bank accounts where Decoda deposits funds collected from patients. Each account displays its processing fees for online and in-person transactions, and can be assigned to specific locations.

<Info>
  New merchant accounts are provisioned by Decoda support — to add one, contact support directly from the page. You can edit and archive existing accounts yourself.
</Info>

### View Merchant Accounts

Each merchant account card shows:

* **Name** and unique ID.
* **Default** badge if it is the fallback account for locations without a specific assignment.
* **Online Payments** processing fee (percentage) and per-transaction fee (cents).
* **In-Person Payments** processing fee (percentage) and per-transaction fee (cents).
* **Locations** associated with this account.

### Edit a Merchant Account

<Steps>
  <Step title="Open the Editor">
    Click on a merchant account card, or click the **Edit** icon on the card.
  </Step>

  <Step title="Update Fields">
    * **Name:** Change the display name for this account.
    * **Set as default:** Turn this on to make this the default merchant account. The default account is used whenever no specific account is assigned to a location.
    * **Associated Locations:** Check the locations that should route payments through this account. If no locations are selected, the account is only used as the default.
  </Step>

  <Step title="Save">
    Click **Update Merchant Account**.
  </Step>
</Steps>

### Archive a Merchant Account

If you no longer use a merchant account, you can archive it. Archived accounts are unlinked from all locations and stop appearing in the list.

<Steps>
  <Step title="Open the Card">
    Find the merchant account you want to archive. The trash icon only appears on non-default accounts — to archive the default account, first set a different account as the default.
  </Step>

  <Step title="Click Archive">
    Click the **trash** icon on the card. An **Archive Merchant Account** confirmation appears.
  </Step>

  <Step title="Confirm">
    Review the warning (this unlinks all associated locations) and click **Archive**.
  </Step>
</Steps>

## POS Devices

POS (point-of-sale) devices allow your clinic to accept in-person card payments through physical terminals. Devices must be registered in Decoda before they can process transactions.

<Info>
  Need to set up a new terminal? See the [POS Device Setup](/modules/settings/pos-devices/overview) guides for hardware installation, network configuration, and obtaining your registration code.
</Info>

### Register a New Device

<Steps>
  <Step title="Open Registration">
    Click **Register New Device** in the POS Devices section.
  </Step>

  <Step title="Enter Device Details">
    * **Device ID:** The 6-digit alphanumeric code displayed on your physical POS device.
    * **Device Name:** A descriptive label (max 20 characters), such as "Front Desk Terminal" or "Checkout 1".
    * **Location:** Select the physical clinic where this device is located. If your organization has only one location, this is selected automatically.
    * **Merchant Account:** Choose which merchant account transactions from this device should be routed to. If only one merchant account exists, or a default is configured, it is selected automatically.
  </Step>

  <Step title="Register">
    Click **Register Device**. The device appears in the POS Devices grid and is ready to accept payments.
  </Step>
</Steps>

### Manage Devices

* **Change Location:** Use the **Location** menu on a device card to reassign it to a different clinic.
* **Unregister:** Click the settings menu on a device card and select **Unregister Device**. Confirm when prompted. This permanently removes the device from your organization.

## Tips

The **Tips** card has a single **Collect tips** switch. When it's on (the default), staff can add a tip during checkout and request a tip on a customer-facing [tip display](/modules/billing/tip-screen). Turn it off to remove tipping entirely — the tip option disappears from checkout and the **Request Tip** action is hidden on customer displays.

For how tip percentages are calculated (before or after discounts, which items count), see [General Preferences > Tips](/modules/settings/general#tips).

## Gift Card Codes

The **Gift card codes** card controls whether staff can leave gift card codes blank when selling or issuing cards.

* When **Require custom codes for staff-issued gift cards** is off, staff may enter a custom **Gift card code** or leave it blank so Decoda generates one.
* When **Require custom codes for staff-issued gift cards** is on, staff must enter a code for every gift card sold in checkout or issued from **Settings** → **Gift Cards** before payment can be taken.
* Online shop purchases still generate codes automatically.

See [Gift Cards](/modules/settings/gift-cards#choose-how-gift-card-codes-work) for the full workflow.

## Payment Methods

The **Payment methods** card controls which payment options are available across every payment surface — staff checkout, payment plans, memberships, pay links, booking-fee checkout, embeds, and intake forms.

* **ACH (bank transfer)** — Show ACH everywhere. When off, the bank-transfer option disappears for staff and patients alike. Saved bank accounts can still be charged; they just do not appear as a choice.
* **Apple Pay** — Show Apple Pay on patient pay links, booking-fee checkout, and embedded payment screens. Card payments remain available. Save-card flows always exclude Apple Pay because Apple Pay tokens can't be stored for later use.

## Tip Displays

Tip displays are customer-facing screens that present tip options during checkout. Each display is tied to a specific location.

When a patient checks out, the tip screen appears on a separate display facing the patient. They see suggested tip percentages and can choose one or enter a custom amount — your staff doesn't have to ask.

### Add a Tip Display

<Steps>
  <Step title="Open the Form">
    Click **Add Tip Display** in the Tip Displays section.
  </Step>

  <Step title="Configure the Display">
    * **Display Name:** A descriptive label (e.g., "Front Desk", "Checkout 1").
    * **Location:** Select the clinic where this display is used.
  </Step>

  <Step title="Save">
    Click **Add Display**.
  </Step>
</Steps>

### Edit or Delete a Tip Display

* **Edit:** Click the settings menu on a display card, then select **Edit**. You can update the name and turn the **Active** switch on or off.
* **Delete:** Click the settings menu, then select **Delete**. Confirm when prompted. This permanently removes the display.

## Tax Rates

Tax rates define the tax percentages applied to items during checkout. Each tax can be scoped to specific item types, categories, and locations.

### Create a Tax Rate

<Steps>
  <Step title="Open the Form">
    Click **Add Tax Rate** in the Tax Rates section.
  </Step>

  <Step title="Enter Tax Details">
    * **Tax Name:** A descriptive label (e.g., "Sales Tax", "City Tax", "VAT").
    * **Tax Percentage:** The rate as a number between 0 and 100 (e.g., 8.25 for 8.25%).
    * **Location Scope:** Select which locations this tax applies to. Leave empty to apply to all locations.
    * **Apply to:** Choose which items this tax covers:
      * **All items** -- applies to products, services, memberships, packages, and medications.
      * **Products only** -- only physical products.
      * **Services only** -- only services.
      * **Memberships only** -- only memberships.
      * **Packages only** -- only packages.
      * **Medications only** -- only medications.
      * **Specific categories** -- only items in the categories you select. When chosen, a category picker appears.
  </Step>

  <Step title="Save">
    Click **Create Tax Rate**.
  </Step>
</Steps>

### Edit a Tax Rate

Click the settings menu on a tax row and select **Edit Tax Rate**. The same form opens pre-filled with the current values. Update the fields and click **Update Tax Rate**.

### Edit Item Exemptions

To exempt specific items from a tax, click the settings menu on a tax row and select **Edit Item Exemptions**. Check or uncheck individual services, products, packages, and medications to override the tax scope for those items.

### Delete a Tax Rate

Click the settings menu on a tax row and select **Delete**. Confirm when prompted.

## Payment Mediums

Payment mediums are the different ways your clinic accepts payment — credit card, cash, check, Venmo, etc. Decoda provides built-in methods and lets you add custom ones.

### Add a Custom Settlement Type

<Steps>
  <Step title="Open the Form">
    Click **Add Custom Settlement Type** in the Payment Mediums section.
  </Step>

  <Step title="Enter a Name">
    Type a descriptive name for the payment method (e.g., "Venmo", "Zelle", "HSA Card", "Cherry Financing").
  </Step>

  <Step title="Create">
    Click **Create**. The new settlement type appears in the custom mediums table and is immediately available during checkout.
  </Step>
</Steps>

### Edit a Custom Settlement Type

Click the settings menu on the row and select **Edit**. Update the name and click **Update**.

<Info>
  If you rename a custom settlement type to match an existing one, a merge confirmation prompt appears. Confirming the merge consolidates all historical transactions under the existing name.
</Info>

### Delete a Custom Settlement Type

Click the settings menu on the row and select **Delete**. Confirm when prompted. System payment mediums cannot be deleted.

## Embedded Payment Components

The embeddable payment and store details forms have moved to **Settings** → **Developers** → [**Embedded Payment Components**](/modules/settings/embed-payments). Use those tools to generate iframe code for collecting payments or saving payment methods on your website.

## Advanced Configuration

<AccordionGroup>
  <Accordion title="Permissions">
    Payment Management is gated by role-based permissions:

    * **View Payment Settings** — Required to view the Payment Management page, including merchant accounts, gift card code rules, payment methods, POS devices, tip displays, tax rates, and payment mediums.
    * **Manage Payment Settings** — Required to edit merchant accounts, gift card code rules, payment methods, register/unregister POS devices, add/edit/delete tip displays, create/edit/delete tax rates, and manage payment mediums.

    Admin users have full access to all payment management settings by default.
  </Accordion>
</AccordionGroup>