NEW Option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS: enter the real amounts on multicurrency payments

On a payment for an invoice in a foreign currency, Dolibarr derives one of
the two amounts (company currency / invoice currency) from the other at the
invoice rate. The amount really paid in the company currency almost always
differs from that derivation, so the recorded payment does not match the
bank.

Under this option (off by default):
- both the amount in the invoice currency and the real amount in the
  company currency can be entered on the payment pages (customer and
  supplier); a read-only derived exchange rate is displayed live;
- Paiement/PaiementFourn::create() keep both amounts as entered, derive
  the per-invoice exchange rate from them and store it on the dispatch
  line; a warning is raised when the derived rate is far from the invoice
  rate (probable swap), an error when the signs differ;
- the paid status is decided on the balance in the invoice currency: the
  residual amount in company currency is the exchange-rate difference;
- the payment list of the invoice card and the invoice/payment tooltips
  show the amount in the invoice currency and the rate as a sub-line;
- a payment whose foreign amount is missing can be fixed a posteriori from
  the payment card (hidden option MULTICURRENCY_PAYMENT_ALLOW_EDIT_REAL_AMOUNT,
  admin only).

Author: Pichinov-Jose

htdocs/compta/paiement.php

@@ -14,6 +14,7 @@
  * Copyright (C) 2023		William Mead			<william.mead@manchenumerique.fr>
  * Copyright (C) 2024-2025	MDW						<mdeweerd@users.noreply.github.com>
  * Copyright (C) 2025       Josep Lluís Amador      <joseplluis@lliuretic.cat>
+ * Copyright (C) 2026		José MARTINEZ		<jose.martinez@pichinov.com>
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -206,8 +207,8 @@
 			$error++;
 		}
 
-		// Check if payments in both currency
-		if ($totalpayment > 0 && $multicurrency_totalpayment > 0) {
+		// Check if payments in both currency (allowed when entering the real amounts in both currencies, option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS)
+		if ($totalpayment > 0 && $multicurrency_totalpayment > 0 && !getDolGlobalInt('MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS')) {
 			$langs->load("errors");
 			setEventMessages($langs->transnoentities('ErrorPaymentInBothCurrency'), null, 'errors');
 			$error++;
@@ -502,6 +503,27 @@ function callForResult(imgId, multicurrency = 0)
 						});';
 		print '	});'."\n";
 
+		// Live display of the derived exchange rate when the real amounts may be entered in both currencies (option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS)
+		if (getDolGlobalInt('MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS')) {
+			print ' $(document).ready(function () {
+				var derivedratelabel = "'.dol_escape_js($langs->trans('Rate')).'";
+				function updateDerivedRates() {
+					jQuery("span[id^=\'derivedrate_\']").each(function () {
+						var facid = this.id.substring(12);
+						var comp = parseFloat((jQuery("input[name=\'amount_" + facid + "\']").val() || "").replace(",", "."));
+						var forc = parseFloat((jQuery("input[name=\'multicurrency_amount_" + facid + "\']").val() || "").replace(",", "."));
+						if (!isNaN(comp) && comp != 0 && !isNaN(forc) && forc != 0) {
+							jQuery(this).html("<br>" + derivedratelabel + " : " + (Math.abs(forc) / Math.abs(comp)).toFixed(8).replace(/0+$/, "").replace(/\.$/, ""));
+						} else {
+							jQuery(this).html("");
+						}
+					});
+				}
+				jQuery("#payment_form").find("input.amount, input.multicurrency_amount").on("keyup change", updateDerivedRates);
+				updateDerivedRates();
+			});'."\n";
+		}
+
 		print '	</script>'."\n";
 	}
 
@@ -932,6 +954,10 @@ function callForResult(imgId, multicurrency = 0)
 					print '<input type="text" class="maxwidth75" name="'.$namef.'_disabled" value="'.dol_escape_htmltag(GETPOST($namef)).'" disabled>';
 					print '<input type="hidden" name="'.$namef.'" value="'.dol_escape_htmltag(GETPOST($namef)).'">';
 				}
+				// Read-only derived exchange rate, shown when the real amounts may be entered in both currencies (option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS)
+				if (getDolGlobalInt('MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS') && isModEnabled('multicurrency') && !empty($objp->multicurrency_code) && $objp->multicurrency_code != $conf->currency) {
+					print '<span class="opacitymedium small" id="derivedrate_'.$objp->facid.'"></span>';
+				}
 				print "</td>";
 
 				$parameters = array();

htdocs/compta/paiement/class/paiement.class.php

@@ -14,6 +14,7 @@
  * Copyright (C) 2023       Joachim Kueter			<git-jk@bloxera.com>
  * Copyright (C) 2023       Sylvain Legrand			<technique@infras.fr>
  * Copyright (C) 2024-2026	MDW						<mdeweerd@users.noreply.github.com>
+ * Copyright (C) 2026		José MARTINEZ		<jose.martinez@pichinov.com>
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -341,8 +342,40 @@ public function create($user, $closepaidinvoices = 0, $thirdparty = null)
 			$invoice_multicurrency_tx = $tmparray['invoice_multicurrency_tx'];
 			$invoice_multicurrency_code = $tmparray['invoice_multicurrency_code'];
 
+			// Option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS: if both the amount in the invoice currency and the real
+			// amount in the company currency have been provided for this invoice, we keep both amounts as entered (no
+			// derivation at the invoice rate) and we derive the exchange rate from them.
+			$userealamounts = false;
+			if (getDolGlobalInt('MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS')
+				&& (float) price2num(isset($this->amounts[$key]) ? $this->amounts[$key] : 0) != 0
+				&& (float) price2num(isset($this->multicurrency_amounts[$key]) ? $this->multicurrency_amounts[$key] : 0) != 0) {
+				$userealamounts = true;
+			}
+			$invoiceidfortrans = $key; // intermediate name: phan flags a variable named key passed to trans()
+
 			// $key is id of invoice, $value is amount, $way is 'dolibarr' if amount is in main currency, 'customer' if in foreign currency
-			if ($invoice_multicurrency_tx) {
+			if ($userealamounts) {
+				$realcompanyamount = (float) price2num($this->amounts[$key], 'MU');
+				$realforeignamount = (float) price2num($this->multicurrency_amounts[$key], 'MU');
+				// Both real amounts must share the same sign
+				if (($realcompanyamount > 0) != ($realforeignamount > 0)) {
+					$this->error = $langs->trans('ErrorPaymentRealAmountsMustHaveSameSign', (string) $invoiceidfortrans);
+					return -1;
+				}
+				// The counterpart amount is the real amount entered by the user, not a value derived at the invoice rate
+				$value_converted = ($way == 'dolibarr') ? $realforeignamount : $realcompanyamount;
+				// Derived exchange rate, Dolibarr convention: multicurrency_tx = amount in invoice currency / amount in company currency
+				$derived_tx = (float) price2num(abs($realforeignamount) / abs($realcompanyamount), 'MU');
+				if ($derived_tx <= 0) {
+					$this->error = $langs->trans('FailedToFoundTheConversionRateForInvoice');
+					return -1;
+				}
+				$this->multicurrency_tx[$key] = $derived_tx;
+				// Non-blocking warning if the derived rate is far (> 50%) from the invoice rate (probable swap of the two amounts)
+				if ($invoice_multicurrency_tx && abs($derived_tx - $invoice_multicurrency_tx) > (0.5 * $invoice_multicurrency_tx)) {
+					setEventMessages($langs->trans('WarningPaymentDerivedRateFarFromInvoiceRate', (string) $invoiceidfortrans, price2num($derived_tx, 'MU'), price2num($invoice_multicurrency_tx, 'MU')), null, 'warnings');
+				}
+			} elseif ($invoice_multicurrency_tx) {
 				if ($way == 'dolibarr') {
 					$value_converted = (float) price2num($value * $invoice_multicurrency_tx, 'MU');
 				} else {
@@ -472,8 +505,13 @@ public function create($user, $closepaidinvoices = 0, $thirdparty = null)
 				$facid = $key;
 				if (is_numeric($amount) && $amount != 0) {
 					$amount = price2num($amount);
+					// Under MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS, store the per-invoice exchange rate derived from the real amounts instead of the single payment rate
+					$multicurrencytxtostore = $currencytxofpayment;
+					if (getDolGlobalInt('MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS') && !empty($this->multicurrency_tx[$key])) {
+						$multicurrencytxtostore = $this->multicurrency_tx[$key];
+					}
 					$sql = "INSERT INTO ".MAIN_DB_PREFIX."paiement_facture (fk_facture, fk_paiement, amount, multicurrency_amount, multicurrency_code, multicurrency_tx)";
-					$sql .= " VALUES (".((int) $facid).", ".((int) $this->id).", ".((float) $amount).", ".((float) $this->multicurrency_amounts[$key]).", ".($currencyofpayment ? "'".$this->db->escape($currencyofpayment)."'" : 'NULL').", ".(!empty($this->multicurrency_tx) ? (float) $currencytxofpayment : 1).")";
+					$sql .= " VALUES (".((int) $facid).", ".((int) $this->id).", ".((float) $amount).", ".((float) $this->multicurrency_amounts[$key]).", ".($currencyofpayment ? "'".$this->db->escape($currencyofpayment)."'" : 'NULL').", ".(!empty($multicurrencytxtostore) ? (float) $multicurrencytxtostore : 1).")";
 
 					dol_syslog(get_class($this).'::create Amount line '.$key.' insert paiement_facture', LOG_DEBUG);
 					$resql = $this->db->query($sql);
@@ -488,6 +526,17 @@ public function create($user, $closepaidinvoices = 0, $thirdparty = null)
 							$deposits = $invoice->getSumDepositsUsed();
 							$alreadypayed = price2num($paiement + $creditnotes + $deposits, 'MT');
 							$remaintopay = price2num($invoice->total_ttc - $paiement - $creditnotes - $deposits, 'MT');
+							// Under MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS, a multicurrency invoice paid at the real amounts keeps a
+							// residual amount in company currency (the exchange-rate difference), so the "paid" status must be decided
+							// on the balance in the invoice currency and not on the balance in the company currency.
+							$remaintopayforclosure = $remaintopay;
+							if (getDolGlobalInt('MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS') && isModEnabled('multicurrency')
+								&& !empty($invoice->multicurrency_code) && $invoice->multicurrency_code != $conf->currency) {
+								$multicurrency_paiement = $invoice->getSommePaiement(1);
+								$multicurrency_creditnotes = $invoice->getSumCreditNotesUsed(1);
+								$multicurrency_deposits = $invoice->getSumDepositsUsed(1);
+								$remaintopayforclosure = price2num($invoice->multicurrency_total_ttc - $multicurrency_paiement - $multicurrency_creditnotes - $multicurrency_deposits, 'MT');
+							}
 
 							//var_dump($invoice->total_ttc.' - '.$paiement.' -'.$creditnotes.' - '.$deposits.' - '.$remaintopay);exit;
 
@@ -502,7 +551,7 @@ public function create($user, $closepaidinvoices = 0, $thirdparty = null)
 
 							if (!in_array($invoice->type, $affected_types)) {
 								dol_syslog("Invoice ".$facid." is not a standard, nor replacement invoice, nor credit note, nor deposit invoice, nor situation invoice. We do nothing more.");
-							} elseif ($remaintopay) {
+							} elseif ($remaintopayforclosure) {
 								// hook to have an option to automatically close a closable invoice with less payment than the total amount (e.g. agreed cash discount terms)
 								global $hookmanager;
 								$hookmanager->initHooks(array('paymentdao'));
@@ -566,22 +615,46 @@ public function create($user, $closepaidinvoices = 0, $thirdparty = null)
 											}
 										}
 
+										// Option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS: carry the invoice currency and the real exchange
+										// rate onto the discount, and scale its company-currency value to the real amount paid, so the real
+										// cost propagates when the deposit is later consumed in a final invoice. Without the option, nothing changes.
+										$discountmccode = '';
+										$discountmctx = null;
+										$discountrealratio = 1;
+										if (getDolGlobalInt('MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS') && isModEnabled('multicurrency')
+											&& !empty($invoice->multicurrency_code) && $invoice->multicurrency_code != $conf->currency) {
+											$discountmccode = $invoice->multicurrency_code;
+											$discountmctx = $invoice->multicurrency_tx;
+											$realeurpaid = (float) price2num($invoice->getSommePaiement(0), 'MT');
+											$realfxpaid = (float) price2num($invoice->getSommePaiement(1), 'MT');
+											if ($realeurpaid != 0 && $realfxpaid != 0) {
+												$discountmctx = (float) price2num($realfxpaid / $realeurpaid, 'MU');
+												if ((float) $invoice->total_ttc != 0) {
+													$discountrealratio = $realeurpaid / (float) $invoice->total_ttc;
+												}
+											}
+										}
+
 										foreach ($amount_ht as $keyfordiscount => $xxx) {
 											$parts = explode('|', (string) $keyfordiscount, 2);
 											$tva_tx = $parts[0];
 											$vat_src_code = isset($parts[1]) ? $parts[1] : '';
-											$discount->amount_ht = abs($amount_ht[$keyfordiscount]);
-											$discount->total_ht = abs($amount_ht[$keyfordiscount]);
-											$discount->amount_tva = abs($amount_tva[$keyfordiscount]);
-											$discount->total_tva = abs($amount_tva[$keyfordiscount]);
-											$discount->amount_ttc = abs($amount_ttc[$keyfordiscount]);
-											$discount->total_ttc = abs($amount_ttc[$keyfordiscount]);
+											$discount->amount_ht = abs($amount_ht[$keyfordiscount] * $discountrealratio);
+											$discount->total_ht = abs($amount_ht[$keyfordiscount] * $discountrealratio);
+											$discount->amount_tva = abs($amount_tva[$keyfordiscount] * $discountrealratio);
+											$discount->total_tva = abs($amount_tva[$keyfordiscount] * $discountrealratio);
+											$discount->amount_ttc = abs($amount_ttc[$keyfordiscount] * $discountrealratio);
+											$discount->total_ttc = abs($amount_ttc[$keyfordiscount] * $discountrealratio);
 											$discount->multicurrency_amount_ht = abs($multicurrency_amount_ht[$keyfordiscount]);
 											$discount->multicurrency_total_ht = abs($multicurrency_amount_ht[$keyfordiscount]);
 											$discount->multicurrency_amount_tva = abs($multicurrency_amount_tva[$keyfordiscount]);
 											$discount->multicurrency_total_tva = abs($multicurrency_amount_tva[$keyfordiscount]);
 											$discount->multicurrency_amount_ttc = abs($multicurrency_amount_ttc[$keyfordiscount]);
 											$discount->multicurrency_total_ttc = abs($multicurrency_amount_ttc[$keyfordiscount]);
+											if ($discountmccode !== '') {
+												$discount->multicurrency_code = $discountmccode;
+												$discount->multicurrency_tx = $discountmctx;
+											}
 											$discount->tva_tx = abs((float) $tva_tx);
 											$discount->vat_src_code = $vat_src_code;
 
@@ -1421,6 +1494,12 @@ public function getNomUrl($withpicto = 0, $option = '', $mode = 'withlistofinvoi
 		if ($this->amount) {
 			$label .= '<br><strong>'.$langs->trans("Amount").':</strong> '.price($this->amount, 0, $langs, 1, -1, -1, $conf->currency);
 		}
+		// Amount in the invoice currency and derived rate (option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS)
+		if (getDolGlobalInt('MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS') && isModEnabled('multicurrency') && !empty($this->multicurrency_amount) && (float) $this->amount != 0 && abs((float) $this->multicurrency_amount - (float) $this->amount) > 0.0001) {
+			$langs->load("multicurrency");
+			$label .= '<br><strong>'.$langs->trans("MulticurrencyPaymentAmount").':</strong> '.price($this->multicurrency_amount, 0, $langs, 1);
+			$label .= '<br><strong>'.$langs->trans("Rate").':</strong> '.price2num((float) $this->multicurrency_amount / (float) $this->amount, 'MU');
+		}
 		if ($mode == 'withlistofinvoices') {
 			$arraybill = $this->getBillsArray();
 			if (is_array($arraybill) && count($arraybill) > 0) {

htdocs/fourn/class/fournisseur.facture.class.php

@@ -18,6 +18,7 @@
  * Copyright (C) 2024-2026	MDW						<mdeweerd@users.noreply.github.com>
  * Copyright (C) 2026		Vincent de Grandpré		<vincent@de-grandpre.quebec>
  * Copyright (C) 2026		Jose Martinez				<jose.martinez@pichinov.com>
+ * Copyright (C) 2026		José MARTINEZ		<jose.martinez@pichinov.com>
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -2907,6 +2908,17 @@ public function getTooltipContentArray($params)
 		if (!empty($this->total_ttc)) {
 			$datas['totalttc'] = '<br><b>'.$langs->trans('AmountTTC').':</b> '.price($this->total_ttc, 0, $langs, 0, -1, -1, $conf->currency);
 		}
+		// Multicurrency rate and total in the invoice currency (option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS)
+		if (getDolGlobalInt('MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS') && isModEnabled('multicurrency') && !empty($this->multicurrency_code) && $this->multicurrency_code != $conf->currency) {
+			$datas['multicurrencyrate'] = '<br><b>'.$langs->trans('CurrencyRate').':</b> '.price2num($this->multicurrency_tx, 'MU');
+			if (!empty($this->multicurrency_total_ht)) {
+				$datas['multicurrencytotalht'] = '<br><b>'.$langs->trans('MulticurrencyAmountHT').':</b> '.price($this->multicurrency_total_ht, 0, $langs, 0, -1, -1, $this->multicurrency_code);
+			}
+			if (!empty($this->multicurrency_total_tva)) {
+				$datas['multicurrencytotaltva'] = '<br><b>'.$langs->trans('MulticurrencyAmountVAT').':</b> '.price($this->multicurrency_total_tva, 0, $langs, 0, -1, -1, $this->multicurrency_code);
+			}
+			$datas['multicurrencytotalttc'] = '<br><b>'.$langs->trans('MulticurrencyAmountTTC').':</b> '.price($this->multicurrency_total_ttc, 0, $langs, 0, -1, -1, $this->multicurrency_code);
+		}
 		return $datas;
 	}