TALER-MERCHANT.CONF(5)

NAME
taler-merchant.conf - Taler merchant configuration file

DESCRIPTION

The configuration file is line-oriented. Blank lines and whitespace at the beginning and end of a line are ignored. 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.

The values, however, are case-sensitive. 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!

  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 we "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
    Specifies to what time interval a wire transfer deadline computed via the DEFAULT_WIRE_TRANSFER_DELAY should be rounded up. Supported values are NONE, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER and YEAR, each implying that wire transfer deadline computed should be 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. Rounding does not apply if the wire deadline is overridden per-order. Defaults to NONE (no rounding up) if not specified in the configuration.

FORCE_AUDIT
    Force the merchant to report every transaction to the auditor (if the exchange has an auditor)? Default is NO. Do not change except for testing.

ENABLE_SELF_PROVISIONING
    Set to YES to allow unauthenticated clients to create new instances.

MANDATORY_TAN_CHANNELS
    Space-separted list of TAN channels required for password reset. Can be "sms" or "email" or both.

HELPER_SMS
    Helper binary to use to send SMS. Will get the SMS phone number as the only command-line argument, and the message to send as the body. Optional, if missing "sms" will not work as a TAN channel.

HELPER_EMAIL
    Helper binary to use to send e-mail. Will get the e-mail address as the only command-line argument, and the message to send as the body. Optional, if missing "email" will not work as a TAN channel.

STRICT_PROTOCOL_V19
    Set to YES to strictly enforce protocol version 19 or later. Transient option for development.

PAYMENT_TARGET_TYPES
    Space-separated list of allowed payment target types (like bitcoin, iban or x-taler-bank). Defaults to "*" which means no restrictions if not specified.

TERMS_DIR
    Directory where the terms of service of the merchant operator can be fund. The directory must contain sub-directories for every supported language, using the two-character language code in lower case, e.g. "en/" or "fr/". Each subdirectory must then 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. The extension defines the mime type. Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg", "png" and "gif". For example, using a TERMS_ETAG of "0", the structure could be the following:

•   $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
    Basename of the file(s) in the TERMS_DIR with 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. However, whenever users must approve the new terms, the TERMS_ETAG MUST change.

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

PAYMENT_TARGET_REGEX
    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

The following options are from the “[merchant-kyccheck]” section and used by the taler-merchant-kyccheck helper process which checks with an exchange if we have know-your-customer (KYC) process issues to resolve.

AML_FREQ
    Specifies how often the backend should check for KYC status changes at the exchange if we are 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

The following options must be in 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, public version of the exchange's long-time offline signing key. Can be omitted, 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>.

AUTHOR
GNU Taler contributors

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