Protocols such as &xep0060; already acknowledge that services may require payment for operations (e.g., node subscriptions or item retrieval) but leave the payment mechanism out-of-band. This specification provides the in-band protocol to fulfill that need.
-The design is informed by analogous protocols in the HTTP ecosystem: the long-reserved HTTP 402 Payment Required status code; the L402 protocol published by Lightning Labs, in which a client receives a WWW-Authenticate header containing a macaroon token and a Lightning invoice and presents a token-preimage credential after payment; and the x402 protocol published by Coinbase et al., in which a client receives an HTTP 402 response with a PAYMENT-REQUIRED header listing accepted payment schemes and retries with a PAYMENT-SIGNATURE header; and the Machine Payments Protocol (MPP) published by Stripe and Tempo, an IETF-tracked open standard for machine-to-machine payments that similarly uses HTTP 402 challenges with multi-method selection, machine-readable error codes, payment receipts, and cryptographic challenge binding. +
The design is informed by analogous protocols in the HTTP ecosystem: the long-reserved HTTP 402 Payment Required status code; the L402 protocol published by Lightning Labs, in which a client receives a WWW-Authenticate header containing a macaroon token and a Lightning invoice and presents a token-preimage credential after payment; the x402 protocol published by Coinbase et al., in which a client receives an HTTP 402 response with a PAYMENT-REQUIRED header listing accepted payment schemes and retries with a PAYMENT-SIGNATURE header; and the Machine Payments Protocol (MPP) published by Stripe and Tempo, an IETF-tracked open standard for machine-to-machine payments that similarly uses HTTP 402 challenges with multi-method selection, machine-readable error codes, payment receipts, and cryptographic challenge binding.
The conceptual parallels shared by all four are:
This specification is payment-system agnostic. A service MAY require payment exclusively via bank transfer, distributed ledger, instant-settlement network, or any combination thereof. No payment system is privileged over any other at the protocol level. - Crucially, this specification does not enumerate or curate payment systems itself: each payment option is - expressed as a payment URI, and the payment system is identified by that URI's scheme (registered in the IANA URI Schemes registry, - and, for the payto scheme, the payment target types maintained externally per RFC 8905). Adding support for a new - payment network therefore requires no change to this document.
+ This specification also does not enumerate or curate payment systems. Each payment option is expressed as a payment URI, + and the payment system is identified by that URI's scheme. Adding support for a new payment network therefore requires no change + to this document. ++ The payment URI SHOULD be registered in the IANA URI Schemes registry, but there are URIs widely used by wallet and payment software + that are not yet registered, such the lightning: URI scheme, documented in the Lightning Network specifications (BOLT #11). + For the payto: scheme, which is IANA registered, the payment target types are maintained externally per RFC 8905.
Juliet operates a premium conference room on conference.shakespeare.lit that charges an entry fee. - Romeo attempts to join but is declined and presented with invoice options spanning both traditional banking and an instant-settlement network.
+ Romeo attempts to join but is declined and presented with multiple invoice options.Because SEPA bank transfers may take time to settle, the service SHOULD set a generous session expiry for bank-transfer options and MAY grant access provisionally upon receiving the retry stanza, subsequently revoking it if reconciliation fails. Alternatively, where the service has detected the payment but has not yet confirmed settlement, it MAY ask the payer to wait and retry later (see Error Flow).
+Juliet's server requires a small deposit from senders not present in her roster, as a proof-of-intent mechanism to deter unsolicited messages. Instant-settlement options are used because slow bank transfers would allow queuing before verification.
+Juliet's server requires a small deposit from senders not present in her roster, as a proof-of-intent mechanism to deter unsolicited messages. + Instant-settlement options are used because slow bank transfers would allow queuing before verification.
A client MAY proactively request an invoice from a service before sending the gated stanza. This is useful when the client wishes to present payment options to the user before committing to an action. Before sending a proactive invoice request, the client SHOULD discover whether the service supports this feature by querying for the 'urn:xmpp:payment:0#invoice-request' feature via &xep0030;.
+A client MAY proactively request an invoice from a service before sending the gated stanza. + This is useful when the client wishes to present payment options to the user before committing to an action. + Before sending a proactive invoice request, the client SHOULD discover whether the service supports this + feature by querying for the 'urn:xmpp:payment:0#invoice-request' feature via &xep0030;.
The <invoice/> element is the container for all payment options associated with a single payment event. It MUST contain at least one <option/> child element and MAY contain a <description/> child element whose character data provides additional human-readable context.
-The <invoice/> element possesses the following attributes:
+The <invoice/> element has the following attributes:
Each <option/> element describes one complete, self-contained payment method. The payer MUST use exactly one option to fulfill the invoice.
-The character data of the <option/> element MUST be a payment URI. The payment system is identified by the URI's scheme (e.g. payto: per RFC 8905, or lightning: for a Lightning Network invoice or offer), and the amount, currency, and beneficiary are carried within the URI as defined by that scheme's own standard. This specification neither defines nor curates the set of usable schemes; any scheme registered in the IANA URI Schemes registry MAY be used. The payto URI scheme (RFC 8905) is RECOMMENDED as the primary scheme.
+The character data of the <option/> element MUST be a payment URI. The payment system is identified by the URI's scheme (e.g. payto: per RFC 8905), and the amount, currency, and beneficiary are carried within the URI as defined by that scheme's own standard. This specification neither defines nor curates the set of usable schemes. The payto URI scheme (RFC 8905) is RECOMMENDED as the primary scheme.
A client is NOT required to parse the payment URI. It MAY treat the URI as an opaque string to be handed to an external payment application or rendered as a QR code; see Amount Presentation Integrity.
The <option/> element possesses the following attributes:
This specification does not define a separate human-readable amount field. The amount is carried in the payment URI: a client that parses the option's scheme reads it from there for display, while one that does not delegates the URI to a payment application that displays it (see Amount Presentation Integrity). A duplicate amount supplied alongside the URI would be redundant in the first case and unverifiable in the second. The amount is readily extracted from common schemes (payto from its amount=currency:value parameter, bitcoin: from its decimal amount, a lightning: BOLT 11 invoice from its prefix); for less common schemes, and where no amount is encoded at all (such as a zero-amount Lightning invoice), the payer's payment application presents the amount it is about to send for confirmation.
-The <option/> element MAY also contain a <qr/> child element whose character data is a payment string to be rendered as a QR code. This is useful where the payment URI is not itself the QR payload that the payer's payment application expects to scan, for example, a SEPA credit transfer for which banking apps scan a European Payments Council (EPC069-12) payload rather than a payto URI. A client renders the <qr/> content as a QR code without interpreting it, exactly as it would QR-encode the URI, so no scheme-specific parsing is required. This specification does not define or constrain the format of the <qr/> payload; that is a matter between the service and the scanning payment application. Because a payment URI is always present, the <qr/> element is purely an additional rendering convenience: it is not authoritative and is subject to the same integrity considerations as other invoice content (see Amount Presentation Integrity). Clients SHOULD also present the underlying URI as selectable text for accessibility.
+This specification does not define a separate human-readable amount field. The amount is carried in the payment URI. A client that parses the option's scheme reads it from there for display, while one that does not delegates the URI to a payment application that displays it (see Amount Presentation Integrity). A duplicate amount supplied alongside the URI would be redundant in the first case and unverifiable in the second. The amount is readily extracted from common schemes (payto from its amount=currency:value parameter, bitcoin: from its decimal amount, a lightning: BOLT 11 invoice from its prefix). For less common schemes, and where no amount is encoded at all (such as a zero-amount Lightning invoice), the payer's payment application presents the amount it is about to send for confirmation.
+The <option/> element MAY also contain a <qr/> child element whose character data is a payment string to be rendered as a QR code. This is useful where the payment URI is not itself the QR payload that the payer's payment application expects to scan, for example, a SEPA credit transfer for which banking apps scan a European Payments Council (EPC069-12) payload rather than a payto URI. A client renders the <qr/> content as a QR code without interpreting it, exactly as it would QR-encode the URI, so no scheme-specific parsing is required. This specification does not define or constrain the format of the <qr/> payload; that is a matter between the service and the scanning payment application. Because a payment URI is always present, the <qr/> element is purely an additional rendering and payment convenience and is subject to the same integrity considerations as other invoice content (see Amount Presentation Integrity). Clients SHOULD also present the underlying URI as selectable or copyable text for accessibility.
The <payment/> element is added by the payer as an extension to the retried stanza to indicate that a payment has been made for the referenced session.
The <payment/> element possesses a single attribute:
The <payment/> element MAY contain a <proof/> child element. The <proof/> element possesses a required 'type' attribute and its character data is the proof token. Where the satisfied option carried a 'proof' attribute, the payer SHOULD set 'type' to that declared value. The proof token is opaque to XMPP; its syntax and verification are defined by the payment system the option uses, not by this specification.
The <payment-required/> element is an application-specific stanza error condition. It is used as a child of the <error/> element to indicate that the requested action requires payment before it can be fulfilled.
+The <payment-required/> element is an application-specific stanza error condition. + It is used as a child of the <error/> element to indicate that the requested action requires payment before it can be fulfilled.
+The <payment-required/> element possesses the following OPTIONAL attributes:
| payment-pending | -A payment has been detected for the referenced session but has not yet been confirmed as settled. The payer should wait and retry. This is not a failure; it is paired with stanza error type "wait" and SHOULD be accompanied by a 'retry-after' attribute (see Error Flow). | +A payment has been detected for the referenced session but has not yet been confirmed as settled. The payer should wait and retry. + This is not a failure and is therefore paired with stanza error type "wait" and SHOULD be accompanied by a 'retry-after' attribute (see Error Flow). |
The <payment-required/> element additionally possesses an OPTIONAL retry-after attribute: a non-negative integer number of seconds the payer SHOULD wait before retrying the same session. It is meaningful with the 'payment-pending' reason (and MAY accompany any transient condition returned with stanza error type "wait").
+ +The <payment-required/> element additionally possesses an OPTIONAL retry-after attribute. + If it exists, it MUST be set to a non-negative integer number of seconds the payer SHOULD wait before retrying the same session. + It is meaningful with the 'payment-pending' reason (and MAY accompany any transient condition returned with stanza error type "wait").
The <receipt/> element MAY be included by a service in the successful response to a retried stanza to provide the payer with a machine-readable record of the settled payment. It is an OPTIONAL protocol element; its absence does not indicate that payment failed.
-The <receipt/> element possesses the following attributes:
+The <receipt/> element MAY be included by a service in the successful response to a retried stanza to provide the payer with a machine-readable record of the settled payment. + It is an OPTIONAL protocol element and its absence does not indicate that the payment failed.
+ +The <receipt/> element has the following attributes:
A service that supports emitting receipts SHOULD advertise the feature 'urn:xmpp:payment:0#receipt' via &xep0030;.
Because each option carries a payment URI, any payment system reachable through a registered URI scheme is usable without modifying this specification. Cryptocurrency networks are addressed through their own native schemes rather than through a payto target type because typically the native scheme is the form the payer's wallet recognises (see The option Element).
-A QR code is normally generated directly from the payment URI: the client renders the URI string as a QR code without interpreting it, and the payer scans it with a wallet or banking application. This works natively for cryptocurrency URI schemes. For some bank-transfer systems, however, the payment application expects a different QR payload (for example, banking apps in several European countries scan a European Payments Council EPC069-12 payload rather than a payto URI). In that case the service MAY additionally supply that payload in the <qr/> child of the option, which the client likewise renders as a QR code without interpreting it. The payment URI itself remains REQUIRED, so a machine-readable, scheme-identified payment instruction is always present.
-When generating Lightning Network invoices for inclusion in an <option/> element, the service SHOULD encode the payment hash in a way that allows stateless preimage verification (see Verification), avoiding the need to query the Lightning node on every retry.
+Because each option carries a payment URI, any payment system reachable through a registered URI scheme is usable without modifying this specification. + Cryptocurrency networks are often better addressed through their own native schemes rather than through a payto target type because typically + the native scheme is the form the payer's wallet recognises (see The option Element).
+ +A QR code is normally generated directly from the payment URI: the client renders the URI string as a QR code without interpreting it, + and the payer scans it with a wallet or banking application. This works natively for cryptocurrency URI schemes. For some bank-transfer systems, + however, the payment application expects a different QR payload (for example, banking apps in several European countries scan a European Payments Council + EPC069-12 payload rather than a payto URI). In that case the service MAY additionally supply that payload in the <qr/> + child of the option, which the client likewise renders as a QR code without interpreting it. The payment URI itself remains REQUIRED, + so a machine-readable, scheme-identified payment instruction is always present.
Clients MUST NOT present a payment interface as the sole means of completing an action where an accessibility-equivalent alternative exists. Where a service also offers a &xep0158; CAPTCHA challenge, the payment option and the CAPTCHA option SHOULD be presented with equal prominence.
-When rendering a payment option as a QR code, whether from the payment URI or from a <qr/> payload, clients SHOULD also present the underlying payment URI as selectable text so that users of screen readers or other assistive technologies can copy and use it directly.
+Clients MUST NOT present a payment interface as the sole means of completing an action where an accessibility-equivalent alternative exists. + Where a service also offers a &xep0158; CAPTCHA challenge, the payment option and the CAPTCHA option SHOULD be presented with equal prominence.
+When rendering a payment option as a QR code, whether from the payment URI or from a <qr/> payload, + clients SHOULD also present the underlying payment URI as selectable text so that users of screen readers or other assistive technologies can copy and use it directly.
A service therefore MUST verify a session against parameters it knows itself, never against any property of the client's retry stanza; this is what allows verification to survive server-side stanza mutation. The session value MUST be unguessable and MUST be bound to what was purchased (e.g. the resource the invoice grants access to and the amount required) so that a session obtained for one resource or amount cannot be redeemed for another. Where the invoice was issued in response to a proactive <get-invoice/> request, the 'target' resource SHOULD be part of this binding.
How the service achieves this is an implementation choice. It MAY store server-side state mapping the session to the invoice, or encode the binding into a self-contained keyed token, for example an HMAC over those service-side parameters (not the option URIs, which embed the session and are not echoed on retry) together with a per-invoice nonce, so that each session stays unique and can be re-verified without storing the invoice. Either way the service MUST record consumed sessions until they expire (see Replay Attacks): the token approach avoids storing invoice parameters but not the set of consumed sessions.
+An intermediary XMPP server could modify <invoice/> contents in transit, redirecting payment destinations to attacker-controlled accounts. Implementations SHOULD use end-to-end encryption (e.g., &xep0384;) when the integrity of invoice contents is critical. For Lightning Network options, stateless preimage verification protects the service from granting access without payment: because the session identifier is bound to the payment hash (see Session Binding), a tampered invoice would yield a preimage that fails verification. This does not protect the payer, who may still send funds to an attacker; end-to-end encryption is required for that.
For traditional bank transfer options, no equivalent cryptographic binding between the invoice and the beneficiary account exists. Users SHOULD independently verify beneficiary account details before initiating a bank transfer, particularly when communicating with a service for the first time.
The authoritative amount and beneficiary of a payment are those encoded in the payment URI of the chosen <option/>. This specification deliberately carries no separate human-readable amount field: a duplicate amount supplied alongside the URI could not be verified against it by a client that does not parse the scheme, and a preview diverging from the URI is a spoofing risk. The label and purpose attributes remain human-readable text describing the option and the reason for payment.
Accordingly:
@@ -616,15 +638,22 @@ upperroom-c4a1f902End-to-end encryption (e.g. &xep0384;) protects the integrity of the URI in transit.
Clients MUST NOT automatically pay an invoice above a configurable amount threshold without explicit user confirmation. Implementations SHOULD default this threshold to zero (i.e., all payments require explicit user approval) and SHOULD allow the user to raise it. Automated agents operating within a pre-authorized budget MAY raise this threshold programmatically for their specific use case, but MUST NOT do so without the knowledge and consent of the account holder.
+Clients MUST NOT automatically pay an invoice above a configurable amount threshold without explicit user confirmation. + Implementations SHOULD default this threshold to zero (i.e., all payments require explicit user approval) and SHOULD allow the user to raise it. + Automated agents operating within a pre-authorized budget MAY raise this threshold programmatically for their specific use case, + but MUST NOT do so without the knowledge and consent of the account holder.
Services MUST NOT include information in invoice metadata that would allow correlation of payments to real-world identities beyond what is required for the service function.
-Lightning Network payment hashes are pseudonymous. However, a service that retains proof-of-payment preimages alongside session records can link a payment to the payer's JID. Services SHOULD minimize the identity information stored alongside consumed session records and SHOULD delete such records once the access grant has expired.
-Traditional bank transfer options inherently reveal the payer's real name and account details to the payee, as this is a property of the underlying banking system. Clients SHOULD inform the user of this before initiating a bank transfer to a party the user has not previously transacted with.
+Lightning Network payment hashes are pseudonymous. However, a service that retains proof-of-payment preimages alongside session records can link a payment to the payer's JID. + Services SHOULD minimize the identity information stored alongside consumed session records and SHOULD delete such records once the access grant has expired.
+Traditional bank transfer options inherently reveal the payer's real name and account details to the payee, as this is a property of the underlying banking system. + Clients SHOULD inform the user of this before initiating a bank transfer to a party the user has not previously transacted with.
The 'session' value SHOULD NOT encode any information about the payer's identity or behavior.
An entity that supports the error-flow portion of this protocol MUST advertise the feature 'urn:xmpp:payment:0'. An entity that additionally supports the proactive IQ-based invoice request MUST advertise 'urn:xmpp:payment:0#invoice-request'. An entity that supports emitting <receipt/> elements upon successful payment MUST advertise 'urn:xmpp:payment:0#receipt'.
+An entity that supports the error-flow portion of this protocol MUST advertise the feature 'urn:xmpp:payment:0'. + An entity that additionally supports the proactive IQ-based invoice request MUST advertise 'urn:xmpp:payment:0#invoice-request'. + An entity that supports emitting <receipt/> elements upon successful payment MUST advertise 'urn:xmpp:payment:0#receipt'.
This specification deliberately does not establish an ®ISTRAR; registry of payment schemes, payment systems, or proof-of-payment formats. Curating payment systems is outside the XSF's area of expertise and is already handled by external bodies. Payment options are identified by their URI scheme via the IANA URI Schemes registry, and for the payto scheme by the payment target types maintained externally under RFC 8905. Proof types are declared per option by the issuing service and echoed by the payer (see The payment Element); the conventional values listed there are non-normative and their formats are defined by the relevant payment systems' own specifications.
+This specification deliberately does not establish an ®ISTRAR; registry of payment schemes, payment systems, or proof-of-payment formats. + Curating payment systems is outside the XSF's area of expertise and is already handled by external bodies. Payment options are identified by their URI scheme, + ideally via the IANA URI Schemes registry, and for the payto scheme by the payment target types maintained externally under RFC 8905. + Proof types are declared per option by the issuing service and echoed by the payer (see The payment Element). + The conventional values listed there are non-normative and their formats are defined by the relevant payment systems' own specifications.