Following community review: identify payment systems by their URI scheme instead of an XSF-maintained registry; the option payload is now a payment URI and the redundant 'scheme' and 'amount' attributes are removed (amount and currency are carried by the URI). Made the payment URI mandatory and added an optional <qr/> child carrying a payment string to render as a QR code, for systems whose scannable QR format differs from the URI. Removed the Payment Schemes and Proof Types registries; proof types are now declared per option by the issuer and echoed by the payer, with a non-normative list of conventional types. Added the 'payment-pending' reason and a 'retry-after' attribute returned with stanza error type "wait". Added security guidance on amount-presentation integrity and clarified that clients need not parse payment URIs. Removed the <display-amount/> element: the amount is carried by the payment URI and obtained from there for display, avoiding a duplicate, unverifiable amount that could diverge from the URI. Clarified that a client can present any option without recognising its scheme — by QR code, URI handoff, or selectable text — and narrowed the case in which an option is genuinely unactionable.
First draft.
This XEP provides a mechanism for XMPP services to require payment before access to their resources or functionality is granted. Use cases include charging for account registration or hosting, compensating operators of AI agents or bots for compute costs, monetizing file hosting services per upload or download, requiring an entry fee for access to a Multi-User Chat (XEP-0045)
Existing XMPP anti-spam work (CAPTCHA Forms (XEP-0158)
Protocols such as Publish-Subscribe (XEP-0060)
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. 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.
This specification was designed with the following requirements in mind:
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 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).
Balthasar operates a news-summary bot that charges per query. Because the amounts are small and latency matters, only instant-settlement options are offered. This is a service-level policy decision, not a protocol constraint.
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 Service Discovery (XEP-0030)
If the service does not support proactive invoice requests, it SHOULD return a <feature-not-implemented/> error of type "cancel".
This specification extends CAPTCHA Forms (XEP-0158)
To embed a payment invoice within a CAPTCHA Forms (XEP-0158)
This specification uses the namespace 'urn:xmpp:payment:0'. (see Namespace Versioning regarding the possibility of incrementing the version number)
The following elements are defined in the 'urn:xmpp:payment:0' namespace.
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 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), 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 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 following proof types are in common use. This list is non-normative: it is a convenience vocabulary, not a registry maintained by this specification. The format and verification of each is defined by the relevant payment system's own standard.
| Type | Meaning |
|---|---|
| preimage | A secret revealed upon settlement of a hash-locked payment (e.g. a Lightning Network payment preimage). |
| reference | A transaction or end-to-end reference string supplied by the payment network (e.g. a SEPA end-to-end identifier, a UPI transaction ID, a PIX E2EID). |
| txid | An on-chain transaction identifier. |
| proof | A payee-verifiable cryptographic payment proof supplied out of band (e.g. a private-network transaction proof). |
| token | An opaque bearer token issued by a facilitator after verified payment, enabling a "pay once, use many times" pattern. |
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:
| Value | Meaning |
|---|---|
| payment-required | No <payment/> element was present. The resource requires payment before access is granted. |
| invalid-session | The 'session' value is unknown, has already been consumed, or does not match the HMAC verification check. |
| payment-expired | The invoice has passed its 'expires' time and may no longer be honored. The payer SHOULD request a fresh invoice. |
| verification-failed | A <proof/> element was present but the proof could not be verified as valid for the referenced payment. |
| payment-insufficient | The payment amount detected was less than the required amount. |
| 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 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. 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 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 Service Discovery (XEP-0030)
The <get-invoice/> element is the payload of a proactive invoice request. It is sent as the child of an IQ-get stanza and possesses the following attributes:
When a service requires payment for an action, it MUST respond to the triggering stanza with an error of type "auth" containing the <payment-required/> application condition element qualified by 'urn:xmpp:payment:0', and MUST include an <invoice/> element as a sibling of the error condition element within the <error/> element.
The "auth" error type is appropriate because the payer has not yet demonstrated authorization (via payment) to access the resource. The <payment-required/> application condition distinguishes this case from <not-authorized/> and <registration-required/>.
If the requesting entity is not authenticated at all (e.g., it has not completed SASL authentication with its own server, or its JID cannot be verified), the service SHOULD return a <not-authorized/> error rather than a <payment-required/> error. Payment challenges SHOULD only be issued to entities whose identity can be established, to prevent anonymous entities from exploiting the payment flow to probe service behavior.
The service SHOULD include a human-readable <text/> child within the <error/> element describing the reason for the payment requirement.
When a <payment/> element is present on a retried stanza but verification fails, the service SHOULD return a <not-acceptable/> error of type "modify" containing a <payment-required/> element with an appropriate 'reason' attribute (see The payment-required Element), and MAY include a new <invoice/> element to allow the payer to retry with a fresh payment. Using a machine-readable 'reason' value allows automated agents to distinguish between a recoverable failure (e.g., 'payment-expired', which warrants requesting a new invoice) and a non-recoverable one (e.g., 'verification-failed', which warrants escalating to the user).
Some payment systems settle asynchronously: the service may have detected a payment for the session but cannot yet confirm it has settled (e.g. a bank transfer awaiting reconciliation, or a cryptocurrency payment awaiting confirmations). In this case, where the service does not need a proof from the payer, only more time, it SHOULD return a stanza error of type "wait" (per RFC 6120
The mechanism by which a service verifies that a payment has been made is outside the scope of this specification. The following non-normative guidance is provided for implementors.
For bank transfers (SEPA, IBAN, UPI, PIX, SWIFT, etc.), the service typically cannot verify payment in real time. The service SHOULD encode the session identifier as the payment reference in the payto URI (the 'message' or 'instruction' query parameter) and reconcile incoming payments against outstanding sessions via its bank's API or statement-import mechanism. Because bank transfers can take from seconds (SEPA Instant) to days (SWIFT) to settle, bank transfer options are best suited to one-time access grants such as account registration or monthly subscriptions rather than per-message micropayments.
For Lightning Network payments, the service MAY verify payment by stateless preimage verification: if the payment hash is encoded in the session identifier, the service verifies that SHA-256(preimage) matches the payment hash without querying external state. Alternatively, the service MAY query its own Lightning node for a settled invoice.
A facilitator service MAY issue an opaque bearer token after verifying payment. The token can be used across multiple retried stanzas within its validity period, enabling a "pay once, use many times" pattern. The format and lifecycle of such tokens is outside the scope of this specification.
A service MUST NOT accept the same session identifier more than once. Once a session is consumed, the service MUST invalidate it. A service MUST NOT honor a session after the time specified in the 'expires' attribute.
The following rules apply to implementations of this specification.
The 'payto' URI scheme (RFC 8905) is the RECOMMENDED primary URI scheme for traditional bank rails, because it covers the widest range of them within a single IETF-standardized format. Examples of valid payto URIs include:
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 CAPTCHA Forms (XEP-0158)
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.
The 'purpose' attribute of <invoice/> and the 'label' attribute of <option/> are human-readable strings. Services SHOULD provide these in the language of the recipient where known. Multiple language variants MAY be provided using the standard 'xml:lang' attribute on any element containing character data.
This specification does not define an amount or currency syntax of its own: the amount, currency, and any denomination are carried inside the payment URI and are governed by that URI scheme's own standard (for payto, the RFC 8905 currency:amount notation). A client that displays the amount derives it from the URI and SHOULD format it for the recipient's locale.
The following security considerations apply to implementations of this specification.
Session identifiers MUST be unique and single-use. A service MUST maintain a record of consumed session identifiers for at least as long as the invoice expiry window to prevent replay attacks. Reusing a session identifier to obtain multiple access grants MUST be rejected.
Because XMPP servers routinely mutate stanzas in transit — adding elements such as <delay/>, rewriting the 'from' attribute, injecting stream management acknowledgements, and normalizing namespace prefixes — it is not possible for a service to cryptographically bind an invoice to the byte content of the stanza it declined. Body-level hashing, as used by HTTP-based payment protocols, is therefore not applicable in XMPP.
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., OMEMO Encryption (XEP-0384)
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:
End-to-end encryption (e.g. OMEMO Encryption (XEP-0384)
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.
The 'session' value SHOULD NOT encode any information about the payer's identity or behavior.
This document requires no interaction with the Internet Assigned Numbers Authority (IANA).
The XMPP Registrar
If the protocol defined in this specification undergoes a revision that is not fully backwards-compatible with an older version, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of XEP-0053.
The XMPP Registrar
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 XMPP Registrar
This is the one registry this specification defines, and it concerns XMPP application contexts (a domain within the XSF's remit) rather than payment systems.
The XMPP Registrar
| Value | Description |
|---|---|
| muc-entry | Entry fee for a Multi-User Chat (XEP-0045) |
| file-upload | Fee for a file upload service (e.g., HTTP File Upload (XEP-0363) |
| message | Per-message fee, e.g., for a bot service or an anti-spam deposit. |
| registration | Account registration or hosting fee. |
Several alternative designs were considered during the development of this specification.
Data Forms (XEP-0004)
The "auth" error type was chosen for the payment-required error rather than, say, "cancel" or a new type, because the payer genuinely lacks authorization to perform the requested action until payment is made. This mirrors the semantics of HTTP 402 and is consistent with the existing use of "auth" for <registration-required/> in RFC 6120
This specification defines only single-payment ("charge") semantics: one invoice, one payment, one grant. For high-frequency use cases such as per-query AI agent bots, this model requires a new invoice round-trip for every request, which introduces latency and overhead.
A future companion specification MAY define streaming payment session semantics, analogous to the session intent in the Machine Payments Protocol (MPP). In such a model, an agent would open a payment channel by pre-funding it, and subsequent requests within the same channel would be settled using off-chain cryptographic vouchers without requiring a new invoice or an on-chain transaction per query. Such a specification would advertise support via a new feature (e.g., 'urn:xmpp:payment:0#session') and is outside the scope of this document.
]]>