TALER-MERCHANT.CONF(5)

📦 version 1.3.0, in nixos 26.05, nixpkgs unstable

💖 NAME 💖

taler-merchant.conf — the Taler merchant configuration file. This is the TALER-MERCHANT.CONF(5) manual page from GNU Taler, and okay so this page is long and comes in 2 parts — this is part 1, bestie. 💅

✨ DESCRIPTION ✨

Okay so the config file is line-oriented, bestie. Blank lines? Ignored. Whitespace at the beginning and end of a line? Also ignored, periodt. 💅

Comments start with # or % in the first column (after any beginning-of-line whitespace) and go to the end of the line.

The file is split into sections. Every section begins with [SECTIONNAME] and contains a number of options of the form OPTION=VALUE. There may be whitespace around the = (equal sign). Section names and options are case-insensitive.

But values? Values are case-sensitive, so don't play with them. In particular, boolean values are one of YES or NO. Values can include whitespace by surrounding the entire value with " (double quote). Note, however, that there are no escape characters in such strings; all characters between the double quotes (including other double quotes) are taken verbatim. 😭

Values that represent a time duration are represented as a series of one or more NUMBER UNIT pairs, e.g. 60 s, 4 weeks 1 day, 5 years 2 minutes.

Values that represent an amount are in the usual amount syntax: CURRENCY:VALUE.FRACTION, e.g. EUR:1.50. The FRACTION portion may extend up to 8 places.

Values that represent filenames can begin with a /bin/sh-like variable reference. This can be simple, such as $TMPDIR/foo, or complex, such as ${TMPDIR:-${TMP:-/tmp}}/foo. The variables are expanded either using key-values from the [PATHS] section (see below) or from the environment (getenv()). The values from [PATHS] take precedence over those from the environment. If the variable name is found in neither [PATHS] nor the environment, a warning is printed and the value is left unchanged. Variables (including those from the environment) are expanded recursively, so if FOO=$BAR and BAR=buzz then the result is FOO=buzz. Recursion is bounded to at most 128 levels to avoid undefined behavior for mutually recursive expansions like if BAR=$FOO in the example above. 🫶

The [PATHS] section is special in that it contains paths that can be referenced using $ in other configuration values that specify filenames. Note that configuration options that are not specifically retrieved by the application as filenames will not see “$”-expressions expanded. To expand $-expressions when using taler-config, you must pass the -f command-line option.

The system automatically pre-populates the [PATHS] section with a few values at run-time (in addition to the values that are in the actual configuration file and automatically overwriting those values if they are present). These automatically generated values refer to installation properties from GNU autoconf. The values are usually dependent on an INSTALL_PREFIX which is determined by the --prefix option given to configure. The canonical values are:

  • LIBEXECDIR = $INSTALL_PREFIX/taler/libexec/
  • DOCDIR = $INSTALL_PREFIX/share/doc/taler/
  • ICONDIR = $INSTALL_PREFIX/share/icons/
  • LOCALEDIR = $INSTALL_PREFIX/share/locale/
  • PREFIX = $INSTALL_PREFIX/
  • BINDIR = $INSTALL_PREFIX/bin/
  • LIBDIR = $INSTALL_PREFIX/lib/taler/
  • DATADIR = $INSTALL_PREFIX/share/taler/

Note that on some platforms, the given paths may differ depending on how the system was compiled or installed; the above are just the canonical locations of the various resources. These automatically generated values are never written to disk. 💀

Files containing default values for many of the options described below are installed under $TALER_MERCHANT_PREFIX/share/taler-merchant/config.d/. The configuration file given with -c to Taler binaries overrides these defaults.

A configuration file may include another, by using the @INLINE@ directive, for example, in main.conf, you could write @INLINE@ sub.conf to include the entirety of sub.conf at that point in main.conf.

⚠️ Be extra careful when using taler-merchant-config -V VALUE to change configuration values: it will destroy all uses of @INLINE@ and furthermore remove all comments from the configuration file! Not me warning you twice, but bestie, it's giving danger. 🙈

🌈 GLOBAL OPTIONS 🌈

The [PATHS] section is special in that it contains paths that can be referenced using $ in other configuration values that specify filenames. For Taler, it commonly contains the following paths:

  • TALER_HOME — Home directory of the user, usually ${HOME}. Can be overwritten by testcases by setting ${TALER_TEST_HOME}.
  • TALER_DATA_HOME — Where should Taler store its long-term data. Usually ${TALER_HOME}/.local/share/taler-merchant/.
  • TALER_CONFIG_HOME — Where is the Taler configuration kept. Usually ${TALER_HOME}/.config/taler-merchant/.
  • TALER_CACHE_HOME — Where should Taler store cached data. Usually ${TALER_HOME}/.cache/taler-merchant/.
  • TALER_RUNTIME_DIR — Where should Taler store system runtime data (like UNIX domain sockets). Usually ${TMP}/taler-merchant-runtime.

🦋 CURRENCY SPECIFICATIONS 🦋

Sections with a name of the form [currency-$NAME] (where "$NAME" could be any unique string) are used to specify details about how currencies should be handled (and in particularly rendered) by the user interface. A detailed motivation for this section can be found in DD51. Different components can have different rules for the same currency. For example, a bank or merchant may decide to render Euros or Dollars with always exactly two fractional decimals, while an Exchange for the same currency may support additional decimals. The required options in each currency specification section are:

  • ENABLED — Set to YES or NO. If set to NO, the currency specification section is ignored. Can be used to disable currencies or select alternative sections for the same CODE with different choices.
  • CODE — Code name for the currency. Can be at most 11 characters, only the letters A-Z are allowed. Primary way to identify the currency in the protocol.
  • NAME — Long human-readable name for the currency. No restrictions, but should match the official name in English.
  • FRACTIONAL_INPUT_DIGITS — Number of fractional digits that users are allowed to enter manually in the user interface.
  • FRACTIONAL_NORMAL_DIGITS — Number of fractional digits that will be rendered normally (in terms of size and placement). Digits shown beyond this number will typically be rendered smaller and raised (if possible).
  • FRACTIONAL_TRAILING_ZERO_DIGITS — Number of fractional digits to pad rendered amounts with even if these digits are all zero. For example, use 2 to render 1 USD as $1.00.
  • ALT_UNIT_NAMES — JSON map determining how to encode very large or very tiny amounts in this currency. Maps a base10 logarithm to the respective currency symbol. Must include at least an entry for 0 (currency unit). For example, use {"0":"€"} for Euros or "{"0":"$"}" for Dollars. You could additionally use {"0":"€","3":"k€"} to render 3000 EUR as 3k€. For BTC a typical map would be {"0":"BTC","-3":"mBTC"}, informing the UI to render small amounts in milli-Bitcoin (mBTC). 🍓

👑 MERCHANT OPTIONS 👑

The following options are from the [merchant] section and used by the merchant backend.

  • DB — Plugin to use for the database, e.g. postgres.
  • SERVE — Should the HTTP server listen on a UNIX domain socket (set option to "unix"), or on a TCP socket (set option to "tcp"), or be activated via systemd (set option to "systemd").
  • BASE_URL — Which base URL should the merchant backend assume for itself in the protocol. Optional. If not given, the base URL will be constructed from X-Forwarded-Host, X-Forwarded-Port and X-Forwarded-Prefix headers that a reverse-proxy should be setting.
  • CURRENCY — Default currency of the merchant. Used primarily in the SPA in dialogs. Note that the merchant backend is multi-currency capable and setting this option will not prevent other currencies from being used. The full set of allowed currencies is determined from the overall list of exchanges that are enabled in the configuration.
  • UNIXPATH — Path to listen on if SERVE is set to "unix".
  • UNIXPATH_MODE — Access permission mask to use for the "UNIXPATH".
  • PORT — Port on which the HTTP server listens, e.g. 8080.
  • BIND_TO — Hostname to which the merchant HTTP server should be bound to, e.g. "localhost".
  • LEGAL_PRESERVATION — How long do we keep data in the database for tax audits after the transaction has completed? Default is 10 years.
  • DEFAULT_PAY_DELAY — What is the default payment delay for new instances. This is how long the customer has to pay the order before the offer expires. This backend default can be changed per-instance and then still overridden per-order. Defaults to one day if not specified in the configuration.
  • DEFAULT_REFUND_DELAY — What is the default refund delay for new instances. This is how long the merchant can grant refunds to the customer. Is added on top of the payment deadline (for an actual order). This backend default can be changed per-instance and then still overridden per-order. If the order overrides the wire transfer deadline and does not specify a refund deadline and if the DEFAULT_REFUND_DELAY would imply a longer refund deadline, then the wire transfer deadline is used for the refund deadline. Defaults to 15 days if not specified in the configuration.
  • DEFAULT_WIRE_TRANSFER_DELAY — What is the default wire transfer delay for new instances. This is how long the exchange has to settle the payment with a wire transfer, enabling refunds and aggregation of multiple transfers to happen until this time. The value given is added on top of the refund deadline and is then subject to rounding as per DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL. This backend default can be changed per-instance and then still overridden per-order. Defaults to one month if not specified in the configuration. 🔥
  • DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL — the rounding queen 👑 this one says which time interval a wire transfer deadline computed via DEFAULT_WIRE_TRANSFER_DELAY should get rounded up to. Supported values are NONE, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER and YEAR — and each one means the computed wire transfer deadline gets rounded up to the respective end of the next interval, using the local timezone of the merchant backend. This backend default can be changed per-instance. Ngl, rounding just does not apply if the wire deadline is overridden per-order. Defaults to NONE (aka no rounding up at all) if you don't specify it in the configuration.
  • FORCE_AUDIT — makes the merchant report every single transaction to the auditor (if the exchange even has one)? Default is NO. 💀 Do not change this except for testing, bestie, I'm serious.
  • ENABLE_SELF_PROVISIONING — set it to YES and unauthenticated clients can create new instances. That's the whole vibe.
  • MANDATORY_TAN_CHANNELS — a space-separated list of the TAN channels required for password reset 🔐. Can be "sms" or "email" or both.
  • HELPER_SMS — the helper binary used to send SMS. It gets the SMS phone number as the only command-line argument, and the message to send as the body. Optional — if it's missing, "sms" just won't work as a TAN channel. 🙈
  • HELPER_EMAIL — same deal but for e-mail ✉️. It gets the e-mail address as the only command-line argument, and the message to send as the body. Optional — if it's missing, "email" won't work as a TAN channel either.
  • STRICT_PROTOCOL_V19 — set to YES to strictly enforce protocol version 19 or later. It's a transient option for development, so don't get attached.
  • PAYMENT_TARGET_TYPES — space-separated list of the allowed payment target types (like bitcoin, iban or x-taler-bank). Defaults to "*", which means no restrictions at all if you don't specify it.
  • TERMS_DIR — the directory where the terms of service of the merchant operator can be found 📜. It must contain sub-directories for every supported language, using the two-character language code in lower case, e.g. "en/" or "fr/". Each subdirectory then has to contain files with the terms of service in various formats. The basename of the file of the current policy must be specified under TERMS_ETAG, and the extension defines the mime type. Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg", "png" and "gif". So like, using a TERMS_ETAG of "0", the structure could be this whole situation:
    • $TERMS_DIR/en/0.pdf
    • $TERMS_DIR/en/0.html
    • $TERMS_DIR/en/0.txt
    • $TERMS_DIR/fr/0.pdf
    • $TERMS_DIR/fr/0.html
    • $TERMS_DIR/de/0.txt
  • TERMS_ETAG — the basename of the file(s) in the TERMS_DIR holding the current terms of service. The value is also used for the "Etag" in the HTTP request to control caching. Whenever the terms of service change, the TERMS_ETAG MUST also change, and old values MUST NOT be repeated 🚨. For example, the date or version number of the terms of service SHOULD be used for the Etag. If there are minor (e.g. spelling) fixes to the terms of service, the TERMS_ETAG probably SHOULD NOT be changed. But whenever users must approve the new terms, the TERMS_ETAG MUST change. No exceptions, periodt.
  • PRIVACY_DIR — works the same as TERMS_DIR, just for the privacy policy 🕵️‍♀️.
  • PRIVACY_ETAG — works the same as TERMS_ETAG, just for the privacy policy.
  • DEFAULT_PERSONA — which "Persona" should be chosen by default for new clients using the SPA? The setting can always be changed locally in the browser, but new clients without a setting stored locally will use this value. Possible values include: "expert", "offline-vending-machine", "point-of-sale", "digital-publishing", "e-commerce" and "developer". Defaults to "expert", which means all stable features are enabled — main character energy only ✨.
  • PAYMENT_TARGET_REGEX — a POSIX regular expression imposing additional restrictions on the "payto://"-URIs allowed for bank accounts of instances of this system. For example, "payto://iban/CH.*" would restrict the system to only Swiss IBAN accounts 🇨🇭. Optional, no restrictions if not set.

🌸 MERCHANT KYCCHECK OPTIONS 🌸

These ones live in the [merchant-kyccheck] section and are used by the taler-merchant-kyccheck helper process, which checks with an exchange if we have know-your-customer (KYC) process issues to resolve. Very responsible of it.

  • AML_FREQ — specifies how often the backend should check for KYC status changes at the exchange if we're experiencing KYC issues. Default is every 6h. ⏰
  • AML_LOW_FREQ — specifies how often the backend should check for KYC status changes at the exchange if we are not experiencing any KYC issues, but there might be some with (delayed) aggregation, so we should at a low frequency still check for reports. Default is every 7 days.

🗄️ MERCHANT POSTGRES BACKEND DATABASE OPTIONS 🗄️

These options must be in the section [merchantdb-postgres] if the "postgres" plugin was selected for the database.

  • CONFIG — how to access the database, e.g. "postgres:///taler" to use the "taler" database. Testcases use "talercheck". 💾

🤝 KNOWN EXCHANGES (for merchants) 🤝

The merchant configuration can include a list of known exchanges if the merchant wants to specify that certain exchanges are explicitly trusted. For each trusted exchange, a section [merchant-exchange-$NAME] must exist, where $NAME is a merchant-given name for the exchange. The following options must be given in each "[exchange-$NAME]" section.

  • EXCHANGE_BASE_URL — base URL of the exchange, e.g. "https://exchange.demo.taler.net/" 🌐
  • MASTER_KEY — Crockford Base32 encoded master public key, the public version of the exchange's long-time offline signing key 🔑. Can be omitted — but in that case the exchange will NOT be trusted unless it is audited by a known auditor. Omitting MASTER_KEY can be useful if we do not trust the exchange without an auditor, but should pre-load the keys of this particular exchange on startup instead of waiting for it to be required by a client.
  • CURRENCY — name of the currency for which this exchange is used, e.g. "KUDOS". The entire section is ignored if the currency does not match the currency we use, which must be given in the [taler] section. 🪙
  • DISABLED — set to YES to disable this exchange. Optional option, defaults to NO. 💤

👀 SEE ALSO 👀

taler-merchant-passwd(1), taler-merchant-httpd(1)

🐛 BUGS 🐛

Report bugs by using https://bugs.taler.net/ or by sending electronic mail to <taler@gnu.org>. They're literally waiting for your bug reports, don't be shy 🫶

👑 AUTHOR 👑

GNU Taler contributors

2014-2025 Taler Systems SA (GPLv3+ or GFDL 1.3+)

Okay so that's the whole page, bestie — version 1.0, dated Dec 22, 2025, and it's the TALER-MERCHANT.CONF(5) manual page, all wrapped up with a little bow 🎀 Go configure something iconic 💅✨

📦 where this page comes from