nips/89.md

NIP-89

payto: Payment Targets

draft optional author:atxmj

This NIP standardizes the approach to payment and tip invocations from user profiles, posts, chats, and elsewhere using the RFC-8905 (payto:) URI scheme standard for "payment targets".

payto: event broadcasting

Clients may allow users to specify a list (one or many) of "payment targets" as specified in the RFC-8905 (payto:) URI scheme standard, each consisting of a pair of values, payment_target_type and authority (to be labeled as preferred by the client), in order to generate an event of kind 0 (set_metadata) specifying "payment targets" that may be used for payment or tip invocation from a user's profile, posts, chats, or elsewhere.

The client may allow the user to input and perform validation on the payment_target_type and authority fields (labeled as preferred by the client) as they see fit.

Example of broadcasting a "payto" event

The client allows the user to add multiple pairs of "payment network" and "address" values to a list of "payment options" in their profile.

The client performs validation on the inputs and warns the user that the "payment network" for the third "payment option" with value unknowntype is not recognized, but allows them to submit it regardless.

The client then broadcasts an event such as

{
  "pubkey": "afc93622eb4d79c0fb75e56e0c14553f7214b0a466abeba14cb38968c6755e6a",
  "kind": 0,
  "content": "{\"payto\": [{\"payment_target_type\": \"bitcoin\", \"authority\": \"bc1qxq66e0t8d7ugdecwnmv58e90tpry23nc84pg9k\"}, {\"payment_target_type\": \"nano\", \"authority\": \"nano_1dctqbmqxfppo9pswbm6kg9d4s4mbraqn8i4m7ob9gnzz91aurmuho48jx3c\"}, {\"payment_target_type\": \"unknowntype\", \"authority\": \"l7tbta5b9xze6ckkfc99uohzxd009b0r\"}]}"
  ...
}

Example of steps taken by the client on input

• allow the user to specify a list of payment_target_type and authority value pairs (labeled as preferred by the client) of their choice
• for each pair of payment_target_type and authority values specified by the user
  • optionally do some minimal validation on those fields in a generalized way that applies to any payment network
  • optionally warn users if a specifid payment_target_type is not recognized by the client
• broadcast the event in the format specified above

Recommended Payment Target Types

This is a list of recommended payment target types for clients to recognize and store icons and stylization configurations for.

Payment Target Type	Long Stylization	Short Stylization	Symbol	References
bitcoin	Bitcoin	BTC	₿	https://bitcoin.design/
lightning	Lightning Network	LBTC	—	https://github.com/shocknet/bitcoin-lightning-logo
cashme	Cash App	Cash App	–	https://cash.app/press
nano	Nano	XNO	Ӿ	https://nano.org/en/currency

payto: event observation

On observation of events of kind 0 (set_metadata), the event may specify the key "payto" with a value consisting of a list (one or many) of "payment target" values, each specified as a pair of values payment_target_type and authority as specified in the RFC-8905 (payto:) URI scheme for payment targets.

For each pair of values in the payto list, the client should assemble a full payto:// deep link URI and render it as a button or link in the user's profile, posts, chats, or elsewhere, in the format of payto://<payment_target_type>/<authority>.

The client should store a map of recognized payment target types along with a corresponding icon & stylization configuration (to be defined by the client).

For recognized payment_target_type values, the client should render a button or link using the associated icon & stylization.

For unrecognized payment_target_type values, the client may chose to either ignore them or use a generic stylization, perhaps using the payment_target_type value directly for the button or link.

If a user has specified multiple payment targets, the client may choose to render only the first one, render multiple buttons or links, or render a dropdown to select the payment target of choice.

Example of observing a "payto" event

If a client sees an event like this:

{
  "pubkey": "afc93622eb4d79c0fb75e56e0c14553f7214b0a466abeba14cb38968c6755e6a",
  "kind": 0,
  "content": "{\"payto\": [{\"payment_target_type\": \"bitcoin\", \"authority\": \"bc1qxq66e0t8d7ugdecwnmv58e90tpry23nc84pg9k\"}, {\"payment_target_type\": \"nano\", \"authority\": \"nano_1dctqbmqxfppo9pswbm6kg9d4s4mbraqn8i4m7ob9gnzz91aurmuho48jx3c\"}, {\"payment_target_type\": \"unknowntype\", \"authority\": \"l7tbta5b9xze6ckkfc99uohzxd009b0r\"}]}"
  ...
}

for each payment target it will assemble a deep link payment invocation URI, as

payto://bitcoin/bc1qxq66e0t8d7ugdecwnmv58e90tpry23nc84pg9k (recognized) payto://nano/nano_1dctqbmqxfppo9pswbm6kg9d4s4mbraqn8i4m7ob9gnzz91aurmuho48jx3c (recognized) payto://unknowntype/l7tbta5b9xze6ckkfc99uohzxd009b0r (unrecognized)

The client chooses to ignore the third unrecognized payment_target_type, and only embeds the first two payment target deep links in the user's profile, posts, chats, or elsewhere as buttons, links, or a dropdown selector using the corresponding icons & stylizations for the recognized payment target types.

Optionally, the client may have chosen to render the third payment target using the text unknowntype rather than ignoring it.

Example of steps taken by the client on observation

• for each pair of payment_target_type and authority values in the payto list
  • optionally do some minimal validation on those fields in a generalized way that applies to any payment network, and filter out invalid pairs
  • optionally filter out any pairs with an unrecognized payment_target_type
  • assemble a full payto:// deep link URI in the format payto://<payment_target_type>/<authority>
  • render a button, link, or dropdown in user profiles, posts, chats, and elsewhere using the assembled deep links and the corresponding icons & stylization configurations for recognized payment_target_type values