diff --git a/umad-05-payreq-request.md b/umad-05-payreq-request.md index b216afb..5e42088 100644 --- a/umad-05-payreq-request.md +++ b/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: diff --git a/umad-06-payreq-response.md b/umad-06-payreq-response.md index 8a9e671..f73e602 100644 --- a/umad-06-payreq-response.md +++ b/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.