FunnelFox Billing settings

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 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.

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. 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 and collecting email from Apple Pay.

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.

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)

Delayed capture

Hold an authorized payment for a set time before capturing the funds. A cancellation before capture costs nothing, while a refund after capture is a real money movement. Learn more about Delayed payment capture.

Setting	Description	Value
`delayed_capture`	Capture delay in hours per card network, transaction type, and PSP, plus a `cit`/`mit` fallback used when the order’s network and PSP pair has no entry. A `null` fallback captures immediately.	JSON (default: 12 hours everywhere)

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.

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.

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

The statement descriptor is the text your customer sees next to the charge on their card statement. This setting is the organization-wide fallback, used by every Price Point that has no descriptor of its own. FunnelFox Billing reads it at charge time, so a change applies immediately to new purchases on those Price Points and to renewals of existing subscriptions. Learn more about the billing 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)

Custom charges

Configure charges made for an amount set in the API call. Learn more about custom charges.

Setting	Description	Value
`one_off_charge_descriptor`	The descriptor shown on the card statement for custom charges. Blank falls back to `price_point_default_descriptor`.	Text
`one_off_charge_description`	The product description used in dispute responses. Blank falls back to “One-time in-app purchase”.	Text (max 250 characters)
`one_off_charge_max_amount`	The largest amount a single custom charge can request. The number is compared to the amount whatever the currency. Blank sets no limit.	Number (blank by default)

FunnelFox enables custom charges for your organization, so one_off_charge_enabled is not yours to set. Changing the descriptor or description applies to new charges only, and completed charges keep the values they were made with.

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)

Getting started

Payments

Subscription management

Settings

FunnelFox Billing settings

Payment provider credentials

Adyen

Stripe

Primer

Airwallex

API keys

Checkout page fields

Apple Pay

Double-purchase prevention

Subscription retries

Delayed capture

Free trial

Decline classification

Rate limits

Tax

Statement descriptor

Custom charges

Dashboard and organization

Next steps

​Payment provider credentials

​Adyen

​Stripe

​Primer

​Airwallex

​API keys

​Checkout page fields

​Apple Pay

​Double-purchase prevention

​Subscription retries

​Delayed capture

​Free trial

​Decline classification

​Rate limits

​Tax

​Statement descriptor

​Custom charges

​Dashboard and organization

​Next steps

Payment provider credentials

Adyen

Stripe

Primer

Airwallex

API keys

Checkout page fields

Apple Pay

Double-purchase prevention

Subscription retries

Delayed capture

Free trial

Decline classification

Rate limits

Tax

Statement descriptor

Custom charges

Dashboard and organization

Next steps