taler-merchant.conf(5)

17.91. taler-merchant.conf(5)#

17.91.1. Name#

taler-merchant.conf - Taler configuration file

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

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

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

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

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

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.

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

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

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

17.91.3. SEE ALSO#

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

17.91.4. BUGS#

Report bugs by using https://bugs.taler.net/ or by sending electronic mail to <taler@gnu.org>.