RFC 8905

The 'payto' URI Scheme for Payments

📅 published October 2020, from ietf

The 'payto' URI Scheme for Payments 💸

Okay bestie, paperwork first 📋✨ This is RFC 8905, The 'payto' URI Scheme for Payments. It's an Independent Submission, so it's not an IETF stream document, and it's Informational 🦋. It was written by F. Dold (Taler Systems SA) and C. Grothoff (Bern University of Applied Sciences), dated October 2020, with ISSN 2070-1721. The title block doesn't list anything it obsoletes or updates.

Abstract 🌸

So the big idea is that this doc defines the payto URI scheme for pointing at payment targets 💖 One unified scheme for every payment target type means apps can offer the same kind of user interaction with these URIs, which makes it way easier to bring in new payment systems and apps. It's giving standardization queen energy 👑

Status of This Memo 📝

This one is not an Internet Standards Track spec. It's published for informational purposes 🧁

This is a contribution to the RFC Series, independent of any other RFC stream. The RFC Editor chose to publish it at their discretion, and they make no statement about how valuable it is for implementation or deployment. Docs approved by the RFC Editor aren't candidates for any level of Internet Standard. See Section 2 of RFC 7841 for more on that 🌈

Info about the current status, errata, and how to give feedback lives at https://www.rfc-editor.org/info/rfc8905 🔗

Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved 💜

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the publication date. Please read them carefully, because they spell out your rights and restrictions for this document 📜

Table of Contents 🗺️

1.  Introduction
  1.1.  Objective
  1.2.  Requirements Language
2.  Syntax of a 'payto' URI
3.  Semantics
4.  Examples
5.  Generic Options
6.  Internationalization and Character Encoding
7.  Tracking Payment Target Types
  7.1.  ACH Bank Account
  7.2.  Business Identifier Code
  7.3.  International Bank Account Number
  7.4.  Unified Payments Interface
  7.5.  Bitcoin Address
  7.6.  Interledger Protocol Address
  7.7.  Void Payment Target
8.  Security Considerations
9.  IANA Considerations
10. Payto Payment Target Types
11. References
  11.1.  Normative References
  11.2.  Informative References
Authors' Addresses

1. Introduction ✨

This doc defines the 'payto' Uniform Resource Identifier (URI) [RFC3986] scheme for designating transfer form data for payments 💅

1.1. Objective 🎯

A 'payto' URI always identifies the target of a payment 💖 It's made up of a payment target type, a target identifier, and optional parameters like an amount or a payment reference.

The target identifier's meaning is defined by the payment target type, and it usually represents either a bank account or an (unsettled) transaction 🏦

Same vibe as before: one unified scheme for all payment target types lets apps offer user interactions with these URIs, which makes it easier to introduce new payment systems and apps 🦋

1.2. Requirements Language 📜

Here are the key words: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL". They're interpreted as described in BCP 14 [RFC2119] [RFC8174], but only when they show up in all capitals, exactly like that 🙈

2. Syntax of a 'payto' URI 🧩

This doc uses the Augmented Backus-Naur Form (ABNF) of [RFC5234] 🤓

  payto-URI = "payto://" authority path-abempty [ "?" opts ]
  opts = opt *( "&" opt )
  opt-name = generic-opt / authority-specific-opt
  opt-value = *pchar
  opt = opt-name "=" opt-value
  generic-opt = "amount" / "receiver-name" / "sender-name" /
                "message" / "instruction"
  authority-specific-opt = ALPHA *( ALPHA / DIGIT / "-" / "." )
  authority = ALPHA *( ALPHA / DIGIT / "-" / "." )

path-abempty is defined in Section 3.3 of [RFC3986]. pchar is defined in Appendix A of [RFC3986] 📚

3. Semantics 🧠

The authority component of a payment URI identifies the payment target type 🎀 The payment target types are defined in the "Payto Payment Target Types" registry (see Section 10). The path component identifies the target for a payment, as interpreted by that payment target type. The query component can give extra parameters for a payment.

Every payment target type SHOULD accept the options defined in generic-opt.

The default operation of applications that invoke a URI with the 'payto' scheme MUST be to launch an application (if available) associated with the payment target type that can initiate a payment. ✨

If multiple handlers are registered for the same payment target type, the user SHOULD be able to choose which application to launch. This is so users with several bank accounts (each reached through that bank's own app) can pick which account to pay with 💸

An application SHOULD allow dereferencing a 'payto' URI even when that URI's payment target type isn't registered in the "Payto Payment Target Types" registry 🫶

Details of the payment MUST be taken from the path and options given in the URI. The user SHOULD be allowed to modify these details before confirming a payment 💅

4. Examples 🌈

Valid Example:

payto://iban/DE75512108001245126199?amount=EUR:200.0&message=hello

Invalid Example (authority missing):

payto:iban/12345

Look at that, the invalid one is missing its authority, so it's a no-go 💀

5. Generic Options 🍓

Applications MUST accept URIs with options in any order 🌸 The "amount" option MUST NOT occur more than once. Other options MAY be allowed multiple times, with further restrictions depending on the payment target type. The following options SHOULD be understood by every payment target type.

amount: The amount to transfer. The format MUST be:

amount = currency ":" unit [ "." fraction ]
currency = 1*ALPHA
unit = 1*(DIGIT / ",")
fraction = 1*(DIGIT / ",")

If a 3-letter currency is used, it MUST be an [ISO4217] alphabetic code. A payment target type MAY define semantics beyond ISO 4217 for currency codes that aren't 3 characters long. The unit value MUST be smaller than 2^53. If it's present, the fraction MUST consist of no more than 8 decimal digits. Using commas is optional for readability, and they MUST be ignored 🧮

receiver-name: Name of the entity that receives the payment (creditor). The value of this option MAY be subject to lossy conversion, modification, and truncation (for example, due to line wrapping or character set conversion) 💌

sender-name: Name of the entity that makes the payment (debtor). The value of this option MAY be subject to lossy conversion, modification, and truncation (for example, due to line wrapping or character set conversion) 🫠

message: A short message to identify the purpose of the payment. The value of this option MAY be subject to lossy conversion, modification, and truncation (for example, due to line wrapping or character set conversion) 💬

instruction: A short message giving payment reconciliation instructions to the recipient. An instruction that follows the character set and length limitation defined by the respective payment target type SHOULD NOT be subject to lossy conversion. This one's serious business 🔥

6. Internationalization and Character Encoding 🌍

Various payment systems use restricted character sets 🧸 An application that processes 'payto' URIs MUST convert characters that aren't allowed by the respective payment systems into allowable characters, using either an encoding or a replacement table. This conversion MAY be lossy, except for the instruction field. If the value of the instruction field would be subject to lossy conversion, modification, or truncation, the application SHOULD refuse further processing of the payment until a different instruction value is provided 🙅‍♀️

To avoid special encoding rules for the payment target identifier, the userinfo component [RFC3986] is disallowed in 'payto' URIs. Instead, the payment target identifier is given as an option, where the encoding rules are uniform for all options 🎯

Defining a generic way of tagging the language of option fields that contain natural language text (such as "receiver-name", "sender-name", and "message") is out of scope for this document, since internationalization has to accommodate the restrictions and requirements of the underlying banking system of the payment target type. The internationalization concerns SHOULD be individually defined by each payment target type 🌏

7. Tracking Payment Target Types 📋

There's a registry of "Payto Payment Target Types", described in Section 10. Its registration policy is "First Come First Served", as described in [RFC8126]. When requesting new entries, careful consideration of the following criteria is strongly advised 🫶

  1. The description clearly defines the syntax and semantics of the payment target and optional parameters, if applicable.
  2. Relevant references are provided, if they're available.
  3. The chosen name is appropriate for the payment target type, doesn't conflict with well-known payment systems, and avoids the potential to confuse users.
  4. The payment system underlying the payment target type isn't fundamentally incompatible with the general options (such as positive decimal amounts) in this specification.
  5. The payment target type isn't a vendor-specific version of a payment target type that could be described more generally by a vendor-neutral payment target type.
  6. The specification of the new payment target type stays within the scope of payment transfer form data. In particular, specifying complete invoices is out of scope. Neither are processing instructions to the payment processor or bank beyond a simple payment.
  7. The payment target and the options don't contain the payment sender's account details.

Docs that support requests for new registry entries should give the following info for each entry:

  • Name: The name of the payment target type (a case-insensitive ASCII string, restricted to alphanumeric characters, dots, and dashes).
  • Description: A description of the payment target type, including the semantics of the path in the URI if applicable.
  • Example: At least one example URI to illustrate the payment target type.
  • Contact: The contact information of a person to reach for further information.
  • References: Optionally, references describing the payment target type (such as an RFC) and target-specific options, or references describing the payment system underlying the payment target type.

This document populates the registry with seven entries as follows (see also Section 10) 🦋✨

7.1. ACH Bank Account 💸

  • Name: ach

ACH stands for Automated Clearing House 🏦. The path has two parts: the routing number and the account number. The handler's implementation decides how long option values can be and which characters they can use. Language tagging and internationalization of options are not supported 🙅‍♀️.

Example:

payto://ach/122000661/1234
  • Contact: N/A
  • References: [NACHA], RFC 8905

7.2. Business Identifier Code 🌸

  • Name: bic

BIC is the Business Identifier Code 🏛️. The path is just a BIC, and it's used for wire transfers between banks. The Society for Worldwide Interbank Financial Telecommunication (SWIFT) provides the registry for BICs. The path doesn't let you specify a bank account number, so no account digits here 🙅‍♀️. The handler's implementation decides the length and character set limits for option values. Language tagging and internationalization of options are not supported.

Example:

payto://bic/SOGEDEFFXXX
  • Contact: N/A
  • References: [BIC], RFC 8905

7.3. International Bank Account Number 🇪🇺

  • Name: iban

IBAN stands for International Bank Account Number 💳. Usually you can use the IBAN to figure out the matching BIC with a lookup in the right proprietary translation table, which is very neat ✨. But some legacy applications treat payments to the same IBAN differently depending on the BIC you give them 🙃. So the path can have either one component (the IBAN) or two components (the BIC followed by the IBAN).

The message option in a 'payto' URI matches the "unstructured remittance information" of SEPA credit transfers 📝. It's capped at 140 characters, and the allowed character set changes depending on the countries of the banks and payment processors involved.

The instruction option matches the "end-to-end identifier" of SEPA credit transfers 🔖. It's capped at 35 characters. Those can be alphanumeric or come from this special set: +?/-:().,'

Language tagging and internationalization of options are not supported.

Examples:

payto://iban/DE75512108001245126199
payto://iban/SOGEDEFFXXX/DE75512108001245126199
  • Contact: N/A
  • References: [ISO20022], RFC 8905

7.4. Unified Payments Interface 📲

  • Name: upi

UPI is the Unified Payment Interface 🇮🇳. The path is an account alias 🪪. The amount and receiver-name options are mandatory for this payment target, so don't skip them 🚨. The handler's implementation decides the length and character set limits for option values. Language tags and internationalization of options are not supported.

Example:

payto://upi/alice@example.com?receiver-name=Alice&amount=INR:200
  • Contact: N/A
  • References: [UPILinking], RFC 8905

7.5. Bitcoin Address ₿

  • Name: bitcoin

This one is for the Bitcoin protocol 🪙. The path is a "bitcoinaddress", as defined in [BIP0021]. The handler's implementation decides the length and character set limits for option values. Language tags and internationalization of options are not supported.

Example:

payto://bitcoin/12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu
  • Contact: N/A
  • References: [BIP0021], RFC 8905

7.6. Interledger Protocol Address 🌊

  • Name: ilp

ILP is the Interledger protocol 🌐. The path is an ILP address, as defined in [ILP-ADDR]. The handler's implementation decides the length and character set limits for option values. Language tagging and internationalization of options are not supported.

Example:

payto://ilp/g.acme.bob
  • Contact: N/A
  • References: [ILP-ADDR], RFC 8905

7.7. Void Payment Target 🫥

  • Name: void

The "void" payment target type lets you spell out the details of an out-of-band payment, like cash or other in-person transactions 🤝💵. The path is optional and gets read as a comment. The handler's implementation decides the length and character set limits for option values. Language tags and internationalization of options are not supported.

Example:

payto://void/?amount=EUR:10.5

8. Security Considerations 🛡️

Okay, this section is serious, bestie 😭🚨. Interactive applications that handle the 'payto' URI scheme MUST NOT initiate any financial transactions without prior review and confirmation from the user, and they MUST take measures to prevent clickjacking [HMW12]. No surprise payments, ever 💅.

Unless a 'payto' URI is received over a trusted, authenticated channel, a user might not be able to tell who the payment is going to. Homographs [unicode-tr36] make this even sketchier 👀. So a payment target type SHOULD NOT use human-readable names together with unicode in the target account specification. If it does, the user could think they're confirming the right account when they're really looking at a lookalike 💀.

The authentication, authorization, and transport security used to process a payment encoded in a 'payto' URI are handled by the application. They are not in scope for this document 🔐.

To avoid unnecessary data collection 🧹, payment target types SHOULD NOT include personally identifying information about the sender of a payment that the application doesn't need in order to make the payment 🙈.

9. IANA Considerations 📋

IANA maintains the "Uniform Resource Identifier (URI) Schemes" registry 🗂️, and that registry has an entry for the 'payto' URI scheme. IANA has updated that entry so it points to this document ✨.

Scheme name:  payto

Status:  provisional

URI scheme syntax:  See Section 2 of RFC 8905.

URI scheme semantics:  See Section 3 of RFC 8905.

Applications/protocols that use this scheme name:  payto URIs are
   mainly used by financial software.

Contact:  Christian Grothoff <grothoff@gnu.org>

Change controller:  Christian Grothoff <grothoff@gnu.org>

References:  See Section 11 of RFC 8905.

10. Payto Payment Target Types 🧾

This document lists a set of payment target types 💜. Future work might need to define more payment target types, so the list isn't closed. The GNUnet Assigned Numbers Authority (GANA) [GANA] runs the "Payto Payment Target Types" registry 👑. For each payment target type, the registry tracks:

  • Name: The name of the payment target type. It's a case-insensitive ASCII string, limited to alphanumeric characters, dots, and dashes.
  • Contact: Contact information for a person who can answer further questions.
  • References: Optionally, references that describe the payment target type (such as an RFC) and its target-specific options, or references that describe the payment system behind the payment target type.

The entries in the "Payto Payment Target Types" registry that this document defines are listed in Table 1 🌈.

                 +=========+=========+===========+
                 | Name    | Contact | Reference |
                 +=========+=========+===========+
                 | ach     | N/A     | RFC 8905  |
                 +---------+---------+-----------+
                 | bic     | N/A     | RFC 8905  |
                 +---------+---------+-----------+
                 | iban    | N/A     | RFC 8905  |
                 +---------+---------+-----------+
                 | upi     | N/A     | RFC 8905  |
                 +---------+---------+-----------+
                 | bitcoin | N/A     | RFC 8905  |
                 +---------+---------+-----------+
                 | ilp     | N/A     | RFC 8905  |
                 +---------+---------+-----------+
                 | void    | N/A     | RFC 8905  |
                 +---------+---------+-----------+

                              Table 1

11. References 📚

11.1. Normative References

[ISO20022] International Organization for Standardization, "Financial
           Services - Universal financial industry message scheme",
           ISO 20022, May 2013, <https://www.iso.org>.

[ISO4217]  International Organization for Standardization, "Codes for
           the representation of currencies", ISO 4217, August 2015,
           <https://www.iso.org>.

[NACHA]    Nacha, "2020 Nacha Operating Rules & Guidelines", 2019.

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <https://www.rfc-editor.org/info/rfc2119>.

[RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
           Resource Identifier (URI): Generic Syntax", STD 66,
           RFC 3986, DOI 10.17487/RFC3986, January 2005,
           <https://www.rfc-editor.org/info/rfc3986>.

[RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
           Specifications: ABNF", STD 68, RFC 5234,
           DOI 10.17487/RFC5234, January 2008,
           <https://www.rfc-editor.org/info/rfc5234>.

[RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
           Writing an IANA Considerations Section in RFCs", BCP 26,
           RFC 8126, DOI 10.17487/RFC8126, June 2017,
           <https://www.rfc-editor.org/info/rfc8126>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[unicode-tr36]
           Davis, M., Ed. and M. Suignard, Ed., "Unicode Technical
           Report #36: Unicode Security Considerations", September
           2014.

11.2. Informative References

[BIC]      International Organization for Standardization, "Banking
           -- Banking telecommunication messages -- Business
           identifier code (BIC)", ISO 9362, December 2014,
           <https://www.iso.org>.

[BIP0021]  Schneider, N. and M. Corallo, "Bitcoin Improvement
           Proposal 21", September 2019, <https://en.bitcoin.it/w/
           index.php?title=BIP_0021&oldid=66778>.

[GANA]     GNUnet e.V., "GNUnet Assigned Numbers Authority (GANA)",
           April 2020, <https://gana.gnunet.org/>.

[HMW12]    Huang, L., Moshchuk, A., Wang, H., Schecter, S., and C.
           Jackson, "Clickjacking: Attacks and Defenses", 2012,
           <https://www.usenix.org/system/files/conference/
           usenixsecurity12/sec12-final39.pdf>.

[ILP-ADDR] Interledger, "ILP Addresses - v2.0.0",
           <https://interledger.org/rfcs/0015-ilp-addresses/>.

[UPILinking]
           National Payments Corporation of India, "Unified Payment
           Interface - Common URL Specifications For Deep Linking And
           Proximity Integration", November 2017,
           <https://www.npci.org.in/sites/default/files/
           UPI%20Linking%20Specs_ver%201.6.pdf>.

Authors' Addresses 🎀

Florian Dold
Taler Systems SA
7, rue de Mondorf
L-5421 Erpeldange
Luxembourg

Email: dold@taler.net


Christian Grothoff
Bern University of Applied Sciences
Quellgasse 21
CH-2501 Biel/Bienne
Switzerland

Email: christian.grothoff@bfh.ch
📦 where this page comes from