search

mojaloop / mojaloop-specification

This repo contains the specification document set of the Open API for FSP Interoperability
https://docs.mojaloop.io/api
Other
20 stars 40 forks source link

[cross-currency] - Allow for discovery of payee currencies and routing by address #19

Open adrianhopebailie opened 5 years ago

adrianhopebailie commented 5 years ago

The current API defines a flow for discovery of the payee and payee details using a combination of the /parties and /participants API.

Ultimately this results in the sending DFSP getting a Party response which provides details of the payee. It is anticipated that the sending DFSP will use this information (such as Party.name) to render appropriate options to the sender for making a payment.

It is not currently possible to determine the currency of the payee's account from the Party data model.

Page 80 of the API specification suggests that the API support a query string for the purposes of filtering:

This HTTP request should support a query string (see Section 3.1.3 for more information regarding URI syntax) for filtering of currency. To use filtering of currency, the HTTP request GET /participants//?currency=XYZ should be used, where XYZ is the requested currency.

However this only allows the sender to filter out payees that would require a cross-currency transfer, it doesn't allow the sender to determine the currency of the payee's account if the sender is willing to make a cross-currency transfer.

Privacy

The design of a mechanism for the discovery of accounts, and routing of quotes and payments to those accounts, needs to be done in a privacy preserving manner. It should not be possible during the lookup flow for a sender to discover more information about the receiver than the receiver is prepared to share or than is needed to make the payment.

If the payee has multiple accounts in different currencies that it can receive payments into then these should be indexed in the lookup using opaque identifiers.

Proposal

The following updates to the API would facilitate cross-currency quotes and transfers and the necessary lookups to facilitate these.

Update Party

The Party data model should be updated to include a new addresses data element: (Some existing properties excluded to save space)

Data Element Cardinality Type Description
partyIdInfo 1 PartyIdInfo Party Id type, id, sub ID or type, and FSP Id
name 0..1 PartyName Display name of the Party, could be a real name or a nickname
addresses 0..1 AddressList A list of addresses that can be used to route payments to the party

Add AddressList and Address data types

The AddressList data model is defined as:

Data Element Cardinality Type Description
address 1..16 Address Number of address elements

The Address data model is defined as:

Data Element Cardinality Type Description
address 0..1 Address An address of the payee
currency 1 Currency The currency of the account

The Address data type is a variable length string with a maximum size of 1023 characters and consists of:

An entity providing accounts to parties (i.e. a participant) can provide any value for an Address that is routable to that entity. It does not need to provide an address that makes the account identifiable outside the entity's domain. i.e. This is an address not an identifier

For example, a participant (Blue DFSP) that controls the address space moja.blue might allocate a random UUID to the account and return the value:

{
  "address" : "moja.blue.8f027046-b82a-4fa9-838b-70210fcf8137",
  "currency" : "ZAR" 
}

This address is routable to Blue DFSP because it uses the prefix moja.blue

Blue DFSP may also simply use their own address if that is sufficient (in combination with the remainder of the PartyIdInfo) to uniquely identify the payee and the destination account.

{
  "address" : "moja.blue",
  "currency" : "ZAR" 
}

This address is also routable to Blue DFSP because it uses the prefix moja.blue

IMPORTANT: The policy for defining addresses and the life-cycle of these is at the discretion of the address space owner (the payee DFSP in this case)

Use the address in the Party.PartyIdInfo.PartySubIdOrType to assist in routing

If a sending DFSP has an address for the payee that they wish to include in a quote request to assist intermediaries in routing the quote they should include this in the Party.PartyIdInfo.PartySubIdOrType data element.

Intermediaries that need to route a quote request via FX providers or Cross-network providers/gateways will determine the next hop of the quote request by consulting their internal routing tables using the address as the lookup value.

henrka commented 5 years ago

I do not like using the element name address for addressing an account, as an address generally is used to determine where someone lives or an organization is situated. For example accountAddress or (or possibly paymentAddress if the addresses are short lived) would make much more sense to me.

Also, to me it seems more logical to use for example AccountList instead of AddressList in the Party type, as currency is the mandatory element in the Address type in the suggestion above:

Data Element Cardinality Type Description
partyIdInfo 1 PartyIdInfo Party Id type, id, sub ID or type, and FSP Id
name 0..1 PartyName Display name of the Party, could be a real name or a nickname
accounts 0..1 AccountList A list of accounts that the Party has in different currencies together with an optional AccountAddress for routing purposes

AccountList

Data Element Cardinality Type Description
account 1..32 Account Number of Account elements

Account

Data Element Cardinality Type Description
currency 1 Currency The currency of the account
accountAddress 0..1 AccountAddress The address to this account
adrianhopebailie commented 5 years ago

@ehenrka good suggestions. I like your version of this proposal. Are there any other properties you think we should have on the Account object that would be useful to share such as limits?

henrka commented 5 years ago

Thanks @adrianhopebailie. Specific limits are usually very private. In some cases it is not even allowed to share that a limit has been breached, just that the transfer failed for some reason.

One thing that might be useful is some kind of a description of the account if an account holder has more than one account in the same currency.

mjbrichards commented 3 years ago

Can we pick this up from the aspect of currency definition? Whether or not we include address information (and, in PISP at least, we have now moved that to a separate API,) the Payer DFSP probably still needs to know what currency/ies the payee identifier can receive in. We are probably heading for FXP towards an architecture in which the Payer DFSP rather than the switch makes the decision on whether a transaction requires FX; but, in any case, the Payee DFSP will need to indicate what currency/ies their customer can receive in.

Could I propose something like the following?

Data Element Cardinality Type Description
partyIdInfo 1 PartyIdInfo Party Id type, id, sub ID or type, and FSP Id
name 0..1 PartyName Display name of the Party, could be a real name or a nickname
currencies 0..n Currency A list of currencies in which the Party can receive funds

Absence of this parameter would indicate that the Payee DFSP is happy to receive in the sending currency - for instance, in schemes which only support a single currency. In cases where a beneficiary can receive in more than one currency, it would be the responsibility of the Payer DFSP to decide which currency to specify for the beneficiary to receive, and to arrange for currency conversion if required.

millerabel commented 3 years ago

I’m not clear on how this would work.

Sender proposes 1,000 ideneros in a quotation request; payee DFSP answers with {USD, pesos, } but not ideneros. How is the payment condition formed around these open-ended details? The quotation response must be definitive and deterministic.

So the currencies {0..n} would have to be part of an error response, but not present in a successful response. We should be cautious about over-disclosure of account details in a quotation response, particularly in error cases… that could lead to perverse uses of the API (like harvesting and caching).

That would mean, Sender proposes ideneros, payee DFSP says, “no, but I’ll accept USD or pesos for this alias.” Payer participant then reformulates the request, at the direction of the sender and if the sender is willing. Quotation response then succeeds, includes the now single proposed currency, and a payment condition is attached.

A broader alternative is to provide multiple quotations in a single response, each with a single currency, and each with its own payment condition. It’s then up to the sender to pick one and approve a transfer, or to abandon the request.

— Miller

Miller Abel | Kohala Ranch Lot 695 | m: +1 425.443.3970 <tel:+1.425.443.3970>

On Mar 9, 2021, at 3:57 AM, mjbrichards notifications@github.com wrote:

Can we pick this up from the aspect of currency definition? Whether or not we include address information (and, in PISP at least, we have now moved that to a separate API,) the Payer DFSP probably still needs to know what currency/ies the payee identifier can receive in. We are probably heading for FXP towards an architecture in which the Payer DFSP rather than the switch makes the decision on whether a transaction requires FX; but, in any case, the Payee DFSP will need to indicate what currency/ies their customer can receive in.

Could I propose something like the following?

Data Element Cardinality Type Description partyIdInfo 1 PartyIdInfo Party Id type, id, sub ID or type, and FSP Id name 0..1 PartyName Display name of the Party, could be a real name or a nickname currencies 0..n Currency A list of currencies in which the Party can receive funds Absence of this parameter would indicate that the Payee DFSP is happy to receive in the sending currency - for instance, in schemes which only support a single currency. In cases where a beneficiary can receive in more than one currency, it would be the responsibility of the Payer DFSP to decide which currency to specify for the beneficiary to receive, and to arrange for currency conversion if required.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/mojaloop/mojaloop-specification/issues/19#issuecomment-793780310, or unsubscribe https://github.com/notifications/unsubscribe-auth/AB6OJ6HSIWIYV7XADVFEVHLTCYEI5ANCNFSM4H3XJDEA.

mjbrichards commented 3 years ago

The plan is that this information should be included as part of the response to a GET /parties request. So the Payer DFSP says, "Tell me about MSISDN 123456", and one of the things the payee DFSP responds with is "This person can receive funds in USD or pesos." Now, if the payer account is in ideneros, it's up to the Payer DFSP to say to the customer "sorry, can't send," or to figure out how to get the currency converted (for instance, by identifying an FXP and including them in the quote request, or by doing the FX conversion themselves and charging the customer for it.) But in any case, it happens before the Payer DFSP issues the quote request, which can therefore remain determinate, as we need it to be.

henrka commented 3 years ago

I'm fine with just having a list of the currencies that is supported by the Party (account holder), if the earlier discussed AccountAddress is no longer needed.

mjbrichards commented 3 years ago

For the moment, that information is dealt with via the PISP. I believe that there is no outstanding requirement for an equivalent change in the FSPIOP API