taler-merchant.conf.5.rst (12055B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2014-2024 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. Can be "sms" or "email" or both. 170 171 HELPER_SMS 172 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. 173 174 HELPER_EMAIL 175 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. 176 177 STRICT_PROTOCOL_V19 178 Set to YES to strictly enforce protocol version 19 or later. Transient option for development. 179 180 PAYMENT_TARGET_TYPES 181 Space-separated list of allowed payment target types (like bitcoin, iban or x-taler-bank). 182 Defaults to "\*" which means no restrictions if not specified. 183 184 TERMS_DIR 185 Directory where the terms of service of the merchant operator can be fund. 186 The directory must contain sub-directories for every supported language, 187 using the two-character language code in lower case, e.g. "en/" or "fr/". 188 Each subdirectory must then contain files with the terms of service in 189 various formats. The basename of the file of the current policy must be 190 specified under ``TERMS_ETAG``. The extension defines the mime type. 191 Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg", 192 "png" and "gif". For example, using a ``TERMS_ETAG`` of "0", the structure 193 could be the following: 194 195 - $TERMS_DIR/en/0.pdf 196 - $TERMS_DIR/en/0.html 197 - $TERMS_DIR/en/0.txt 198 - $TERMS_DIR/fr/0.pdf 199 - $TERMS_DIR/fr/0.html 200 - $TERMS_DIR/de/0.txt 201 202 TERMS_ETAG 203 Basename of the file(s) in the ``TERMS_DIR`` with the current terms of service. 204 The value is also used for the "Etag" in the HTTP request to control 205 caching. Whenever the terms of service change, the ``TERMS_ETAG`` MUST also 206 change, and old values MUST NOT be repeated. For example, the date or 207 version number of the terms of service SHOULD be used for the Etag. If 208 there are minor (e.g. spelling) fixes to the terms of service, the 209 ``TERMS_ETAG`` probably SHOULD NOT be changed. However, whenever users must 210 approve the new terms, the ``TERMS_ETAG`` MUST change. 211 212 PRIVACY_DIR 213 Works the same as ``TERMS_DIR``, just for the privacy policy. 214 215 PRIVACY_ETAG 216 Works the same as ``TERMS_ETAG``, just for the privacy policy. 217 218 DEFAULT_PERSONA 219 Which "Persona" should be chosen by default for new clients 220 using the SPA? The setting can always changed locally in the 221 browser, but new clients without a setting stored locally will 222 use this value. 223 Possible values include: "expert", "offline-vending-machine", 224 "point-of-sale", "digital-publishing", "e-commerce" and "developer". 225 Defaults to "expert", which means all stable features are enabled. 226 227 PAYMENT_TARGET_REGEX 228 POSIX regular expression imposing additional restrictions on the "payto://"-URIs allowed 229 for bank accounts of instances of this system. For example, "payto://iban/CH.*" would 230 restrict the system to only Swiss IBAN accounts. Optional, no restrictions if not set. 231 232 MERCHANT KYCCHECK OPTIONS 233 ------------------------- 234 235 The following options are from the “[merchant-kyccheck]” section and 236 used by the ``taler-merchant-kyccheck`` helper process which checks 237 with an exchange if we have know-your-customer (KYC) process issues 238 to resolve. 239 240 AML_FREQ 241 Specifies how often the backend should check for KYC status 242 changes at the exchange if we are experiencing KYC issues. 243 Default is every 6h. 244 245 AML_LOW_FREQ 246 Specifies how often the backend should check for KYC status 247 changes at the exchange if we are not experiencing any KYC 248 issues, but there might be some with (delayed) aggregation 249 so we should at a low frequency still check for reports. 250 Default is every 7 days. 251 252 253 MERCHANT POSTGRES BACKEND DATABASE OPTIONS 254 ------------------------------------------ 255 256 The following options must be in section “[merchantdb-postgres]” if the 257 “postgres” plugin was selected for the database. 258 259 CONFIG 260 How to access the database, e.g. “postgres:///taler” to use the 261 “taler” database. Testcases use “talercheck”. 262 263 264 KNOWN EXCHANGES (for merchants) 265 ------------------------------- 266 267 The merchant configuration can include a list of known exchanges if the 268 merchant wants to specify that certain exchanges are explicitly trusted. 269 For each trusted exchange, a section [merchant-exchange-$NAME] must exist, where 270 $NAME is a merchant-given name for the exchange. The following options 271 must be given in each “[exchange-$NAME]” section. 272 273 EXCHANGE_BASE_URL 274 Base URL of the exchange, e.g. “https://exchange.demo.taler.net/” 275 276 MASTER_KEY 277 Crockford Base32 encoded master public key, public version of the 278 exchange's long-time offline signing key. Can be omitted, in that 279 case the exchange will NOT be trusted unless it is audited by 280 a known auditor. 281 Omitting ``MASTER_KEY`` can be useful if we do not trust the exchange 282 without an auditor, but should pre-load the keys of this 283 particular exchange on startup instead of waiting for it to be 284 required by a client. 285 286 CURRENCY 287 Name of the currency for which this exchange is used, e.g. “KUDOS”. 288 The entire section is ignored if the currency does not match the currency 289 we use, which must be given in the ``[taler]`` section. 290 291 DISABLED 292 Set to YES to disable this exchange. Optional option, defaults to NO. 293 294 295 SEE ALSO 296 ======== 297 298 taler-merchant-passwd(1), taler-merchant-httpd(1) 299 300 BUGS 301 ==== 302 303 Report bugs by using https://bugs.taler.net/ or by sending electronic 304 mail to <taler@gnu.org>.