Add metadata feature doc and update use case details

docs/product/features/metadata.md

@@ -0,0 +1,18 @@
+
+# Metadata
+The very nature of Mojaloop as a switch interconnecting DFSPs means that Mojaloop cannot ascribe meaning to the transaction. However, transactions do also have the potential to carry metadata alongside the payment details, and it is this metadata that can be used by a scheme to link the payment to transactions outside Mojaloop, so supporting interoperability by carrying context across DFSPs. This applies to either a push or an RTP transaction.
+
+Metadata helps describe, contextualize, or manage the payment beyond just the amount, sender, and recipient. It is not strictly required to move money, but it is crucial for reconciliation, automation, compliance and customer experience.
+
+At the simplest level this can be used to, for example, tie a payment to a bill, so it can be recognised as being in payment of an electricity bill. Another example would be to use it to carry an invoice number alongside a payment in settlement of a B2B liability. Or it might describe the purpose of a payment, such as “Tuition for Q3 2025”, “Salary June 2025”, or “Loan repayment”.
+
+Where this metadata is intended to be used for payment automation, this "meaning" is defined by the scheme operator and the participating DFSPs, not the Mojaloop Hub. Automation would commonly be implemented as part of the [Core Connector customisation in the participation tools](./connectivity.md).
+
+## Applicability
+
+This version of this document relates to Mojaloop Version [17.0.0](https://github.com/mojaloop/helm/releases/tag/v17.0.0)
+
+## Document History
+  |Version|Date|Author|Detail|
+|:--------------:|:--------------:|:--------------:|:--------------:|
+|1.0|16th July 2025| Paul Makin|First version.|

docs/product/features/ml-feature-list.md

@@ -2,9 +2,7 @@
 
 Mojaloop is open source instant payments software that interconnects
 disparate financial institutions in a manner that promotes financial
-inclusion and provides robust risk management for all participants. It
-is available for use by any body that wishes to use it to implement and
-operate an inclusive instant payments scheme.
+inclusion and provides robust risk management for all participants. It is available for use by any body that wishes to use it to implement and operate an inclusive instant payments scheme.
 
 ## Mojaloop's Core Functions
 
@@ -35,10 +33,21 @@ together make Mojaloop a low cost, inclusive instant payments system:
  
 
 ## The Mojaloop Ecosystem
+### The Core
 In reading this document, it is important to understand the terminology used to identify the various actors, and how they interact. The following diagram provides a high level view of the Mojaloop ecosystem.
 
 ![Mojaloop Ecosystem](./ecosystem.svg)
 
+### Overlay Services
+Around the core illustrated in the above diagram there are a set of overlay services, which also form part of the complete Mojaloop open source package. These are:
+- The **Account Lookup Service** (ALS), and a number of oracles that are used by the ALS in alias resolution;
+- A set of **portals**, built to use the Business Operations Framework, which allow a hub operator to interact with/manage the Mojaloop Hub;
+- A **Merchant Payments** module, which supports merchant registration and the issuing of merchant IDs, including the generation of QR Codes which can be scanned to initiate a merchant transaction;
+- The **Testing Toolkit** (TTK), which allows engineers to simulate any aspect of the Mojaloop core ecosystem, to facilitate their development, integration and testing efforts;
+- An **Integration Toolkit** (ITK), part of the [connectivity support](./connectivity.md) library, which facilitates the connection between a DFSP and a Mojaloop Hub;
+- **ISO 8583 integration**, which allows ATMs (or an ATM switch) to be integrated with a Mojaloop Hub, for cash withdrawals;
+- [**MOSIP integration**](https://www.mosip.io), which allow payments to be routed to a MOSIP-based digital identity, rather than (say) a mobile phone number.
+
 ## Feature List
 
 This document presents a feature list which covers the following aspects

docs/product/features/tariffs.md

@@ -1,9 +1,53 @@
 # Fees and Tariffs
-This section describes the mechanisms that Mojaloop provides to support a range of different tariff models and the opportunities for participants and hub operators to levy fees. 
+Mojaloop supports transaction fees using a flexible rules-driven architecture designed to ensure transparency and agreement at every stage of a payment.
 
-To be completed.
+##  **Agreement of Terms – Fee Negotiation**
+
+Before a transaction occurs, Mojaloop uses its **Agreement of Terms** transaction phase to allow DFSPs to calculate  and agree all associated fees and commissions. 
+
+At the beginning of this phase, the Payer's DFSP proposes the transaction to the Payee's DFSP, including a choice of charging model, being that either fees are added to the amount the sender pays, or they are deducted from the amount the beneficiary receives.
+
+If the Payer's DFSP wishes to proceed, then they submit a confirmation. In this, the Payee's DFSP submits their fees (and other conditions) to the Payer's DFSP in the form of a contract, including either an acceptance of the chosen charging model, or a rejection.
+
+If the Payer DFSP wishes to proceed on the terms presented by the Payee DFSP, then it presents the terms of the transfer to the Payer, including the total to be paid by the Payer based on the selected charging model. 
+
+| Charging Model | Payer Pays| Payee Receives |
+| -------------- | ---------------------- | -------------------- |
+| Sender Pays | Value + Payer DFSP Fee + Payee DFSP Fee |Value|
+| Beneficiary Pays| Value + Payer DFSP Fee|Value - Payee DFSP Fee|
+
+
+If the Payer accepts the terms and wishes to proceed, the agreed transfer value is debited from the Payer's account by the Payer's DFSP, which then retains their own fees and submits a transfer request for the remaining value, together with the Payee's contract, to the Mojaloop Hub.
+
+The Payee DFSP, on completion of the transfer, retains their agreed fees, and credits the Payee's account with the remainder.
+
+In this way, all of the fees are consolidated into a single quote so the payer knows the exact cost before proceeding - including whether the Payee DFSP's fees are paid by the Payer or the Payee. 
+
+##  **Rules Handler – Interchange Fees**
+
+Mojaloop supports advanced fee rules like **interchange fees** via its Rules Handler, which evaluates transactions in-flight. For example, in a wallet-to-wallet peer‑to‑peer payment involving different DFSPs, Mojaloop can automatically apply a 0.6% fee charged by the Payee DFSP to the Payer DFSP. These are recorded as ledger entries and settled later.
+
+## **Hub Fees (Operator Fees)**
+
+Beyond per-transaction charges, hub operators may impose additional infrastructure–use or subscription fees on participating DFSPs. These “hub fees” are typically minimal — just enough to cover operational costs — with the aim of keeping end-user fees as low as possible in a “cost‑recovery plus" model. 
+
+---
+
+### In Summary
+
+| Fee Type                | Handled By             | When & How                                    |
+| ----------------------- | ---------------------- | --------------------------------------------- |
+| Transaction Fees        | Agreement of Terms Service        | Quoted up front, agreed before execution      |
+| Interchange Fees        | Rules Handler + Ledger | Applied during processing based on rules      |
+| Hub Infrastructure Fees | Hub Operator           | Charged separately to recover operating costs |
+
+This layered approach gives Mojaloop strong support for fee transparency, configurability, automation, and settlement consistency—crucial for interoperable and cost-effective financial inclusion systems.
+
+## Applicability
+
+This version of this document relates to Mojaloop Version [17.0.0](https://github.com/mojaloop/helm/releases/tag/v17.0.0)
 
 ## Document History
   |Version|Date|Author|Detail|
 |:--------------:|:--------------:|:--------------:|:--------------:|
-|1.0|3rd June 2025| Paul Makin|Initial version|
+|1.0|17th July 2025| Paul Makin|Initial version|

docs/product/features/use-cases.md

@@ -1,21 +1,21 @@
 
 # Use Cases
 
-A Mojaloop Hub's core function is the clearing of the transfer of funds between two accounts, each of which is held at a DFSP connected to the Hub, commonly referred to as a push payment. This enables it to support a wide range of use cases.
+A Mojaloop Hub's core function is the clearing of the transfer of funds between two accounts, each of which is held at a DFSP connected to the Hub, commonly referred to as a push payment. This enables it to support a wide range of use cases. However this is not the only transfer type that Mojaloop supports.
 
-This description of the use cases supported by Mojaloop is grouped according to the underlying protocol types, in order to demonstrate the extensible nature of a Mojaloop Hub. So we have:
+The following description of the use cases supported by Mojaloop is grouped according to the underlying protocol types, in order to demonstrate the extensible nature of a Mojaloop Hub. So we have:
 - **Push payments**, which supports the core use cases of P2P, B2B, etc;
 - **Request To Pay**, which supports some types of merchant payments, e-commerce and collections;
 - A range of **cash services**, including CICO and offline;
 - **PISP/3PPI protocols**, which allow fintechs and others to develop services such as merchant payments, small-scale salary runs, collections etc;
 - **Bulk payments**, to support nation-scale social payments and salaries;
 - **Cross-Border payments**, including both remittances and merchant payments.
 
-These are described in more detail below.
+These are described in more detail below. When reading these descriptions, it should be remembered that many of these transaction types [support the transport of metadata along with the payment itself](./metadata.md).
 
 (For an API-led view of use cases, please refer to the [use cases section of the Mojaloop API documentation](https://docs.mojaloop.io/api/fspiop/use-cases.html#table-1))
-## Core Use Cases
-This means that, at the most basic level, a Mojaloop Hub directly supports the following use cases:
+## "Push Payment" Use Cases
+A Mojaloop Hub directly supports the following use cases, which are all "flavours" of push payments:
 - Person to Person (**P2P**);
 - Person to Business (**P2B**), including simple forms of merchant payments, both face to face and remote (online);
 - Business to Business (**B2B**);
@@ -24,7 +24,7 @@ This means that, at the most basic level, a Mojaloop Hub directly supports the f
 
 In all types of merchant payment, a payment can be facilitated using merchant IDs (for USSD) or QR codes (smartphones).
 
-## Request To Pay
+## "Request To Pay" Use Cases
 
 As well as push payments, Mojaloop supports Request To Pay (RTP) transactions, in which a payee requests a payment from a payer, and _when the payer consents_ their DFSP pushes the payment to the payee on their behalf. This supports the following use cases:
 
@@ -33,34 +33,32 @@ As well as push payments, Mojaloop supports Request To Pay (RTP) transactions, i
     - In all types of face to face merchant payment, a payment can be facilitated using merchant IDs (for USSD) or QR codes (smartphones).
 - **e-Commerce**, sometimes also known as remote merchant payments, when for example a checkout page (web page or mobile app) would include a "pay from my bank account" button, which would trigger an RTP. 
 
-- **Collections**, including P2G, P2B, B2B and B2G - though this can also be achieved through the fintech/3PPI interface described below. 
+- **Collections**, including P2G, P2B, B2B and B2G. This would commonly used for the payment of utility bills. This can also be achieved through the fintech/3PPI interface described below - the decision is a matter for a scheme operator. 
 
 ## Cash Services
 A Mojaloop Hub directly supports the common interoperable cash in/out transactions that every DFSP (and their customers) would expect:
-- **Cardless ATM**;
-- **Cash In at off-us Agent**;
-- **Cash Out at off-us Agent**;
-- **Offline Cash**.
+- **Cardless ATM**, through integration with ATM networks, using the ISO 8583 protocol;
+- **Cash In / Cash Out (CICO) at off-us Agent**;
+- **Offline Cash**:
+	- A Mojaloop Hub is able to offer support to **offline cash** payment schemes because such a payment scheme is viewed as cash - albeit digital. So a withdrawal to an offline cash wallet (a load) is analogous to a "cash out" transaction; and a deposit from an offline cash wallet (an upload) is analogous to a "cash in" transaction. However, the operator of such a scheme might consider that all such wallet load/upload transactions, whether on-us or off-us, should be processed through the Mojaloop Hub, for ease of reconciliation by the offline scheme.
 
-A Mojaloop Hub is able to offer support to **offline cash** payment schemes because such a payment scheme is viewed as cash - albeit digital. So a withdrawal to an offline cash wallet (a load) is analogous to a "cash out" transaction; and a deposit from an offline cash wallet (an upload) is analogous to a "cash in" transaction. However, the operator of such a scheme might consider that all such wallet load/upload transactions, whether on-us or off-us, should be processed through the Mojaloop Hub, for ease of reconciliation by the offline scheme.
-
-## Fintechs and Others
+## "3PPI" Use Cases - Fintechs and Others
 A Mojaloop Hub directly supports Third Party Payment Initiation (3PPI), so that Payment Initiation Service Providers (PISPs) - better known as fintechs - can, using their own smartphone apps, recruit customers, and offer them a unified or enhanced payments service. Most DFSPs connected to a Mojaloop Hub can support 3PPI services, if they have a reasonably modern back office.
 
 A fintech can use the 3PPI service to initiate a Request To Pay (RTP) - asking their customer's DFSP to initiate a payment to a payee. This supports the following use cases:
 -	**Collections**, in particular P2G and P2B;
 -	**Salary payments**, essentially the processing of a bulk payments list, on behalf of small/medium businesses; 
 -	**Merchant payments** (P2B), using a QR code for initiation.
 
-## Bulk Payments
+## "Bulk Payment" Use Cases
 Every payments service needs to facilitate bulk payments, and Mojaloop offers this service using an extremely efficient model. All but the very smallest DFSPs are able to offer this service to their customers, allowing them to submit payments lists that can reach every customer of every connected DFSP. This is in support of:
 - **Pensions, Social and other payments** (G2P);
 - **Salaries** (G2P and B2P).
 
 In addition, the bulk payment functionality is available through the **3PPI service** (above), which would enable all DFSPs - even the very smallest - to offer a smaller scale bulk payments service through either a fintech, or directly through their own 3PPI service.
 
 
-## Cross Border Payments
+## "Cross Border" Use Cases
 
 A Mojaloop Hub can enable a DFSP's customers to send money across borders in a cost-effective manner, facilitating the foreign exchange (FX) process as part of the transaction. This supports the following use cases:
 - **P2P** and **P2B** (sending money to friend and family in another country, or paying a bill in another country);
@@ -72,16 +70,20 @@ In order to explore the aspects of the Mojaloop ecosystem that enable this, it i
 2. The support for foreign exchange providers (FXPs) to connect to a Mojaloop Hub and offer FX services. Neither the payer not the payee needs to define the currency to be used for a transaction; they each transact in their own currency, and the Mojaloop Hub(s) facilitate the interchange. This capability <a href="https://./ForeignExchange.html" style="color: ox 00A3FF;">is introduced here</a>.
 
 3. How the interconnection/interscheme and foreign exchange capabilities are brought together to support <a href="https://./CrossBorder.html" style="color: ox 00A3FF;">cross border transactions</a>.
+## Others; Card Payments
+Many potential adopters ask about the possibility of using Mojaloop to switch card transactions. The answer is that, from a technical perspective, it is perfectly possible to switch a card transaction; the card Personal Account Number (PAN) can be used as an alias to initiate an RTP transaction, particularly as the Bank Identification Number (BIN), which forms part of the PAN, identifies the DFSP that holds the customer's account, to which the RTP should be routed.
+
+However, the practicality is that the card Point of Sale (PoS) device would need to be updated to route transactions accordingly; domestic transactions via an RTP to the Mojaloop switch, the rest to the issuing card network. And those PoS devices often belong to the acquiring banks, who may be unlikely to grant access (larger retailers, who often own their, usually integrated, PoS devices, might be more amenable).
+
+Further, re-routing transactions initiated using a card bearing the logo of an international payment scheme would be wholly inappropriate, and would almost certainly place everyone involved in a precarious legal position. Consequently this is something that should only ever be considered when a domestic card scheme is used, and the owner of that scheme is willing for their cards to be used in this way.
+
+Finally, using such an approach for debit cards is a closer match to a Mojaloop RTP transaction; using it for a credit card, which might include placing a funds reservation on an account (when checking into a hotel, for example), would add further complexity.
 
 ## Extended Use Cases
 
-In addition to these standard use cases, Mojaloop supports the implementation
-of more complex use cases by adopters, which add additional features and
-are layered over the top of the standard use cases.
+In addition to these standard use cases, Mojaloop supports the implementation of more complex use cases by adopters, which add additional features and are layered over the top of the standard use cases.
 
-These
-scheme-specific use cases can readily be added by individual scheme
-operators.
+These scheme-specific use cases can readily be added by individual scheme operators.
 
 ## Applicability
 
@@ -90,6 +92,7 @@ This version of this document relates to Mojaloop Version [17.0.0](https://githu
 ## Document History
   |Version|Date|Author|Detail|
 |:--------------:|:--------------:|:--------------:|:--------------:|
+|1.5|16th July 2025| Paul Makin|Changed the sub-headings to reflect how the introductory text talks about use cases. Refined the descriptions. Added a link to a metadata description. Added a note about card transactions.|
 |1.4|12th June 2025| Paul Makin|Extended the introductory text to explain the use case grouping.|
 |1.3|10th June 2025| Paul Makin|Added a description of e-commerce payments using RTP. Retitled 3PPI payments as Fintech payments.Clarified bulk payment initiation via 3PPI. Finally, some cosmetic updates to highlight hyperlinks to other documents.|
 |1.2|14th April 2025| Paul Makin|Updates related to the release of V17, including links to the interscheme and FX documentation.|