nips/89.md

NIP-89

payto: Payment Targets

draft optional author:atxmj

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\"}]}"
  ...
}

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 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 and/or 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 and/or 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 or stylizations for the recognized payment target types.