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