A cabability URN for one time payments on the Internet.

Web Vouchers are a way to encode a voucher or voucher code into an URN.

Web Vouchers are a new type of identifier for one time payments on the web. These new identifiers are designed to enable the recipient to prove access to the funds associated with that voucher with one more vendors that accept that voucher. Web Vouchers are URNs of the form `urn:voucher:123456789abcdefghi`.

This document specifies a format, and operations that Web Vouchers may support.

This document in an informal draft discussed in the w3c web payments community group.


One time codes are a popular way of solving one off problems on the web. And example might be sending someone a code to log in to a system, or one to reset a password or one to creating a private address for a calendar. However there exists no generic URN on the web to encode such a one time code such that it can be used for redeeming a payment, good or service.

This document specifies a format, and operations that Web Vouchers may support.


This spec is a work in progress. The web vouchers spec started, and is currently being discussed, on the following threads.

Design Goals

Web Vouchers are a component of larger systems, such as the Linked Data ecosystem [[LINKED-DATA]], which have driven the design goals for this specification. This section summarizes the primary design goals for this specification.

Goal Description
Decentralization The voucher should not be server specific, though it may be.
Control Only the entities that know the voucher URN can use it.
Privacy The Voucher URN is kept private between those that honor it.
Security Transmission of a URN will be over encrypted formats.
Proof-based Using PKI, hash, or other trap door function, it is possible to identify a URN without being able to spend it.
Discoverability It may be possible to discover more information about a URN in a proof based network, or using an authoritative server.
Interoperability URIs and URNs are used to provide wide interoperability with existing systems on the web.
Portability Be system and network-independent and enable entities to use their digital identifiers with any system that supports Web Vouchers.
Simplicity Favor a reduced set of simple features in order to make the technology easier to understand, implement, and deploy.
Extensibility When possible, enable extensibility provided it does not greatly hinder interoperability, portability, or simplicity.

Design Considerations

There needs to be a public component, this is to allow the person owning/selling the voucher to know the voucher still contains value. The private part is what is used to redeem and claim the voucher credit. The private part is typically a one way retrieval process, e.g. tearing open the packet, scratching off the silver or hologram.

Secondly there needs to be checksums... people mistype stuff all the time. I'm finding using a single integer number works best for computers to read (e.g. QR code, NFC) and allow this number to be entered as mneomonics using Bitcoin's BIP39 so people can enter say 10 words to get that integer number to redeem the voucher.

Thirdly the issuer needs to be included in the URN. This is because you may have Starbucks, PayPal, CoinMode, Google, etc... could be issuing these vouchers. Whoever is issuing the voucher needs to be named somehow.

Fourthly the currency needs to be described. This is either USD, BTC, GBP, starbuck points etc..

Finally the other key learning is there must be an optional expiry date option as many vouchers are handled by businesses who need to reclaim lost funds somehow and expirery solves this.

There are other points to consider but these seem imperative. i.e. the fields are
    voucher: to define it is some sort of voucher
    url: where to query and get more info about the voucher.
    public: very large integer value to verify amount voucher can be redeemed for.
    private: the redeeming number
    destination: platform specific could be a cryptoaddress or user handle
This gives two urns. One to check a voucher and another to redeem it

JSON key values

The following are suggested JSON fields to tie to a voucher.
        public: 12345678901234567890,
        is_valid: true,
        currency: "bitcoin",
        expires: 1238972934 (epoch time)
        redeem_url : "https://www.acme.com/redeem"
        remaining_uses : 1
        redeemed : false
        redeemed_by : "??"
        redeemed_dates : [ 123987234, 124789238 ]

URN Format

The basic idea is to create a capability URN (like a capability URI but with an URN) and allow it to be used as a voucher for spending. The proposed format is :


The D word. Thhre. I said it. There are two things that are useful to discover. Firstly, more information about a voucher. The discovered document SHOULD return Linked Data. This can be done on a well known url, for example :
The other convenient thing that can be discovered is a server or servers that accept the voucher. This could be done over a gossip network with an initial bootstrap. A discovery node accepts the URN and points to a document with relevant servers.



The first client implementation uses vouchers to interact with the lightning network.

Client Demo


Server Code


This spec is a team effort. Thanks to Michiel De Jong, Andrew Bansford Brown, Stuart Rashford, Adrian Hope-Bailie and many others for making this possible.