At the heart of all interactions in Open Payments is a digital wallet. Access to this wallet via the Open Payments APIs always starts with a URL which we call a Payment Pointer.

Not all URLs are Payment Pointers, but all Payment Pointers are URLs.

A URL is only a Payment Pointer if:

1. the server handling HTTP requests to that URL supports the Open Payments protocol
2. the URL dereferences a resource defined by the Open Payments APIs (a client, wallet, incoming payment, or outgoing payment)
3. the URL uses the https protocol and has no user-info, port, query string, or fragment parts

The quickest way to test if a URL that looks like a Payment Pointer really is a Payment Pointer is to make an HTTP GET request to it with an Accept header value of application/json:

GET /alice HTTP/1.1
Host: openpayments.example
Accept: application/json

If the URL is a Payment Pointer, the response will provide details of the underlying wallet, including the URL of the grant request endpoint, which can be used to get access tokens to connect to the wallet via the Open Payments APIs.

HTTP/1.1 200 Success
Content-Type: application/json

{
    "id": "https://openpayments.example/alice",
    "publicName": "Alice"
    "assetCode": "USD",
    "assetScale": 2
    "authServer": "https://auth.openpayments.example"
}

Shortened Form

Payment Pointers have a shortened form which makes them easier to transcribe and most importantly make them easy to recognise as Payment Pointers (as opposed to regular URLs).

📘

Example

https://openpayments.example/alice is shortened to $openpayments.example/alice.

A shortened-form Payment Pointer can be converted into a URL by simply replacing the $ character at the start of the string with https://.

There is a special case for URLs with no path. This is to avoid conflicts with the root of the domain which is often reserved for serving a web page. A shortened-form Payment Pointer that results in a URL with no path when converted to the long form should use the value .well-known/pay as the path.

📘

Example

$openpayments.example is expanded to https://openpayments.example/.well-known/pay

i18n

While the use of the dollar $ symbol is not applicable for all currencies it is the only symbol that is in the set of allowed characters for a URI (as defined in RFC3986).

Other symbols such as €, ¥, and £ can be used in URLs but they must be percent-encoded first.

Since the $ symbol is used for multiple currencies (not just the US dollar) and is widely understood to symbolise money or finance it has been used as the prefix for short-form Payment Pointers. Using the $ symbol does not imply that the underlying account is denominated in dollars, it is simply a useful indicator that the string that follows can be converted to a URL that is a Payment Pointer.

Privacy and Security

A single wallet can have one or more Payment Pointers. The Payment Pointer is a proxy identifier for the underlying wallet. This loose coupling allows Payment Pointers to be disabled or even linked to a new wallet (although there are considerations that must be made before allowing this) without affecting the underlying wallet.

A wallet owner might wish to generate unique Payment Pointers for every counter-party they interact with to prevent the Payment Pointer becoming a tracking vector.

For any external parties, a Payment Pointer is as good as a wallet. Any two distinct Payment Pointers should be treated as distinct wallets by clients even if the client is aware that they are proxies for the same underlying wallet.

Permissions granted to a client for access to a wallet via one Payment Pointer are not automatically usable to access the same wallet via other Payment Pointers.

Discovery and Interaction

Using URLs as payment instruments solves one of the biggest issues with existing payments user experiences, discoverability and interaction.

URLs (Universal Resource Locators) have been used on the Web for decades to provide a way for clients to directly locate a resource and begin interacting with it (via HTTP). Payment Pointers are both a proxy identifier and resource locator for the wallet in order to access it via APIs and begin an interaction with the provider of the wallet.

Using URLs as proxies is also preferable to overloading other identifiers such as email addresses and MSISDNs as these proxies have no standard for interaction. The result is that an identifier like an MSISDN or email requires a registry that maps the identifier to an account provider and a mechanism for governing this mapping securely.