taler-merchant.conf.5.rst (15007B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2014-2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3.0, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Florian Dold 17 @author Benedikt Muller 18 @author Sree Harsha Totakura 19 @author Marcello Stanisci 20 @author Christian Grothoff 21 @author Javier Sepulveda 22 23 24 taler-merchant.conf(5) 25 ###################### 26 27 .. only:: html 28 29 Name 30 ==== 31 32 **taler-merchant.conf** - Taler configuration file 33 34 35 Description 36 =========== 37 38 .. include:: ../frags/common-conf-syntax.rst 39 40 Files containing default values for many of the options described below 41 are installed under ``$TALER_MERCHANT_PREFIX/share/taler-merchant/config.d/``. 42 The configuration file given with **-c** to Taler binaries 43 overrides these defaults. 44 45 A configuration file may include another, by using the ``@INLINE@`` directive, 46 for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to 47 include the entirety of ``sub.conf`` at that point in ``main.conf``. 48 49 Be extra careful when using ``taler-merchant-config -V VALUE`` to change configuration 50 values: it will destroy all uses of ``@INLINE@`` and furthermore remove all 51 comments from the configuration file! 52 53 54 GLOBAL OPTIONS 55 -------------- 56 57 The “[PATHS]” section is special in that it contains paths that can be 58 referenced using “$” in other configuration values that specify 59 filenames. For Taler, it commonly contains the following paths: 60 61 TALER_HOME 62 Home directory of the user, usually “${HOME}”. Can be overwritten by 63 testcases by setting ${TALER_TEST_HOME}. 64 65 TALER_DATA_HOME 66 Where should Taler store its long-term data. 67 Usually “${TALER_HOME}/.local/share/taler-merchant/”. 68 69 TALER_CONFIG_HOME 70 Where is the Taler configuration kept. 71 Usually “${TALER_HOME}/.config/taler-merchant/”. 72 73 TALER_CACHE_HOME 74 Where should Taler store cached data. 75 Usually “${TALER_HOME}/.cache/taler-merchant/”. 76 77 TALER_RUNTIME_DIR 78 Where should Taler store system runtime data (like UNIX domain 79 sockets). Usually “${TMP}/taler-merchant-runtime”. 80 81 .. include:: frags/currency-spec.rst 82 83 84 MERCHANT OPTIONS 85 ---------------- 86 87 The following options are from the “[merchant]” section and used by the 88 merchant backend. 89 90 DB 91 Plugin to use for the database, e.g._“postgres”. 92 93 SERVE 94 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"). 95 96 BASE_URL 97 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. 98 99 CURRENCY 100 Default currency of the merchant. Used primarily in the SPA 101 in dialogs. Note that the merchant backend is multi-currency 102 capable and setting this option will not prevent other 103 currencies from being used. The full set of allowed currencies 104 is determined from the overall list of exchanges that are enabled 105 in the configuration. 106 107 UNIXPATH 108 Path to listen on if we "SERVE" is set to "unix". 109 110 UNIXPATH_MODE 111 Access permission mask to use for the "UNIXPATH". 112 113 PORT 114 Port on which the HTTP server listens, e.g. 8080. 115 116 BIND_TO 117 Hostname to which the merchant HTTP server should be bound to, e.g. "localhost". 118 119 LEGAL_PRESERVATION 120 How long do we keep data in the database for tax audits after the 121 transaction has completed? Default is 10 years. 122 123 DEFAULT_PAY_DELAY 124 What is the default payment delay for new instances. This is how long the 125 customer has to pay the order before the offer expires. 126 This backend default can be changed per-instance and then still overridden per-order. 127 Defaults to one day if not specified in the configuration. 128 129 DEFAULT_REFUND_DELAY 130 What is the default refund delay for new instances. This is how long the 131 merchant can grant refunds to the customer. Is added on top of the 132 payment deadline (for an actual order). 133 This backend default can be changed per-instance and then still overridden per-order. 134 If the order overrides the wire transfer deadline and does not 135 specify a refund deadline and if the DEFAULT_REFUND_DELAY would 136 imply a longer refund deadline, then the wire transfer deadline 137 is used for the refund deadline. 138 Defaults to 15 days if not specified in the configuration. 139 140 DEFAULT_WIRE_TRANSFER_DELAY 141 What is the default wire transfer delay for new instances. This is how long the 142 exchange has to settle the payment with a wire transfer, enabling refunds and aggregation 143 of multiple transfers to happen until this time. 144 The value given is added on top of the refund deadline and is then 145 subject to rounding as per DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL. 146 This backend default can be changed per-instance and then still overridden per-order. 147 Defaults to one month if not specified in the configuration. 148 149 DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL 150 Specifies to what time interval a wire transfer deadline computed 151 via the DEFAULT_WIRE_TRANSFER_DELAY should be rounded up. Supported 152 values are NONE, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER and 153 YEAR, each implying that wire transfer deadline computed 154 should be rounded up to the respective end of the next interval 155 using the local timezone of the merchant backend. 156 This backend default can be changed per-instance. 157 Rounding does not apply if the wire deadline is overridden per-order. 158 Defaults to NONE (no rounding up) if not specified in the configuration. 159 160 FORCE_AUDIT 161 Force the merchant to report every transaction to the auditor 162 (if the exchange has an auditor)? Default is ``NO``. 163 Do not change except for testing. 164 165 ENABLE_SELF_PROVISIONING 166 Set to YES to allow unauthenticated clients to create new instances. 167 168 MANDATORY_TAN_CHANNELS 169 Space-separated list of TAN channels required for password reset. 170 Supported channels are ``sms`` and ``email``. Every channel in the list is 171 mandatory: listing both requires both challenges, while listing only one 172 requires only that challenge. 173 174 PASSWORD_CHANGE_MFA 175 Set to ``YES`` to require a merchant changing its own password to solve one 176 additional challenge using a channel from ``MANDATORY_TAN_CHANNELS``. If 177 multiple usable channels are configured, the merchant may choose any one of 178 them. The current password remains required. Enabling this option without 179 configuring at least one mandatory TAN channel is invalid. Defaults to 180 ``NO``. 181 182 PHONE_REGEX 183 Posix regular expression specifying which phone numbers are acceptable for 184 the instances. Useful to restrict phone numbers to those that work 185 with the ``HELPER_SMS``. Optional, if missing no restrictions apply. 186 187 HELPER_SMS 188 Helper binary to use to send SMS. 189 Will get the SMS phone number as the only command-line argument, 190 and the message to send as the body. 191 Optional, if missing "sms" will not work as a TAN channel. 192 193 HELPER_EMAIL 194 Helper binary to use to send e-mail. 195 Will get the e-mail address as the only command-line argument, 196 and the message to send as the body. 197 Optional, if missing "email" will not work as a TAN channel. 198 199 STRICT_PROTOCOL_V19 200 Set to YES to strictly enforce protocol version 19 or later. Transient option for development. 201 Then the "external" authentication method is rejected when creating an instance or 202 changing its authentication, and the instance password is no longer accepted as a 203 bearer token (clients must use login tokens). 204 205 PAYMENT_TARGET_TYPES 206 Space-separated list of allowed payment target types (like bitcoin, iban or x-taler-bank). 207 Defaults to "\*" which means no restrictions if not specified. 208 209 TERMS_DIR 210 Directory where the terms of service of the merchant operator can be fund. 211 The directory must contain sub-directories for every supported language, 212 using the two-character language code in lower case, e.g. "en/" or "fr/". 213 Each subdirectory must then contain files with the terms of service in 214 various formats. The basename of the file of the current policy must be 215 specified under ``TERMS_ETAG``. The extension defines the mime type. 216 Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg", 217 "png" and "gif". For example, using a ``TERMS_ETAG`` of "0", the structure 218 could be the following: 219 220 - $TERMS_DIR/en/0.pdf 221 - $TERMS_DIR/en/0.html 222 - $TERMS_DIR/en/0.txt 223 - $TERMS_DIR/fr/0.pdf 224 - $TERMS_DIR/fr/0.html 225 - $TERMS_DIR/de/0.txt 226 227 TERMS_ETAG 228 Basename of the file(s) in the ``TERMS_DIR`` with the current terms of service. 229 The value is also used for the "Etag" in the HTTP request to control 230 caching. Whenever the terms of service change, the ``TERMS_ETAG`` MUST also 231 change, and old values MUST NOT be repeated. For example, the date or 232 version number of the terms of service SHOULD be used for the Etag. If 233 there are minor (e.g. spelling) fixes to the terms of service, the 234 ``TERMS_ETAG`` probably SHOULD NOT be changed. However, whenever users must 235 approve the new terms, the ``TERMS_ETAG`` MUST change. 236 237 PRIVACY_DIR 238 Works the same as ``TERMS_DIR``, just for the privacy policy. 239 240 PRIVACY_ETAG 241 Works the same as ``TERMS_ETAG``, just for the privacy policy. 242 243 DEFAULT_PERSONA 244 Which "Persona" should be chosen by default for new clients 245 using the SPA? The setting can always changed locally in the 246 browser, but new clients without a setting stored locally will 247 use this value. 248 Possible values include: "expert", "offline-vending-machine", 249 "point-of-sale", "digital-publishing", "e-commerce" and "developer". 250 Defaults to "expert", which means all stable features are enabled. 251 252 GLOBAL_SPA_CONFIG_DATA 253 Additional configuration fields to pass to the SPA. This must be 254 a JSON object mapping keys to values. The main configuration keys 255 used are "contact_email", "contact_phone", "tax_info", "address" 256 and "support_url". For example, typical configuration might be:: 257 258 '{"contact_email":"contact@example.com", 259 "support_url":"https://tutorials.taler.net/", 260 "tax_info":"VAT number: #12345678", 261 "address": 262 {"name":"Acme Inc", 263 "street":"Acme St. 42", 264 "post_code":"1234", 265 "city":"Acme Town", 266 "country":"Acme Land"} 267 }' 268 269 See https://docs.taler.net/core/api-merchant.html#tsref-type-Location 270 for details on the "address" field. See also in the REST API specification 271 for ``/config`` the entry for ``SpaConfigOptions`` for other 272 SPA configuration options. 273 274 PAYMENT_TARGET_REGEX 275 POSIX regular expression imposing additional restrictions on the "payto://"-URIs allowed 276 for bank accounts of instances of this system. For example, "payto://iban/CH.*" would 277 restrict the system to only Swiss IBAN accounts. Optional, no restrictions if not set. 278 279 MERCHANT KYCCHECK OPTIONS 280 ------------------------- 281 282 The following options are from the “[merchant-kyccheck]” section and 283 used by the ``taler-merchant-kyccheck`` helper process which checks 284 with an exchange if we have know-your-customer (KYC) process issues 285 to resolve. 286 287 AML_FREQ 288 Specifies how often the backend should check for KYC status 289 changes at the exchange if we are experiencing KYC issues. 290 Default is every 6h. 291 292 AML_LOW_FREQ 293 Specifies how often the backend should check for KYC status 294 changes at the exchange if we are not experiencing any KYC 295 issues, but there might be some with (delayed) aggregation 296 so we should at a low frequency still check for reports. 297 Default is every 7 days. 298 299 300 MERCHANT POSTGRES BACKEND DATABASE OPTIONS 301 ------------------------------------------ 302 303 The following options must be in section “[merchantdb-postgres]” if the 304 “postgres” plugin was selected for the database. 305 306 CONFIG 307 How to access the database, e.g. “postgres:///taler” to use the 308 “taler” database. Testcases use “talercheck”. 309 310 311 KNOWN EXCHANGES (for merchants) 312 ------------------------------- 313 314 The merchant configuration can include a list of known exchanges if the 315 merchant wants to specify that certain exchanges are explicitly trusted. 316 For each trusted exchange, a section [merchant-exchange-$NAME] must exist, where 317 $NAME is a merchant-given name for the exchange. The following options 318 must be given in each “[exchange-$NAME]” section. 319 320 EXCHANGE_BASE_URL 321 Base URL of the exchange, e.g. “https://exchange.demo.taler.net/” 322 323 MASTER_KEY 324 Crockford Base32 encoded master public key, public version of the 325 exchange's long-time offline signing key. Can be omitted, in that 326 case the exchange will NOT be trusted unless it is audited by 327 a known auditor. 328 Omitting ``MASTER_KEY`` can be useful if we do not trust the exchange 329 without an auditor, but should pre-load the keys of this 330 particular exchange on startup instead of waiting for it to be 331 required by a client. 332 333 CURRENCY 334 Name of the currency for which this exchange is used, e.g. “KUDOS”. 335 The entire section is ignored if the currency does not match the currency 336 we use, which must be given in the ``[taler]`` section. 337 338 DISABLED 339 Set to YES to disable this exchange. Optional option, defaults to NO. 340 341 342 REPORT GENERATION 343 ----------------- 344 345 The merchant backend can be used to fetch and submit periodic reports. 346 The submission is handled using report generators. These are binaries 347 that receive the main report from standard input (stdin), and are told: 348 349 * the mime type using a "-m" command-line option, 350 * the report target address using a "-t" command-line option, and 351 * a report description using a "-d" command-line option. 352 353 The report generators should return 0 on success. Custom report generators are 354 configured using configuration sections [report-generator-$NAME], where $NAME 355 is a merchant-given name for the report generator. The following options must 356 be given in each “[report-generator-$NAME]” section. 357 358 BINARY 359 Name of the binary to execute. Currently this must be a single 360 filename (usually with the path), no command-line arguments may 361 be specified. 362 363 Default report generators include: 364 365 * ``[report-generator-email]`` with the BINARY 366 taler-merchant-report-generator-email will 367 send reports via e-mail using the UNIX mail program. 368 369 370 SEE ALSO 371 ======== 372 373 taler-merchant-passwd(1), taler-merchant-httpd(1) 374 375 BUGS 376 ==== 377 378 Report bugs by using https://bugs.taler.net/ or by sending electronic 379 mail to <taler@gnu.org>.