Resources

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

Resource types

An Open Payments resource server hosts three sets of APIs, those for incoming payments, quotes, and outgoing payments. A client must receive authorization, via grants, to use any of the APIs.

Each set of APIs has its own resource type: incoming-payment, quote, and outgoing-payment.

incoming-payment

An incoming-payment resource is often the first resource created in a payment flow, by way of the Create Incoming Payment API . The resource is created on the recipient’s account.

The recipient’s account servicing entity (ASE) then returns unique payment details that the client will use to address payments to the recipient. Any payments received using these details are associated with the incoming-payment resource.

incomingAmount

An incoming payment request can include or exclude an incomingAmount.

When an incomingAmount is included, the amount represents the maximum amount to pay into the recipient’s account. One or more payments can be issued using the resource’s unique details but their total amounts can’t exceed the maximum.

When an incomingAmount is excluded, the creation of the subsequent quote resource must contain either a debit amount or a receive amount, discussed in the next section.

Excluding an incomingAmount means the recipient’s ASE won’t know how much to expect. As such, they won’t immediately know when a payment is complete. The client can call the Complete an Incoming Payment API to let the ASE know not to expect further payment. Otherwise, the payment session will eventually expire.

Use case: streaming Web Monetization payments

Supporting streaming Web Monetization payments is one use case for excluding an incomingAmount. The time a user spends on a web monetized site is unknown to the recipient’s ASE. Payments will stream until the session ends. The Web Monetization agent can then request to mark the incoming payment as complete. This tells the ASE that no further payments will be sent and to credit the recipient’s account.

quote

After an incoming-payment resource is created on the recipient’s account, a quote resource is typically created on the sender’s account, by way of the Create a Quote API .

The quote indicates how much it will cost, including any applicable fees, to make the payment. The quote serves as a commitment from the sender’s ASE to deliver a particular amount to the recipient’s ASE. Quotes are only valid for a limited time.

There are three types of quotes. A successfully created quote will be assigned a quoteId in the form of a URL.

Quote with incomingAmount

Use when the incoming payment resource has a defined incomingAmount. The receiver in this quote must be the URL of the incoming payment resource, indicated by /incoming-payments being part of the URL. With this quote type, the incoming payment automatically completes when the outgoing payment is complete.

Fixed-send quote

Use when the incoming payment resource excludes an incomingAmount and the sender wants to specify exactly how much to debit their account. A debitAmount is required for this type of quote. With this quote type, the incoming payment can’t automatically complete when the outgoing payment is complete. The client can issue a Complete Incoming Payment request . Otherwise, the payment session will eventually expire.

Fixed-receive quote

Use when the incoming payment resource excludes an incomingAmount and the sender wants to specify exactly how much the recipient should receive. A receiveAmount is required for this type of quote. With this quote type, the incoming payment automatically completes when the outgoing payment is complete.

outgoing-payment

Finally, an outgoing-payment resource is created on the sender’s account, by way of the Create Outgoing Payment API . An outgoing-payment resource can represent a payment that will be, is currently being, or was sent from the sender’s account. The purpose of this resource is to serve as an instruction to the sender’s ASE to make a payment.

Open Payments doesn’t execute actual payments. It only provides the instructions for the outgoing payment. This separation allows applications to issue payment requests without being registered financial service providers. Applications don’t need to handle sensitive financial data directly, reducing risk and complexity.

Open Payments requires explicit consent from the sender before the outgoing payment resource is created. Consent is obtained through an interactive grant.

The outgoing-payment resource contains the recipient’s wallet address so the sender’s ASE knows where to send the payment. If a quote resource was previously created, the outgoing-payment also contains the quoteId.

Outgoing payment without a quote ID

A quote isn’t required for all outgoing payments. If the sender doesn’t specify the amount the recipient will receive, the outgoing-payment can instead contain incomingPayment and debitAmount values. Web Monetization is a good example of this use case.

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

Grants

For information about the grant types for each resourse, refer to the Grant types section in the Authorization concepts page.