Account Discovery

At the heart of all interactions in Open Payments is an account. The account could be either the sending or the receiving side of the transaction. The entity initiating the transaction is the Open Payments client and discovers the account at the Open Payments server.

In the following example of a person-to-person payment from Alice to Bob, Alice's wallet is the client and therefore her wallet discovers Bob's account at his wallet to begin the transaction.

However, in the second example Alice is the payee but her wallet still uses Bob's Payment Pointer to discover his account and create and authorize a mandate to pull funds from it.

Discovery starts with an identifier, which in Open Payments is an account identifier called a Payment Pointer.

Payment Pointers

All entities in Open Payments are resources identified by, and addressable via, URLs in keeping with the REST pattern. This includes accounts which are the root resource in Open Payments. Discovery involves finding the URL of the account resource because all other resource URLs are relative to the account.

Example account URL:
https://wallet.example/accounts/dee69df8-be40-478f-9828-6267f4d42b01

To make account URLs shorter and easier to transcribe they can be encoded as a Payment Pointer. In this form they also have the advantage of being easily and unambiguously recognizable as Payment Pointers.

Example Payment Pointer:
$wallet.example/accounts/dee69df8-be40-478f-9828-6267f4d42b01

Wallets that support Open Payments will define one or more unique account URLs for each account they service on behalf of the account owner.

erDiagram OWNER ||--|{ ACCOUNT : has ACCOUNT-URL }|--|| ACCOUNT : "identified by" ACCOUNT-URL ||--|| PAYMENT-POINTER : "encoded as"

The rules for encoding and decoding Payment Pointers are defined at paymentpointers.org.

Personal Payment Pointers

In many cases a user will have multiple accounts and will register a single short and easy to transcribe Personal Payment Pointer which they link to their default account. This Personal Payment Pointer can then be easily exchanged with counter-parties when initiating a payment (either as sender or receiver).

Example Personal Payment Pointer:
$wallet.example/alice

Personal Payment Pointers are analogous to an email address or payment card number. Email addresses are given to counter-parties so that they can begin sending emails to the target inbox. Similarly, a payment card number can be given to a counter-party so that they can request payment from the target account.

Users can share their Personal Payment Pointers to both get paid and make payments using Open Payments.

Importantly, a Payment Pointer is not sensitive in the same way that a payment card number is. It can be shared freely with no risk that funds will be pulled from the target account without the account owner's consent

Metadata

Account metadata is provided by an Open Payments Server as a JSON document that describes the various service endpoints that are available to:

  • make payments directly to the account via Interledger (or other payment methods)
  • get authorization to perform actions on the account (using OAuth 2.0)
  • get more information about the owner of the account (using OpenID Connect)
  • create invoices and mandates that are linked to the account

The document is hosted at the account URL and is the default representation of the account resource (using the media type of application/json).

The account URL is the root of further interactions with the account as all other APIs are relative to the account URL.

See the accounts API for more details.