# Merchant Configuration

The Merchant Configuration page lets you set account-wide defaults that apply to all payments. Individual payment requests can override these defaults, but the values you configure here are used when no override is provided.

To open this page, go to **Settings > General** in the ODUS Dashboard.

You can also read and update the same settings via the API — see [`GET /v2/merchant-config`](https://docs.odus.com/docs/api/core/v2/merchant-config-controller-get) and [`POST /v2/merchant-config`](https://docs.odus.com/docs/api/core/v2/merchant-config-controller-set). Your account has exactly one configuration, so neither route takes an ID. An update changes only the fields you send.

## Dashboard settings

These settings control how data is displayed in the ODUS Dashboard. They do not affect payment processing.

### Display currency

The currency used when showing aggregate amounts in reports and statistics. Select any supported currency from the dropdown. This setting does not convert or affect the currencies charged to your customers.

### Timezone

The timezone used for all reporting, scheduling, and subscription billing windows. Timezones are listed in IANA format (for example, `Europe/Paris` or `America/New_York`). If not set, ODUS defaults to UTC.

important

Changing the timezone affects when subscription renewals are grouped and when delayed captures trigger. Review your active subscriptions before changing this setting.

### Subscription grouping window

In minutes. How far apart two of a customer's subscriptions may be created and still be shown together in the **Related subscriptions** section of a subscription's detail page. Enter a whole number between `0` and `1440` (24 hours).

Subscriptions that share a **setup payment** — everything bought in one checkout, free items included — are always grouped, whatever this is set to. The window is what additionally catches an upsell, which is a second checkout and therefore a second payment.

| Value      | Behaviour                                                                                            |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| `0`        | The time window is off. Only subscriptions sharing a setup payment are grouped. This is the default. |
| `1`–`1440` | Subscriptions created within this many minutes of each other are grouped as well.                    |

Grouping is worked out when the page is opened, so changing this value re-groups your existing subscriptions immediately. It is a read-only view — nothing is ever cancelled automatically.

See [Related Subscriptions](https://docs.odus.com/docs/guides/subscriptions/related-subscriptions.md) for how to read the section and open a free add-on from it.

## Default payment settings

These settings define the default capture behaviour for all payment methods. You can override them per payment method type using the sections described below.

### Capture method

Controls when funds are captured after a payment is authorized.

| Value              | Behaviour                                                                            |
| ------------------ | ------------------------------------------------------------------------------------ |
| `automatic`        | Funds are captured immediately at authorization.                                     |
| `manual`           | Funds are not captured automatically. You must call the capture endpoint explicitly. |
| `automaticDelayed` | Funds are captured automatically after the number of days set in **Capture delay**.  |

### Capture delay

Visible only when **Capture method** is set to `automaticDelayed`. Enter the number of days after authorization before the automatic capture triggers. The valid range is **1–5 days**.

### Recurring capture method

The capture method applied to subscription renewal charges. By default it inherits the value from **Capture method**. You can override it independently if recurring charges require different behaviour.

### Recurring capture delay

Visible only when **Recurring capture method** is `automaticDelayed`. The delay in days before recurring charges are auto-captured. The valid range is **1–5 days**.

### Capture at night

When enabled, a delayed capture is scheduled at a random moment between 02:00 and 04:00 in the shopper's local time instead of at the exact moment the capture delay elapses. Captures are only ever moved later, never earlier, so the configured **Capture delay** is always respected.

Two conditions apply:

* Only **delayed** captures are affected. Immediate and manual captures are unchanged.
* The shopper's UTC offset must be known. It is read from the shopper's browser at authorization, which happens automatically for payments made through the Checkout SDK, and remembered for that shopper afterwards. Authorizations that carry no browser information of their own — server-to-server charges, subscription renewals, and retries — reuse the offset last recorded for the same shopper, so they are scheduled at night as well. Payments for a shopper whose offset has never been recorded keep the standard schedule.

Offsets are only recorded while **Capture at night** is enabled, so after turning it on a returning shopper's payments keep the standard schedule until their next authorization from a browser.

note

Shopper location is known only as the UTC offset reported at authorization, not as a full time zone. If a daylight-saving transition falls between authorization and capture, the effective window can shift by an hour.

See [Captures](https://docs.odus.com/docs/guides/payments/capture.md#capturing-at-night) for how this fits into the delayed capture flow.

### Recurring payment bundling

When enabled, same-day subscription renewal charges for the same customer are grouped into a single payment instead of separate charges. This reduces transaction fees and simplifies billing statements.

See [Payment Bundling](https://docs.odus.com/docs/guides/subscriptions/payment-bundling.md) for bundling criteria, failure behaviour, and examples.

### Blacklist customer on chargeback

When enabled, every chargeback you record adds the customer's email address to the blacklist, whether it is recorded from the Dashboard or through the API, so a charged-back customer is blocked without anyone having to remember to do it.

Blacklisting also cancels every active subscription of every customer with that email immediately. See [The Blacklist](https://docs.odus.com/docs/guides/customers/customer-restrictions.md#the-blacklist).

This setting is on by default. In the API it is the `blacklistCustomerOnChargeback` field. Turn it off if you would rather decide for each chargeback. Turning it off does not remove anyone already blacklisted; remove an entry from the [**Blacklist** page](https://docs.odus.com/docs/guides/customers/customer-restrictions.md#the-blacklist).

See [Chargebacks](https://docs.odus.com/docs/guides/payments/chargebacks.md#blacklist-the-customer) for how this interacts with a chargeback request.

### Line item description

The text that describes each purchased item to the shopper. It is sent to the payment provider as the item name — so it appears on PayPal order sheets and wallet screens — and it is also used for the payment note and the item summary in the Dashboard.

| Value          | Behaviour                                                       |
| -------------- | --------------------------------------------------------------- |
| `Price name`   | The name of the price the item references. This is the default. |
| `Product name` | The name of the product the price belongs to.                   |

Pick **Product name** when your product names are the ones shoppers recognise and your price names are internal labels such as `Monthly USD Tier 2`. Names longer than 127 characters are shortened to fit.

A `description` sent with a line item on [`POST /v2/payments`](https://docs.odus.com/docs/api/core/v2/payment-controller-create) always wins over this setting, so you can label individual items without changing your account default.

note

The description is stored on the line item when the payment is created, so changing this setting only affects payments made from then on. Existing payments — and subscription renewals, which reuse the cart of the payment that created them — keep the description they were created with.

## Card payment settings

Tick **Set Card payment settings** to expand card-specific overrides.

### Processing mode

| Value     | Behaviour                                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `cascade` | ODUS routes the payment through the selected cascade rule.                                                               |
| `direct`  | ODUS sends the payment directly to the selected gateway profile.                                                         |
| `route`   | The selected [route](https://docs.odus.com/docs/guides/routing/how-routes-work.md) chooses the gateway for each payment. |

### Default cascade

Visible when mode is `cascade`. Select the cascade rule to apply to card payments by default.

### Default gateway profile

Visible when mode is `direct`. Select the gateway profile to use for card payments by default.

### Default route

Visible when mode is `route`. Select the route to apply to card payments by default. The list offers only routes that are active and have an active version, because a route without both cannot be saved as your default. To create and publish a route, see [Routing card payments with a route](https://docs.odus.com/docs/guides/routing/routing-card-payments.md).

### Card capture method and delay

Per-payment-method override for the capture settings described in [Default payment settings](#default-payment-settings). If set to **Use default**, the root default applies. Capture delay for cards is **1–5 days**.

### Card recurring capture method and delay

Same as above but for subscription renewal charges on cards.

## PayPal payment settings

Tick **Set PayPal payment settings** to expand PayPal-specific overrides.

PayPal always uses `direct` mode. You must select a gateway profile that supports PayPal.

### PayPal gateway

The gateway profile used for all PayPal payments. Only profiles that support PayPal are shown.

### PayPal capture method and delay

Same options as the default capture settings. Capture delay for PayPal is **1–15 days**.

### PayPal recurring capture method and delay

Capture settings applied to PayPal subscription renewal charges.

## Apple Pay payment settings

Tick **Set Apple Pay payment settings** to expand Apple Pay-specific overrides.

Apple Pay always uses `direct` mode. You must select a gateway profile that supports Apple Pay.

### Apple Pay gateway

The gateway profile used for all Apple Pay payments. Only profiles that support Apple Pay are shown.

### Apple Pay capture method and delay

Same options as the default capture settings. Capture delay for Apple Pay is **1–5 days**.

### Apple Pay recurring capture method and delay

Capture settings applied to Apple Pay subscription renewal charges.

## Saving changes

Click **Update** to save all changes. The button is disabled until all required fields are valid.