Payment Pointers

Every account has a URL that is also the API service endpoint

At the heart of all interactions in Open Payments is a financial account. Access to this account 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 identifies a financial account that can be accessed via the Open Payments APIs
  3. the URL is the service endpoint for the Open Payment APIs
  4. 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 Point 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 financial account, including the URL of the grant request endpoint, which can be used to get access tokens to connect to the account 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 account can have one or more Payment Pointers. The Payment Pointer is a proxy identifier for the underlying account. This loose coupling allows Payment Pointers to be disabled or even linked to a new account (although there are considerations that must be made before allowing this) without affecting the underlying account.

An account holder 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 an account. Any two distinct Payment Pointers should be treated as distinct accounts by clients even if the client is aware that they are proxies for the same underlying account.

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

Discovery and Interaction

Using URLs as payment instruments solves one of the biggest issues with existing account to account payments, 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 account identifier and resource locator for the account in order to access it via APIs and begin an interaction with the provider of the account.

Using URLs as account 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.


Did this page help you?