Merge pull request #17 from uma-universal-money-address/feat/payeedata

Add LUD-22 Payee Data to the v1.0 spec.

umad-05-payreq-request.md

@@ -28,10 +28,39 @@ The body of the request is a JSON object with the following fields:
   // LNURLP response.
   "currency": string,
   // The UMA protocol version that will be used for this transaction. See [UMAD-08](/umad-08-versioning.md).
-  "umaVersion": "1.0"
+  "umaVersion": "1.0",
+  "payeeData":  {
+    "name": { "mandatory": boolean },
+    "identifier": { "mandatory": boolean },
+    "countryCode": { "mandatory": boolean },
+    ... All fields optional and more fields may be negotiated. See [LUD-22](https://github.com/lnurl/luds/pull/252)
+  },
 }
 ```
 
+## Payee Data
+
+The `payeeData` field is optional and is used to request additional information about the receiving user. The `mandatory`
+field in each subfield indicates whether the receiving VASP is required to provide that information to proceed with the transaction.
+See [LUD-22](https://github.com/lnurl/luds/pull/252) for more details. Note that the receiving VASP may choose to avoid sending
+any payee identity information for privacy reasons, which may cause the payment to fail if the sending VASP requires it.
+For that reason, the sender SHOULD NOT require any payee identity information to be sent by the receiver unless it is
+absolutely necessary.
+
+### Common Payee Data Fields
+
+The following is a non-exhaustive list of common payee data fields that *may* be requested by the sender:
+
+- `name`: The full name of the receiving user.
+- `identifier`: The canonical receiving UMA address of the receiver.
+- `countryCode`: The ISO 3166-1 alpha-2 country code of the receiving user.
+- `email`: The email address of the receiving user.
+- `accountNumber`: The account number of the receiving user at the receiving VASP.
+
+Note that this struct is extensible, so any field can be added as long as it is agreed upon by both VASPs.
+
+## Payer Data
+
 The `payerData` field is a JSON object that contains information about the payer as described in
 [LUD-18](https://github.com/lnurl/luds/blob/luds/18.md). There's also an UMA-specific payerdata field - `compliance`.
 Its structure is:

umad-06-payreq-response.md

@@ -36,6 +36,12 @@ The full structure of the LNURLP response is:
     // This is separate from the multiplier rate.
     "exchangeFeesMillisatoshi": number
   },
+  "payeeData": {
+    "name": string,
+    "identifier": string,
+    "countryCode": string,
+    ...other fields may be included if supported by receiver and requested by sender
+  },
   "umaVersion": "1.0",
 }
 ```
@@ -47,3 +53,11 @@ a hard cap on the conversion rate validity.
 As described in [UMAD-05](/umad-05-payreq-request.md), the `nodePubKey` and `utxos` fields are used for pre-screening
 by the sending VASP. The `utxoCallback` field is used by the receiving VASP to notify the sending VASP of the utxos
 used to complete the transaction. See [UMAD-07](/umad-07-post-tx-hooks.md) for details.
+
+Each key in the `payeeData` JSON object should correspond to a requested `payeeData` field from the `payeeData` record
+received from the sender in the payreq request. The receiving VASP can send any of the payee id kinds if they are listed
+in the `payeeData` record. But if any is marked as `"mandatory": true` then receiver MUST send them or otherwise
+not proceed with the payment flow. The receiving VASP SHOULD NOT send payee identity types omitted in payeeData record,
+none at all if the record is not present. Note that LUD-22 can be used in conjunction with LUD-18 to allow the payer to
+request that the payee provide identitifying information (which can be optionally verified by SERVICE) before sharing
+payee identity information.