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; 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 conceptual parallels shared by all four are:
This specification is payment-system agnostic. A service MAY require payment exclusively via bank transfer, exclusively via an instant-settlement network, or via any combination thereof. No payment scheme is privileged over any other at the protocol level.
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 invoice options spanning both traditional banking and an instant-settlement network.
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.
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 possesses 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 is the scheme-specific payment payload string (see Payment Schemes Registry).
The <option/> element possesses the following attributes:
The <option/> element MAY contain a <display-amount/> child element. This element contains a locale-appropriate human-readable string representing the amount for the option, making no assumption about which currency or payment system is primary. Examples: "EUR 5.00", "₹ 450", "R 18.50", "USD 0.001", "1 000 sat". Services SHOULD include <display-amount/> when the amount is not self-evident from the payload string.
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 the following attributes:
The <payment/> element MAY contain a <proof/> child element. The <proof/> element possesses a required 'type' attribute identifying the proof format (see Proof Types Registry), and its character data is the proof token.
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 one OPTIONAL attribute:
| 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. |
| scheme-unsupported | The 'scheme' value in the <payment/> element is not accepted by this service. |
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:
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).
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 this specification because it covers the widest range of payment networks within a single IETF-standardized format. Examples of valid payto URIs include:
Implementations MAY also use the European Payments Council (EPC) QR code format for SEPA Credit Transfers (the 'epc-qr' scheme) as an alternative for European users, particularly in countries where this format is already widely deployed (Austria, Belgium, Finland, Germany, Netherlands).
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.
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 URI-based payment options as QR codes, clients SHOULD also present the underlying 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.
The 'amount' attribute uses machine-readable RFC 8905 notation (currency:unit.fraction) rather than locale-formatted strings to avoid locale-dependent parsing errors. Human-formatted amounts SHOULD be derived by the client from the machine-readable value. The <display-amount/> element MAY carry a pre-formatted string if the service wishes to control presentation, but clients SHOULD treat this as advisory only.
ISO 4217 currency codes MUST be used for all standard currencies. Non-ISO identifiers (e.g., BTC, msat) MAY be used for assets not covered by ISO 4217.
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.
Instead, services SHOULD bind the 'session' attribute value to the parameters of the invoice itself using a keyed hash (HMAC). The RECOMMENDED input to the HMAC is the concatenation of: the service's JID, the 'purpose' value, the 'expires' value, and the total amount per scheme. Where the invoice was issued in response to a proactive <get-invoice/> request whose 'target' attribute identifies a specific resource (e.g., a content hash, a file identifier, or a room JID), the 'target' value SHOULD also be included as an HMAC input. This binds the session to the specific resource being purchased, so that a client cannot present a session identifier paid for resource A to obtain access to resource B.
Upon receiving a retried stanza, the service SHOULD recompute the HMAC over the same inputs and compare it against the received 'session' value. A session value that does not match MUST be rejected. This mechanism does not depend on any property of the client-supplied stanza, and therefore survives any server-side stanza mutation in transit.
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.
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'.
The XMPP Registrar
Each registration MUST specify all of the following:
The initial contents of this registry are as follows.
| Scheme | Description | Reference |
|---|---|---|
| payto | A 'payto' URI as defined by RFC 8905. This payment-system-neutral scheme covers IBAN/SEPA bank transfers, UPI, PIX, Bitcoin, and other payment target types within a single standardized format. RECOMMENDED as the primary URI scheme for this specification. Example: payto://iban/DE75512108001245126199?amount=EUR:200.00&message=ref | RFC 8905 |
| lightning-bolt11 | A Lightning Network BOLT 11 invoice string (e.g., beginning with lnbc, lntbs, or another network prefix). | BOLT 11 |
| lightning-bolt12 | A Lightning Network BOLT 12 offer or invoice string (e.g., beginning with lno or lni). | BOLT 12 |
| epc-qr | A European Payments Council QR code payload for SEPA Credit Transfers. Plain-text, newline-delimited format as defined by the EPC (EPC069-12). Commonly used in Austria, Belgium, Finland, Germany, and the Netherlands. | EPC069-12 |
Implementors MAY define private or experimental schemes using reverse-domain-name notation (e.g., com.example.custompay) without XMPP Registrar
The XMPP Registrar
| Type | Description | Payload Format |
|---|---|---|
| lightning-preimage | A 32-byte Lightning Network payment preimage, serving as cryptographic proof that the corresponding BOLT 11 or BOLT 12 invoice was paid. | 64-character lowercase hexadecimal string |
| reference | A payment reference or transaction identifier provided by the payer's bank or payment network after completing a transfer. Examples include a SEPA end-to-end identifier, a UPI transaction ID, and a PIX end-to-end identifier (E2EID). | Alphanumeric string; format is network-dependent |
| txid | An on-chain blockchain transaction identifier (e.g., a Bitcoin transaction ID). | Transaction ID string; format is network-dependent |
| token | An opaque bearer token issued by a facilitator service following verified payment. Enables a "pay once, use many times" pattern within the token's validity period. | Opaque string; format is implementation-defined |
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.
]]>