taler-merchant.conf.5.rst (14787B)
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 202 PAYMENT_TARGET_TYPES 203 Space-separated list of allowed payment target types (like bitcoin, iban or x-taler-bank). 204 Defaults to "\*" which means no restrictions if not specified. 205 206 TERMS_DIR 207 Directory where the terms of service of the merchant operator can be fund. 208 The directory must contain sub-directories for every supported language, 209 using the two-character language code in lower case, e.g. "en/" or "fr/". 210 Each subdirectory must then contain files with the terms of service in 211 various formats. The basename of the file of the current policy must be 212 specified under ``TERMS_ETAG``. The extension defines the mime type. 213 Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg", 214 "png" and "gif". For example, using a ``TERMS_ETAG`` of "0", the structure 215 could be the following: 216 217 - $TERMS_DIR/en/0.pdf 218 - $TERMS_DIR/en/0.html 219 - $TERMS_DIR/en/0.txt 220 - $TERMS_DIR/fr/0.pdf 221 - $TERMS_DIR/fr/0.html 222 - $TERMS_DIR/de/0.txt 223 224 TERMS_ETAG 225 Basename of the file(s) in the ``TERMS_DIR`` with the current terms of service. 226 The value is also used for the "Etag" in the HTTP request to control 227 caching. Whenever the terms of service change, the ``TERMS_ETAG`` MUST also 228 change, and old values MUST NOT be repeated. For example, the date or 229 version number of the terms of service SHOULD be used for the Etag. If 230 there are minor (e.g. spelling) fixes to the terms of service, the 231 ``TERMS_ETAG`` probably SHOULD NOT be changed. However, whenever users must 232 approve the new terms, the ``TERMS_ETAG`` MUST change. 233 234 PRIVACY_DIR 235 Works the same as ``TERMS_DIR``, just for the privacy policy. 236 237 PRIVACY_ETAG 238 Works the same as ``TERMS_ETAG``, just for the privacy policy. 239 240 DEFAULT_PERSONA 241 Which "Persona" should be chosen by default for new clients 242 using the SPA? The setting can always changed locally in the 243 browser, but new clients without a setting stored locally will 244 use this value. 245 Possible values include: "expert", "offline-vending-machine", 246 "point-of-sale", "digital-publishing", "e-commerce" and "developer". 247 Defaults to "expert", which means all stable features are enabled. 248 249 GLOBAL_SPA_CONFIG_DATA 250 Additional configuration fields to pass to the SPA. This must be 251 a JSON object mapping keys to values. The main configuration keys 252 used are "contact_email", "contact_phone", "tax_info", "address" 253 and "support_url". For example, typical configuration might be:: 254 255 '{"contact_email":"contact@example.com", 256 "support_url":"https://tutorials.taler.net/", 257 "tax_info":"VAT number: #12345678", 258 "address": 259 {"name":"Acme Inc", 260 "street":"Acme St. 42", 261 "post_code":"1234", 262 "city":"Acme Town", 263 "country":"Acme Land"} 264 }' 265 266 See https://docs.taler.net/core/api-merchant.html#tsref-type-Location 267 for details on the "address" field. See also in the REST API specification 268 for ``/config`` the entry for ``SpaConfigOptions`` for other 269 SPA configuration options. 270 271 PAYMENT_TARGET_REGEX 272 POSIX regular expression imposing additional restrictions on the "payto://"-URIs allowed 273 for bank accounts of instances of this system. For example, "payto://iban/CH.*" would 274 restrict the system to only Swiss IBAN accounts. Optional, no restrictions if not set. 275 276 MERCHANT KYCCHECK OPTIONS 277 ------------------------- 278 279 The following options are from the “[merchant-kyccheck]” section and 280 used by the ``taler-merchant-kyccheck`` helper process which checks 281 with an exchange if we have know-your-customer (KYC) process issues 282 to resolve. 283 284 AML_FREQ 285 Specifies how often the backend should check for KYC status 286 changes at the exchange if we are experiencing KYC issues. 287 Default is every 6h. 288 289 AML_LOW_FREQ 290 Specifies how often the backend should check for KYC status 291 changes at the exchange if we are not experiencing any KYC 292 issues, but there might be some with (delayed) aggregation 293 so we should at a low frequency still check for reports. 294 Default is every 7 days. 295 296 297 MERCHANT POSTGRES BACKEND DATABASE OPTIONS 298 ------------------------------------------ 299 300 The following options must be in section “[merchantdb-postgres]” if the 301 “postgres” plugin was selected for the database. 302 303 CONFIG 304 How to access the database, e.g. “postgres:///taler” to use the 305 “taler” database. Testcases use “talercheck”. 306 307 308 KNOWN EXCHANGES (for merchants) 309 ------------------------------- 310 311 The merchant configuration can include a list of known exchanges if the 312 merchant wants to specify that certain exchanges are explicitly trusted. 313 For each trusted exchange, a section [merchant-exchange-$NAME] must exist, where 314 $NAME is a merchant-given name for the exchange. The following options 315 must be given in each “[exchange-$NAME]” section. 316 317 EXCHANGE_BASE_URL 318 Base URL of the exchange, e.g. “https://exchange.demo.taler.net/” 319 320 MASTER_KEY 321 Crockford Base32 encoded master public key, public version of the 322 exchange's long-time offline signing key. Can be omitted, in that 323 case the exchange will NOT be trusted unless it is audited by 324 a known auditor. 325 Omitting ``MASTER_KEY`` can be useful if we do not trust the exchange 326 without an auditor, but should pre-load the keys of this 327 particular exchange on startup instead of waiting for it to be 328 required by a client. 329 330 CURRENCY 331 Name of the currency for which this exchange is used, e.g. “KUDOS”. 332 The entire section is ignored if the currency does not match the currency 333 we use, which must be given in the ``[taler]`` section. 334 335 DISABLED 336 Set to YES to disable this exchange. Optional option, defaults to NO. 337 338 339 REPORT GENERATION 340 ----------------- 341 342 The merchant backend can be used to fetch and submit periodic reports. 343 The submission is handled using report generators. These are binaries 344 that receive the main report from standard input (stdin), and are told: 345 346 * the mime type using a "-m" command-line option, 347 * the report target address using a "-t" command-line option, and 348 * a report description using a "-d" command-line option. 349 350 The report generators should return 0 on success. Custom report generators are 351 configured using configuration sections [report-generator-$NAME], where $NAME 352 is a merchant-given name for the report generator. The following options must 353 be given in each “[report-generator-$NAME]” section. 354 355 BINARY 356 Name of the binary to execute. Currently this must be a single 357 filename (usually with the path), no command-line arguments may 358 be specified. 359 360 Default report generators include: 361 362 * ``[report-generator-email]`` with the BINARY 363 taler-merchant-report-generator-email will 364 send reports via e-mail using the UNIX mail program. 365 366 367 SEE ALSO 368 ======== 369 370 taler-merchant-passwd(1), taler-merchant-httpd(1) 371 372 BUGS 373 ==== 374 375 Report bugs by using https://bugs.taler.net/ or by sending electronic 376 mail to <taler@gnu.org>.