Open Payments concepts

The Open Payments (OP) standard helps to facilitate the setup of payments between OP-enabled payment accounts.

When setting up a payment, the client must obtain the wallet address for both the payer and payee. Since the payer is typically the client’s end-user, the client can obtain the payer’s wallet address during an onboarding process, for example. The payer must be authenticated by their account servicing entity (ASE) to grant the client the permission it needs to access the their OP-enabled account.

After the requisite wallet addresses are known, the client can begin obtaining grants to set up one or more payments. The grants allow the client to access the Open Payments API for the purpose of creating and accessing resources for incoming payments, quotes, and outgoing payments.

Wallet address server

Every OP-enabled account is identified by one or more wallet addresses. A wallet address is a publicly shareable account identifier and a service endpoint for gaining access to the Open Payments API. The payer and payee must both have a wallet address to transact using Open Payments.

A wallet address server provides basic details about a wallet address. For more information, visit the wallet addresses page.

Authorization server

An authorization server grants permission for a client to access the Open Payments API and the incoming-payment, quote, and outgoing-payment resources. Open Payments leverages GNAP as the mechanism for delegating authorization.

Refer to the Grant negotiation and authorization page for more information.

Resource server

The Open Payments API is served by a resource server. Operations on the API require the client to have a valid access token issued by a trusted authorization server.

Resource types

The Open Payments API is a simple REST API with three resource types: incoming-payment, quote, and outgoing-payment.

incoming-payment

The first resource to be created when setting up a payment is the incoming-payment resource, created on the payee’s account. When created, the payee’s ASE returns unique payment details to the client that can be used to address payments to the account. Any payments received using these details are then associated with the incoming-payment resource.

A client can issue requests to get an incoming payment’s specific details, as well as list all incoming payments in order to, for example, provide the end-user with transaction details and history.

Create an incoming payment without specifying an incomingAmount

When a request to create an incoming-payment resource includes an incomingAmount, the incomingAmount is the maximum amount to pay into the payee’s account. In other words, it’s the amount that the payee should receive.

Instead of specifying the amount to be received, you can specify how much you want to send by:

1. Excluding the incomingAmount in the request
2. Including a debitAmount of the amount you want to send within a Create Quote request (referred to as a fixed-send quote)
3. Creating an outgoing payment request that includes the quoteId of the above quote

The outgoing payment is created and funds are sent to the incoming-payment resource. However, the incomingAmount was never set, so there’s no indicator on the payee’s side for how much to expect. The payee’s ASE won’t know when the payment has completed.

Instead of waiting for the payment session to expire, the client can issue an explicit request to manually complete the incoming payment to indicate no further payments will be sent.

Use case: streaming Web Monetization (WM) payments

In streaming WM payments, the maximum amount to be paid is unknown to the payee’s ASE. Payments continue to stream until the WM agent ends the session. At this point, the WM agent can request to mark the incoming payment as complete. This enables the payee’s ASE to be notified as soon as possible that no further payments will be sent and to credit the payee’s account.

quote

After an incoming-payment resource is created on the payee’s account, a quote resource must be created on the payer’s account.

The purpose of a quote is to indicate how much it will cost, including any applicable fees, to make the payment. The quote serves as a commitment from the payer’s ASE to deliver a particular amount to the payee’s ASE. A quote is only valid for a limited time.

There are three types of quotes.

• Fixed-send quote - A fixed amount will be paid from the payer’s account. A debitAmount is required for this type. With this quote type, an incoming payment can’t automatically complete until it expires. Instead of waiting for the expiration, the client can issue a Complete Incoming Payment request when the outgoing payment is complete.
• Fixed-receive quote - A fixed amount will be paid into the payee’s account. A receiveAmount is required for this type.
• Quote with incomingAmount - The incoming payment already has a defined incomingAmount. For this type, the receiver is the URL of the incoming-payment resource that will be paid into, indicated by /incoming-payments being part of the URL.

A successfully created quote resource results in the generation of a quote id in the form of a URL.

outgoing-payment

After a quote resource is created, it’s almost time to create the outgoing-payment resource on the payer’s account. The purpose of the outgoing-payment resource is to serve as an instruction to make a payment from the payer’s account.

Open Payments requires the payer to explicitly consent to the creation of the resource before the client can issue the create request. Consent is obtained through an interactive grant.

Within the request to create the outgoing-payment resource is the payee’s wallet address, so the payer’s ASE knows where to send the payment, and the quote resource’s ID, where the payment amounts are defined.

After the outgoing-payment resource is created, the incoming payment can complete, either automatically or manually, to end the Open Payments flow. Now it’s up to the payer’s ASE to settle with the payee’s ASE over a shared payment rail.

An outgoing-payment resource can represent a payment that will be, is currently being, or has previously been sent from the payer’s account. A client can issue requests to get an outgoing payment’s specific details and list all outgoing payments in order to, for example, provide the end-user with transaction details and history.

Payment Methods

The payment method is the means by which the payer’s ASE will fulfill its payment obligations to the payee’s ASE. Cash, credit and debit cards, bank transfers, gift cards and mobile money can all be considered different payment methods.

When an outgoing-payment is completed against an open and active incoming-payment, the payer’s ASE becomes obligated to make payment using the payment method initially specified in the incoming-payment response.

Though OP is designed to be an abstraction layer that can issue payment instructions between transacting parties atop any payment method, Interledger (ILP) is the only payment method that currently integrates with OP readily.

When using ILP as a payment method in OP, the following information is required from the payee’s ASE, in the incoming payment’s method object.

• A type of ilp to indicate the payment method.
• The ILP address of the payee’s ASE: The ILP address is required so that packets representing payments routed over the Interledger network will be forwarded to the node owned and operated by the intended receiver (i.e. payee’s ASE).
• A shared secret: A cryptographically secured secret to be exchanged between the payer’s ASE (the sender) and the payee’s ASE (the receiver) to ensure that packets sent over the Interledger network through a STREAM connection can only be read by the two parties.

incoming-payment methods object

"methods": [
  {
    "type": "ilp",
    "ilpAddress": "g.ilp.iwuyge987y.98y08y",
    "sharedSecret": "1c7eaXa4rd2fFOBl1iydvCT1tV5TbM3RW1WLCafu_JA"
  }
]

After the incoming-payment response is received, the payer’s ASE creates a quote request containing "method": "ilp".