> ## Documentation Index
> Fetch the complete documentation index at: https://funnelfox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# FunnelFox Billing settings
> Reference for everything on the Settings > Main page of the FunnelFox Billing dashboard.
The **Settings** page of your FunnelFox Billing dashboard holds the
configuration for your organization. The **Main** tab covers payment
provider credentials, checkout behavior, retries, taxes, and more.
Change one or more values, then click **Save** to apply your changes, or **Reset Draft** to discard them.
## Payment provider credentials
These blocks connect FunnelFox Billing to your PSP accounts. Set them up with your Solutions manager.
Some providers support several accounts. When more than one account is
configured, each uses the same fields under a separate slot (`default`,
`ff_first`, `ff_second`, `ff_third`). The keys below show the `default` slot.
### Adyen
| Setting | Description | Value |
| ------------------------------------------------- | -------------------------------------------------------------------------------------- | ------ |
| `adyen_collection.default.shop_id` | Balance Platform store ID. Its presence also switches on the navbar Dashboard link. | Text |
| `adyen_collection.default.store_reference` | Paired with the shop ID for the Adyen cache. | Text |
| `adyen_collection.default.account_holder_id` | Balance Platform account-holder ID; mints tokens for the embedded Adyen dashboard. | Text |
| `adyen_collection.default.api_key` | Server-side Adyen API key. | Secret |
| `adyen_collection.default.client_key` | Public client key for the browser payment components. | Text |
| `adyen_collection.default.merchant_account` | Adyen merchant account name sent on every payment. | Text |
| `adyen_collection.default.store` | Sub-merchant store ID for marketplaces, added to payloads when set. | Text |
| `adyen_collection.default.live_url_prefix` | Live endpoint host prefix. Set only in live mode; its presence also signals live mode. | Text |
| `adyen_collection.default.google_pay_merchant_id` | Public Google Pay merchant ID surfaced to the client SDK. | Text |
### Stripe
| Setting | Description | Value |
| --------------------------------------- | --------------------------------------------------------------------------------------- | ------ |
| `stripe_collection.default.account_id` | Stored Stripe account ID, kept as a reference label. | Text |
| `stripe_collection.default.public_key` | Publishable key for the browser Payment Element. A `pk_live_` prefix signals live mode. | Text |
| `stripe_collection.default.private_key` | Secret API key for the server-side Stripe client. | Secret |
| `stripe_collection.default.project_id` | Stored project ID reference. | Text |
### Primer
Primer needs all three of the domain, the private key, and the webhook signing
secret set together to work. The webhook signing secret lives on the
[Webhooks tab](/docs/billing/settings-webhooks#psp-verification-secrets).
| Setting | Description | Value |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `primer_collection.default.domain` | Primer API host. It encodes the environment (`https://api.sandbox.primer.io` for sandbox, `https://api.primer.io` for production). The production host signals live mode. | Text |
| `primer_collection.default.private_key` | Primer API secret, sent as the `X-Api-Key` header. | Secret |
### Airwallex
| Setting | Description | Value |
| ------------------------ | ---------------------------------------------------------- | -------------------- |
| `airwallex_risk_enabled` | Loads Airwallex device fingerprinting in the checkout SDK. | Yes/No (default: No) |
## API keys
API keys let external callers authenticate to the
[FunnelFox Billing API](/docs/develop/api-billing). Two key slots are available
(`first` and `second`), each with the same fields.
| Setting | Description | Value |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------- | ------ |
| `ff_api_secrets_new.first.key` | The API secret token. Callers send it in the `ff-secret-key` header. | Secret |
| `ff_api_secrets_new.first.enabled` | Turns the key on or off. | Yes/No |
| `ff_api_secrets_new.first.group` | Access group granted to callers: `super_admin`, `admin`, `support`, or `viewer` (cumulative). Required. | Text |
| `ff_api_secrets_new.second.key` | Second key slot token. | Secret |
| `ff_api_secrets_new.second.enabled` | Second key on or off. | Yes/No |
| `ff_api_secrets_new.second.group` | Second key access group. | Text |
## Checkout page fields
Control which fields appear on the checkout page. Country rules can still
override the final visibility of some fields. Learn more about
[payment metadata](/docs/billing/payments-management#metadata) and
[collecting email from Apple Pay](/docs/billing/payments-management#email).
| Setting | Description | Value |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------- |
| `show_email_field` | Show an email input at checkout. Email is not required even when the field is shown. | Yes/No (default: No) |
| `show_cardholder_name_field` | Show the cardholder-name input. Country rules can override the final visibility. | Yes/No (default: No) |
| `show_postal_code_field` | Show the postal or ZIP input, which feeds the tax jurisdiction. | Yes/No (default: No) |
| `show_country_selector_field` | Show a billing-country dropdown and switch on the built-in US, GB, and AU per-country field rules. | Yes/No (default: No) |
| `country_field_rule_overrides` | Per-country overrides for postal-code and cardholder-name visibility. | JSON (default: `{}`) |
| `collect_apple_pay_email` | Ask for an email in the Apple Pay sheet and make it the customer's primary email. | Yes/No (default: No) |
| `include_email_into_primer_request` | Attach a known email to Primer payment and renewal requests. Turn off only when emails are unavailable. | Yes/No (default: Yes) |
## Apple Pay
Configure how the Apple Pay sheet appears and behaves. `apple_pay_merchant_name`
and `apple_pay_ordered_card_networks` apply to Primer only.
| Setting | Description | Value |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `apple_pay_merchant_name` | Name shown in the Apple Pay sheet header. Empty uses the Apple or Primer default. | Text |
| `apple_pay_mpan_enabled` | Show the recurring-billing disclosure in the Apple Pay sheet for subscriptions. Needs the management URL below and a recurring Price Point. | Yes/No (default: No) |
| `apple_pay_recurring_payment_management_url` | The "Manage subscription" link shown in the recurring disclosure. If blank, the disclosure is silently disabled even when MPAN is on. | Text |
| `apple_pay_billing_agreement` | Consent text shown in the Apple Pay sheet. | Text (default: "You agree to authorize recurring payments. You can cancel anytime.") |
| `apple_pay_ordered_card_networks` | Restrict or order the card networks Apple Pay offers. Allowed values (case-sensitive): `AMEX`, `CARTES_BANCAIRES`, `DINERS_CLUB`, `DISCOVER`, `EFTPOS`, `ELO`, `JCB`, `MAESTRO`, `MASTERCARD`, `MIR`, `UNIONPAY`, `VISA`. | JSON list (default: `[]`) |
## Double-purchase prevention
| Setting | Description | Value |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| `double_purchase_prevention` | Block a repeat purchase of a lifetime or one-off product the customer already owns. | Yes/No (default: Yes) |
| `double_purchase_prevention_for_subscription` | Block a repeat purchase of a subscription whose features the customer already holds. | Yes/No (default: Yes) |
| `double_purchase_check_by_email` | Widen the check to all accounts sharing the customer's email or aliases. Skipped when more than three accounts share the same email. | Yes/No (default: No) |
## Subscription retries
Control how FunnelFox Billing retries failed subscription charges. Learn more about [Payment retries](/docs/billing/payments-retries).
| Setting | Description | Value |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `retry_logic.schedule_type` | The dunning timetable. | Text (default: `smart`; one of `no_retry`, `smart`, `short`, `long`, `custom_1`–`custom_5`) |
| `retry_logic.grace_enabled` | Keep the customer's access during the retry window. | Yes/No (default: Yes) |
| `retry_logic.partial_charge_enabled` | Allow later retries to charge a reduced fraction of the price. | Yes/No (default: Yes) |
| `retry_logic.final_microcharge_attempt` | Add a final \$1 salvage retry. Applies to the `smart` and `long` schedules only. | Yes/No (default: No) |
| `handbrake_for_test_subs` | Auto-stop fast test subscriptions after this many iterations in non-live mode. | Number (default: 10) |
| `skip_creating_purchase` | Do not create the internal subscription or one-off after payment. Leave off unless instructed otherwise. | Yes/No (default: No) |
## Payment capture
Hold an authorized payment before capturing the funds, giving your team a
fraud-review window. Learn more about [Payment hold](/docs/billing/payments-management#payment-hold).
| Setting | Description | Value |
| --------------------------- | --------------------------------------------------------------- | ------------------- |
| `delayed_capture_hours` | Hours to hold an authorized first (CIT) payment before capture. | Number (default: 1) |
| `delayed_capture_hours_mit` | The same delay for renewal (MIT) payments. | Number (default: 1) |
## Free trial
| Setting | Description | Value |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `free_trial_amount` | The upfront card-verification charge taken and voided at the start of a free trial, always in USD. Set it to `0` to disable the verification charge. | Number (default: 1) |
## Decline classification
FunnelFox Billing sorts payment declines into two types.
A hard decline cancels auto-renew and stops retries. A soft decline
keeps retrying on the dunning schedule.
| Setting | Description | Value |
| ----------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------- |
| `hard_decline_mapping` | Primer only: force the listed declines to be treated as hard. | JSON (default: `[]`) |
| `stripe_hard_decline_mapping` | Stripe decline codes that classify as hard declines. Everything else is treated as soft. | JSON (replaces the built-in defaults) |
| `adyen_hard_decline_mapping` | Adyen refusal reason codes treated as hard declines. | JSON (replaces the built-in defaults) |
For `stripe_hard_decline_mapping` and `adyen_hard_decline_mapping`, the value
you enter fully replaces the built-in defaults rather than adding to them.
## Rate limits
Caps that protect against runaway actions, plus a sandbox-only testing knob.
The refund limit is also referenced from
[Refunds](/docs/billing/payments-management#refunds).
| Setting | Description | Value |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `refund_limit` | Caps operator refund and cancel actions. Exceeding it returns an HTTP 429. | JSON (default: `{"attempt_limit":50,"block_ttl":86400,"window_ttl":3600}`) |
| `charge_limit` | Caps renewal (MIT) charges per saved-card token. | JSON (default: `{"attempt_limit":2,"block_ttl":97200,"window_ttl":75600}`) |
| `first_payment_limit` | Caps first-payment (CIT) checkout attempts per payment-method token. | JSON (default: `{"attempt_limit":10,"block_ttl":600,"window_ttl":300}`) |
| `first_payment_threshold` | Monitoring only. Emits a health metric and does not throttle payments. | JSON (default: `[]`) |
| `artificial_decline` | Sandbox only. The percentage of Primer renewal (MIT) charges returned as synthetic soft declines. No effect in live mode. | Number (default: 0) |
## Tax
Turn tax on and choose how it is calculated. Learn more about
[FunnelFox Billing Taxes](/docs/billing/taxes).
| Setting | Description | Value |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `tax_calculation_provider` | The tax engine. | Text (default: `none`; one of `none`, `stripe`, `static`) |
| `tax_calculation_stripe_region` | Which `stripe_collection` slot Stripe Tax uses when several exist. Blank uses the single account. | Text |
| `taxes_settings_validation_strict` | Block saving changes that hide the country or postal-code field while tax is on. | Yes/No (default: Yes) |
## Statement descriptor
| Setting | Description | Value |
| -------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------ |
| `price_point_default_descriptor` | The organization-wide fallback descriptor shown on the card statement when a Price Point has none. | Text (max 22 characters) |
## Dashboard and organization
General display and integration options.
| Setting | Description | Value |
| ---------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `org_name` | Display name used in the dashboard and reports. Falls back to the organization ID when empty. | Text |
| `dashboard_link_visibility` | Controls the navbar Dashboard link. | Text (default: `adyen_only`; one of `hidden`, `adyen_only`, `always`) |
| `demo_page_sdk_version` | The SDK version the internal demo checkout pages load. | Text (default: `beta`) |
| `sdk_telemetry_enabled` | Turns on checkout SDK telemetry. | Yes/No (default: No) |
| `stripe_link_enabled` | Turns on Stripe Link one-click checkout in the Payment Element. | Yes/No (default: No) |
| `admin_count_of_shown_events_body` | How many event bodies the events panel renders. | Number (default: 10; range 1–50) |
## Next steps
* [Configure webhook settings](/docs/billing/settings-webhooks)
* [Create offerings](/docs/billing/settings-offerings)
* [Manage price points](/docs/billing/settings-price-points)
* [Set up FunnelFox Billing Taxes](/docs/billing/taxes)