From 49b72b4d2a83bbadbf0334b3d9d91ca0d3be2dda Mon Sep 17 00:00:00 2001 From: brad-dow <162852233+brad-dow@users.noreply.github.com> Date: Mon, 29 Jul 2024 09:15:31 -0500 Subject: [PATCH] 490 doc updates (#494) * Minor doc updates Addresses the following issues: - Remove Mojaloop mention on payment method page - Spell out all instances of OP and WM as Open Payments and Web Monetization, respectively - Minor additions and tweaks to Overview and Open Payments Concepts pages with input from Sarah's blog post https://github.com/interledger/open-payments/issues/490 Also took care of updating reference from Open Payments API to Open Payments APIs (plural, no apostrophe) https://github.com/interledger/open-payments/issues/456 * Ran prettier Forgot to run prettier on my last commit :/ * OP references corrected payment-methods.mdx wallet-get-info.mdx --------- Co-authored-by: Mohammed Islam --- .../docs/guides/create-interactive-grant.mdx | 4 +-- .../docs/guides/make-onetime-payment.mdx | 6 ++-- .../docs/guides/make-recurring-payments.mdx | 6 ++-- docs/src/content/docs/introduction/grants.mdx | 14 ++++---- .../docs/introduction/http-signatures.mdx | 8 ++--- .../content/docs/introduction/op-concepts.mdx | 24 +++++++------- .../src/content/docs/introduction/op-flow.mdx | 2 +- .../content/docs/introduction/overview.mdx | 32 +++++++++++++------ .../docs/introduction/wallet-addresses.mdx | 8 ++--- .../content/docs/resources/get-involved.mdx | 2 +- .../docs/resources/payment-methods.mdx | 6 +--- .../docs/snippets/before-you-begin.mdx | 2 +- .../content/docs/snippets/grant-create.mdx | 2 +- .../content/docs/snippets/wallet-get-info.mdx | 2 +- 14 files changed, 65 insertions(+), 53 deletions(-) diff --git a/docs/src/content/docs/guides/create-interactive-grant.mdx b/docs/src/content/docs/guides/create-interactive-grant.mdx index b8149a8a..b1c29ca6 100644 --- a/docs/src/content/docs/guides/create-interactive-grant.mdx +++ b/docs/src/content/docs/guides/create-interactive-grant.mdx @@ -50,9 +50,9 @@ Import `createAuthenticatedClient` from the Open Payments SDK package. ### 2. Create and initialize an authenticated Open Payments client -Create an OP authenticated client by providing the following properties: +Create an Open Payments-authenticated client by providing the following properties: -- `walletAddressURL`: your OP-enabled wallet address that your client will use to authenticate itself to one or more authorization servers. +- `walletAddressURL`: your Open Payments-enabled wallet address that your client will use to authenticate itself to one or more authorization servers. - `privateKey`: the EdDSA-Ed25519 key or preferably the absolute or relative file path to the key that is bound to your wallet address. A public key signed with this private key must be made available as a public JWK document at `{walletAddressUrl}/jwks.json` url. - `keyId`: the identifier of the private key and the corresponding public key. diff --git a/docs/src/content/docs/guides/make-onetime-payment.mdx b/docs/src/content/docs/guides/make-onetime-payment.mdx index b4830a34..2e34b4a3 100644 --- a/docs/src/content/docs/guides/make-onetime-payment.mdx +++ b/docs/src/content/docs/guides/make-onetime-payment.mdx @@ -8,7 +8,7 @@ import HttpSig from '/src/partials/http-msg-sig-note.mdx' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Ts from '/src/partials/ts-prerequisites.mdx' -The Open Payments (OP) API facilitates multiple uses cases for payments to and from different OP-enabled wallets. In this guide we look at the steps for making a one time payment. +The Open Payments APIs facilitate multiple uses cases for payments to and from different Open Payments-enabled wallets. In this guide we look at the steps for making a one time payment. Examples of use cases for a one-time payment might be an e-commerce or a money transmitter application. @@ -55,9 +55,9 @@ Import `createAuthenticatedClient` from the Open Payments SDK package. ### 2. Create an authenticated Open Payments client -Create an OP authenticated client by providing the following properties: +Create an Open Payments-authenticated client by providing the following properties: -- `walletAddressURL` : your OP-enabled wallet address that your client will use to authenticate itself to one or more Authorization Servers (AS). +- `walletAddressURL` : your Open Payments-enabled wallet address that your client will use to authenticate itself to one or more Authorization Servers (AS). - `privateKey` : the EdDSA-Ed25519 key or preferably the absolute or relative file path to the key that is bound to your wallet address. A public key signed with this private key must be made available as a public JWK document at `{walletAddressUrl}/jwks.json` url. - `keyId` : the identifier of the private key and the corresponding public key. diff --git a/docs/src/content/docs/guides/make-recurring-payments.mdx b/docs/src/content/docs/guides/make-recurring-payments.mdx index deef8c50..c7526ac1 100644 --- a/docs/src/content/docs/guides/make-recurring-payments.mdx +++ b/docs/src/content/docs/guides/make-recurring-payments.mdx @@ -8,7 +8,7 @@ import HttpSig from '/src/partials/http-msg-sig-note.mdx' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Ts from '/src/partials/ts-prerequisites.mdx' -The Open Payments (OP) API facilitates multiple uses cases for payments to and from different OP-enabled wallets. In this guide we look at the steps for making recurring payments. +The Open Payments APIs facilitate multiple uses cases for payments to and from different Open Payments-enabled wallets. In this guide we look at the steps for making recurring payments. An example use case for making recurring payments may be a Buy Now Pay Later (BNPL) scheme where a payer purchases a high priced item but pays for it in installments over regularly scheduled intervals. @@ -58,9 +58,9 @@ Import `createAuthenticatedClient` from the Open Payments SDK package. ### 2. Create an authenticated Open Payments client -Create an OP authenticated client by providing the following properties: +Create an Open Payments-authenticated client by providing the following properties: -- `walletAddressURL` : your OP-enabled wallet address that your client will use to authenticate itself to one or more Authorization Servers (AS). +- `walletAddressURL` : your Open Payments-enabled wallet address that your client will use to authenticate itself to one or more Authorization Servers (AS). - `privateKey` : the EdDSA-Ed25519 key or preferably the absolute or relative file path to the key that is bound to your wallet address. A public key signed with this private key must be made available as a public JWK document at `{walletAddressUrl}/jwks.json` url. - `keyId` : the identifier of the private key and the corresponding public key. diff --git a/docs/src/content/docs/introduction/grants.mdx b/docs/src/content/docs/introduction/grants.mdx index 7069d7b8..ac2e8f4c 100644 --- a/docs/src/content/docs/introduction/grants.mdx +++ b/docs/src/content/docs/introduction/grants.mdx @@ -13,7 +13,7 @@ import Interactive from '/src/partials/diagram-interactive-grant.mdx' In Open Payments, a grant indicates a transfer, or delegation, of authorization from a resource owner (RO) to a piece of software. An RO can be a physical person, such as the software’s end user, or a process, such as predefined organizational rules. By delegating authorization, the RO allows the software to access and perform operations on protected resources on the RO’s behalf. -Open Payments leverages the Grant Negotiation and Authorization Protocol (GNAP) as the mechanism by which the piece of software, known as a client instance (or client for short), is delegated authorization to use the Open Payments API to interface with supported accounts. +Open Payments leverages the Grant Negotiation and Authorization Protocol (GNAP) as the mechanism by which the piece of software, known as a client instance (or client for short), is delegated authorization to use the Open Payments APIs to interface with supported accounts. ## GNAP vs OAuth 2.0 @@ -29,7 +29,7 @@ GNAP is being developed as the successor to OAuth 2.0 and is designed to fill ma ## Grant authorization servers -An authorization server (AS) grants delegated privileges to a client in the form of access tokens. Access tokens represent a set of access rights and/or attributes granted to the client. With the requisite access token(s), the client can access a resource server’s (RS) Open Payments API and perform allowed operations, such as creating incoming payments and listing outgoing payments, on behalf of the resource owner. +An authorization server (AS) grants delegated privileges to a client in the form of access tokens. Access tokens represent a set of access rights and/or attributes granted to the client. With the requisite access token(s), the client can access a resource server’s (RS) Open Payments APIs and perform allowed operations, such as creating incoming payments and listing outgoing payments, on behalf of the resource owner. An AS is uniquely identified by its grant endpoint URI, which is an absolute URI that a client calls to initiate a grant request. @@ -41,7 +41,7 @@ A client must generate and add its key to its key registry before requesting a g ## Grant requests -Before a client can access the Open Payments API, it must send a grant request to the AS. The request must contain the type of resource it wants to work with and the action(s) it wants to take on the resource. Resource types include `incoming-payment`, `quote`, and `outgoing-payment`. The available actions depend on type, but examples include `create` and `read`. A successful grant request results in the AS returning one or more access tokens. +Before a client can access the Open Payments APIs, it must send a grant request to the AS. The request must contain the type of resource it wants to work with and the action(s) it wants to take on the resource. Resource types include `incoming-payment`, `quote`, and `outgoing-payment`. The available actions depend on type, but examples include `create` and `read`. A successful grant request results in the AS returning one or more access tokens. The sequence of requests a client makes when setting up a payment can follow one of the paths below. @@ -66,13 +66,13 @@ The sequence of requests a client makes when setting up a payment can follow one ### incoming-payment -A client begins the Open Payments flow by requesting an incoming payment grant from the AS on the _payee_ side. The client can request a single grant to create multiple incoming payments for different OP-enabled accounts as long as each account belongs to the same ASE. +A client begins the Open Payments flow by requesting an incoming payment grant from the AS on the _payee_ side. The client can request a single grant to create multiple incoming payments for different Open Payments-enabled accounts as long as each account belongs to the same ASE. Incoming payment grants are non-interactive by default, meaning interaction by an individual (typically the client’s end-user) is not required for the AS to issue an access token. ### quote -After the client receives an incoming payment grant and an incoming payment resource is created on the payee’s account, the client requests a quote grant from the AS on the _payer_ side. The client can request a single grant to create multiple quotes for different OP-enabled accounts as long as each account belongs to the same ASE. +After the client receives an incoming payment grant and an incoming payment resource is created on the payee’s account, the client requests a quote grant from the AS on the _payer_ side. The client can request a single grant to create multiple quotes for different Open Payments-enabled accounts as long as each account belongs to the same ASE. Quote grants are non-interactive by default, meaning interaction by an individual (typically the client’s end-user) is not required for the AS to issue an access token. @@ -86,9 +86,9 @@ After a successful interaction, the client must issue a [Grant Continuation requ ## Open Payments resource servers -A resource server (RS) provides the Open Payments API through which resources can be created or accessed on the server. GNAP doesn’t presume or require a tight coupling between an RS and an AS and it’s increasingly common for the servers to be run and managed separately. +A resource server (RS) provides the Open Payments APIs through which resources can be created or accessed on the server. GNAP doesn’t presume or require a tight coupling between an RS and an AS and it’s increasingly common for the servers to be run and managed separately. -Operations on the API by a client require the client to have a valid access token issued by a trusted AS. When the client uses its access token to call the RS, the RS examines the token to determine if the token is sufficient for the request. The means by which an RS makes this determination are outside of the scope of Open Payments. If the token is sufficient, the client is given the right to access the operation(s) and resource tied to the token. +Operations on the APIs by a client require the client to have a valid access token issued by a trusted AS. When the client uses its access token to call the RS, the RS examines the token to determine if the token is sufficient for the request. The means by which an RS makes this determination are outside of the scope of Open Payments. If the token is sufficient, the client is given the right to access the operation(s) and resource tied to the token. :::note An open-source implementation of an Open Payments resource server, called Rafiki, is currently in development. diff --git a/docs/src/content/docs/introduction/http-signatures.mdx b/docs/src/content/docs/introduction/http-signatures.mdx index 00ba3dd4..0b130926 100644 --- a/docs/src/content/docs/introduction/http-signatures.mdx +++ b/docs/src/content/docs/introduction/http-signatures.mdx @@ -4,13 +4,13 @@ title: HTTP message signatures import { CodeBlock, LinkOut } from '@interledger/docs-design-system' -HTTP message signatures are cryptographic digital signatures used by the Open Payments API to secure HTTP messages exchanged between sender, receiver, or third-party initiating payment systems. +HTTP message signatures are cryptographic digital signatures used by the Open Payments APIs to secure HTTP messages exchanged between sender, receiver, or third-party initiating payment systems. -The Open Payments API implements the HTTP Signatures section of the GNAP (Grant Negotiation and Authorization Protocol) specification. +The Open Payments APIs implement the HTTP Signatures section of the GNAP (Grant Negotiation and Authorization Protocol) specification. ## Purpose -The use of digital signatures allow the Open Payments API to address two key aspects of message security: +The use of digital signatures allow the Open Payments APIs to address two key aspects of message security: - **Authenticity** of any system that requests access to specific resources - **Integrity** of specific message fields to guard against message tampering @@ -19,7 +19,7 @@ Part of how Open Payments-enabled systems control access to protected resources ## Signature algorithms -To generate message signatures, the Open Payments API implements the **Ed25519** variant of the EdDSA (Edwards-curve Digital Signature Algorithm). +To generate message signatures, the Open Payments APIs implement the **Ed25519** variant of the EdDSA (Edwards-curve Digital Signature Algorithm). EdDSA is an elliptic curve cryptographic algorithm that offers advantages over previous generations of public key cryptography algorithms. The main advantages for using this digital signature algorithm include: diff --git a/docs/src/content/docs/introduction/op-concepts.mdx b/docs/src/content/docs/introduction/op-concepts.mdx index d53dcc60..ae4dce68 100644 --- a/docs/src/content/docs/introduction/op-concepts.mdx +++ b/docs/src/content/docs/introduction/op-concepts.mdx @@ -6,31 +6,31 @@ tableOfContents: import { LinkOut, CodeBlock } from '@interledger/docs-design-system' -The Open Payments (OP) standard helps to facilitate the setup of payments between OP-enabled payment accounts. +The Open Payments standard helps to facilitate the setup of payments between Open Payments-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. +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 Open Payments-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. +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 APIs 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. +Every Open Payments-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 APIs. 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](/introduction/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. +An authorization server grants permission for a client to access the Open Payments APIs 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](/introduction/grants) 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. +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 -The Open Payments API is a simple REST API with three resource types: `incoming-payment`, `quote`, and `outgoing-payment`. +The Open Payments Resource Server API is a simple REST API with three resource types: `incoming-payment`, `quote`, and `outgoing-payment`. #### incoming-payment @@ -52,8 +52,8 @@ The outgoing payment is created and funds are sent to the `incoming-payment` res 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. -:::tip[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. +:::tip[Use case: streaming Web Monetization payments] +In streaming Web Monetization payments, the maximum amount to be paid is unknown to the payee’s ASE. Payments continue to stream until the Web Monetization agent ends the session. At this point, the Web Monetization 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 @@ -74,6 +74,8 @@ A successfully created `quote` resource results in the generation of a quote `id 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 separates payment instructions from the actual execution of payments, allowing applications to issue payment requests without being registered financial service providers themselves. This structure ensures that applications don't need to handle sensitive financial data directly, reducing risk and complexity. + 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](/introduction/grants/#outgoing-payment). 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. @@ -88,9 +90,9 @@ The payment method is the means by which the payer's ASE will fulfill its paymen 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. +Though Open Payments 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 Open Payments 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. +When using ILP as a payment method in Open Payments, 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). diff --git a/docs/src/content/docs/introduction/op-flow.mdx b/docs/src/content/docs/introduction/op-flow.mdx index 7a6fbd21..4509cfb9 100644 --- a/docs/src/content/docs/introduction/op-flow.mdx +++ b/docs/src/content/docs/introduction/op-flow.mdx @@ -14,7 +14,7 @@ This page describes each step in the Open Payments flow at a high level. The seq ### Assumptions - The client's end-user is the payer. -- The client already has the payer's OP-enabled account details and is able to send payments on behalf of the payer. +- The client already has the payer's Open Payments-enabled account details and is able to send payments on behalf of the payer. ## Get account details diff --git a/docs/src/content/docs/introduction/overview.mdx b/docs/src/content/docs/introduction/overview.mdx index b73a391c..6fc01379 100644 --- a/docs/src/content/docs/introduction/overview.mdx +++ b/docs/src/content/docs/introduction/overview.mdx @@ -4,27 +4,39 @@ title: Overview import { LinkOut } from '@interledger/docs-design-system' -Open Payments is an open RESTful API and API standard that enables clients to interface with Open Payments-enabled accounts. In the context of Open Payments (OP), a client is an application, such as a mobile or web app, that consumes one or more OP resources, typically requiring access privileges from one or several authorization servers. +Handling payments is a crucial part of many online applications. Whether it's an eCommerce site selling products, a fundraising platform accepting donations, a streaming service charging for content, or a subscription service with monthly fees, digital payments are central to their operations. Many application developers rely on third-party payment gateways to handle these transactions, which can introduce additional expenses and limit control over the user experience. + +Open Payments is an open RESTful API and API standard that enables clients to interface with Open Payments-enabled accounts. In this context, a client is an application, such as a mobile or web app, that consumes one or more Open Payments resources, typically requiring access privileges from one or several authorization servers. The Open Payments standard is meant to be implemented by account servicing entities (ASEs). ASEs provide and maintain payment accounts for payers and payees, and are regulated entities within the countries they operate. Examples of ASEs include banks, digital wallet providers, and mobile money providers. -When an ASE implements Open Payments, their customers’ financial accounts become OP-enabled. Clients can then call the Open Payments API to view an OP-enabled account’s transaction history and certain account details, as well as issue instructions for receiving payments into and sending payments from the account. +## Benefits of Open Payments + +When an ASE implements Open Payments, their customers’ financial accounts become Open Payments-enabled. Clients can then call the Open Payments API to view an Open Payments-enabled account’s transaction history and certain account details, as well as issue instructions for receiving payments into and sending payments from the account. -For example, an application developer can build payments functionality into their app such that a user with an OP-enabled account can use the app to send funds to another OP-enabled account regardless of whether the recipient uses the same ASE. The app should be able to connect to any ASE that implements the Open Payments standard without the need for custom integrations. +For example, an application developer can build payments functionality into their app without the need for custom integrations with each ASE. Users with Open Payments-enabled accounts can use the app to send funds to another Open Payments-enabled account, regardless of whether the recipient uses the same ASE. This app should be able to connect to any ASE that implements the Open Payments standard without the need for custom integrations. + +The Open Payments standard simplifies integration by offering a single access point to various financial accounts, whether they are bank accounts, digital wallets, or mobile money accounts. This approach eliminates the need for multiple custom integrations, similar to how email standards facilitate seamless communication across different email providers. Refer to the [Open Payments concepts](/introduction/op-concepts) and [Open Payments flow](/introduction/op-flow) pages for additional details. +## User control and security + +With Open Payments, users remain in full control of their financial transactions. When an application uses Open Payments, it securely and cryptographically shares important information about itself with the financial instituion it interacts with. This verification ensures that the account provider knows the application is legitimate when making a payment request on your behalf. Importantly, any withdrawal of money from your account requires your explicit consent, giving you granular control over permissions and transaction limits. + ## Payments Open Payments does not execute payments or touch funds in any way. Instead, the API allows clients to issue payment instructions to ASEs. -For example, a client can instruct an ASE to send a payment of $20.00 USD from its customer’s account to another OP-enabled account at a different ASE. The sending ASE is responsible for executing and settling the payment with the receiving ASE outside of Open Payments. The ability to execute payments between OP-enabled ASEs is predicated on the availability of a common payment rail between the ASEs. +For example, a client can instruct an ASE to send a payment of $20.00 USD from its customer’s account to another Open Payments-enabled account at a different ASE. The sending ASE is responsible for executing and settling the payment with the receiving ASE outside of Open Payments. The ability to execute payments between Open Payments-enabled ASEs is predicated on the availability of a common payment rail between the ASEs. By separating payment instructions from execution/settlement, client developers can include payment functionality within their feature sets without, for example, also registering as a licensed money transfer business. ## Open Payments account identification -Every OP-enabled account is identified by one or more URLs. These URLs not only identify the account, but are also OP service endpoints that provide the entry point for the API. These URLs are called [wallet addresses](/introduction/wallet-addresses). +Every Open Payments-enabled account is identified by one or more URLs. These URLs not only identify the account, but are also Open Payments service endpoints that provide the entry point for the API. These URLs are called [wallet addresses](/introduction/wallet-addresses). + +Wallet addresses in Open Payments are designed to be user-friendly and publicly shareable. They function like email addresses, allowing for straightforward and secure interactions with accounts across various financial institutions without exposing sensitive data. ## Grant negotiation and authorization @@ -32,17 +44,17 @@ Clients must receive grants before issuing payment instructions. Grants give cli Open Payments leverages the Grant Negotiation and Authorization Protocol (GNAP) to define a standard mechanism for clients to request and receive the grants necessary to use the Open Payments API. All requests require signatures, which protect the integrity of the requests. Signatures are generated according to the HTTP Signatures specification. -GNAP makes it possible to give account holders specific and fine-grained control over the permissions they grant to the clients that connect to their accounts, including control over the amounts of transactions with time-based and velocity-based limits. This enables powerful use cases such as third-party payment initiation and delegated authorization without compromising the security of the underlying financial accounts and payment instruments. +GNAP allows account holders to have specific and fine-grained control over the permissions they grant to the clients that connect to their accounts, including control over the amounts of transactions with time-based and velocity-based limits. This enables powerful use cases such as third-party payment initiation and delegated authorization without compromising the security of the underlying financial accounts and payment instruments. Review the [Grant negotiation and authorization](/introduction/grants) page for more information. ## Relation to Open Banking -Open Payments attempts to improve upon existing Open Banking standards as defined in the UK, EU, and other jurisdictions. +Open Payments aims to improve upon existing Open Banking standards as defined in the UK, EU, and other jurisdictions. -Existing Open Banking ecosystems are dominated by aggregators and intermediaries, making it impossible for independent third-parties, such as small merchants, to use payment initiation APIs directly against their customers’ payment accounts. OP allows for scenarios where clients can dynamically register and engage with the API without needing to pre-register with the ASE. This allows for a truly distributed and federated payment ecosystem with global reach and no dependence on any particular underlying account type or settlement system. +Existing Open Banking ecosystems are dominated by aggregators and intermediaries, making it impossible for independent third-parties, such as small merchants, to use payment initiation APIs directly against their customers’ payment accounts. Open Payments allows for scenarios where clients can dynamically register and engage with the API without needing to pre-register with the ASE. This allows for a truly distributed and federated payment ecosystem with global reach and no dependence on any particular underlying account type or settlement system. -OP is also a significantly simpler standard with a small number of resource types and a more secure and powerful authorization protocol. +Open Payments is also a significantly simpler standard with a small number of resource types and a more secure and powerful authorization protocol. ## Goals @@ -53,3 +65,5 @@ When an ASE adopts the Open Payments standard, clients (applications and other p - End-users to create a new payment account for every application and/or website they use - Developers to build clients in any one programming language - ASEs and clients to create and deploy custom integrations to communicate with one another + +Open Payments aims to simplify and democratize payments by providing a standardized, easy-to-integrate solution. This reduces development effort and enhances financial inclusion by making payment solutions more affordable and accessible to all. diff --git a/docs/src/content/docs/introduction/wallet-addresses.mdx b/docs/src/content/docs/introduction/wallet-addresses.mdx index dbbab695..5bbd40d4 100644 --- a/docs/src/content/docs/introduction/wallet-addresses.mdx +++ b/docs/src/content/docs/introduction/wallet-addresses.mdx @@ -2,11 +2,11 @@ title: Wallet addresses --- -At the heart of all interactions in Open Payments (OP) is an OP-enabled account. Every OP-enabled account is identified by one or more URLs. These URLs are not only account identifiers, but also service endpoints for gaining access to the OP API. These URLs are called **wallet addresses**. Not all URLs are wallet addresses, but all wallet addresses are URLs. +At the heart of all interactions in Open Payments is an Open Payments-enabled account. Every Open Payments-enabled account is identified by one or more URLs. These URLs are not only account identifiers, but also service endpoints for gaining access to the Open Payments APIs. These URLs are called **wallet addresses**. Not all URLs are wallet addresses, but all wallet addresses are URLs. A URL is only a wallet address if the: -- Server handling the HTTP requests to the URL supports the OP protocol +- Server handling the HTTP requests to the URL supports the Open Payments protocol - URL uses the `https` protocol and has no `user-info`, `port`, `query string`, or `fragment` parts The quickest way to test if a URL is a wallet address is to make an HTTP `GET` request to the URL with an `Accept` header value of `application/json`. @@ -17,7 +17,7 @@ curl --request GET \ --header 'accept: application/json' ``` -If the URL is a wallet address, the response will provide details about the underlying OP-enabled account, including the URL of the grant request endpoint (the `authServer`). The grant request endpoint is used to get access tokens to connect to the account via the OP API. +If the URL is a wallet address, the response will provide details about the underlying Open Payments-enabled account, including the URL of the grant request endpoint (the `authServer`). The grant request endpoint is used to get access tokens to connect to the account via the Open Payments APIs. ```http HTTP/1.1 200 Success @@ -46,6 +46,6 @@ For any client, a wallet address is as good as an account. Any two distinct wall Using URLs as payment instruments solves two of the biggest issues with existing payments UX: discoverability and interaction. -URLs (universal resource locators) have been used on the web for decades to allow clients to directly locate a resource and begin interacting with it via HTTP. A wallet address is both a proxy identifier and a resource locator for the underlying account, used to access the account via the OP API and begin interactions with the account’s ASE. +URLs (universal resource locators) have been used on the web for decades to allow clients to directly locate a resource and begin interacting with it via HTTP. A wallet address is both a proxy identifier and a resource locator for the underlying account, used to access the account via the Open Payments APIs and begin interactions with the account’s ASE. Using URLs as proxies is also preferable to overloading other identifiers, such as email addresses and Mobile Station International Subscriber Directory Numbers (MSISDNs), as these proxies have no standard for interaction. As a result, identifiers like an MSISDN or email require a registry that maps the identifier to an account provider and a mechanism for governing this mapping securely. diff --git a/docs/src/content/docs/resources/get-involved.mdx b/docs/src/content/docs/resources/get-involved.mdx index f6b75dfc..28cd95b6 100644 --- a/docs/src/content/docs/resources/get-involved.mdx +++ b/docs/src/content/docs/resources/get-involved.mdx @@ -17,7 +17,7 @@ import { LinkOut } from '@interledger/docs-design-system' - Suggesting specification changes - Reporting bugs - Requesting features - - CTA for adding a new supported payment method to OP (currently only supports Interledger as a payment method.) + - CTA for adding a new supported payment method to Open Payments (currently only supports Interledger as a payment method.) - Contribute to the openapi, open-payments, and http-signature-utils packages. ## Community and hackathons diff --git a/docs/src/content/docs/resources/payment-methods.mdx b/docs/src/content/docs/resources/payment-methods.mdx index de8be018..f4e74bc3 100644 --- a/docs/src/content/docs/resources/payment-methods.mdx +++ b/docs/src/content/docs/resources/payment-methods.mdx @@ -4,7 +4,7 @@ title: Supported payment methods import { LinkOut } from '@interledger/docs-design-system' -Open Payments supports the payment methods listed below. Payment methods define the way funds are moved out of one OP-enabled account and into another. +Open Payments supports the payment methods listed below. Payment methods define the way funds are moved out of one Open Payments-enabled account and into another. ## Supported payment methods @@ -13,7 +13,3 @@ Open Payments supports the payment methods listed below. Payment methods define ILP is an open protocol suite for transferring packets of value between peers and across different payment networks or ledgers. The open architecture and minimal protocol enable interoperability for any value transfer system and is optimized for routing large volumes of low-value packets. Refer to the ILP developer documentation for more information. - -### Mojaloop - -Coming soon! diff --git a/docs/src/content/docs/snippets/before-you-begin.mdx b/docs/src/content/docs/snippets/before-you-begin.mdx index 301d8f42..1003ca3b 100644 --- a/docs/src/content/docs/snippets/before-you-begin.mdx +++ b/docs/src/content/docs/snippets/before-you-begin.mdx @@ -6,7 +6,7 @@ import { LinkOut } from '@interledger/docs-design-system' Before working with our code snippets, we recommend creating a wallet account on Rafiki.Money, a test wallet provider that's part of the Interledger testnet. -Rafiki.Money lets you create developer keys and wallet accounts, funded with play money, for making Interledger transactions via the Open Payments API. +Rafiki.Money lets you create developer keys and wallet accounts, funded with play money, for making Interledger transactions via the Open Payments APIs. ## Create an account on Rafiki.Money diff --git a/docs/src/content/docs/snippets/grant-create.mdx b/docs/src/content/docs/snippets/grant-create.mdx index 1ce7d924..36bad820 100644 --- a/docs/src/content/docs/snippets/grant-create.mdx +++ b/docs/src/content/docs/snippets/grant-create.mdx @@ -9,7 +9,7 @@ import Begin from '/src/partials/before-you-begin.mdx' import Ts from '/src/partials/ts-prerequisites.mdx' import Js from '/src/partials/js-prerequisites.mdx' -Before a client can call the Open Payments API, it must request/receive a grant from the appropriate authorization server. The request must indicate the resource type the client intends to work with and the actions the client wants to take at the resource server. +Before a client can call the Open Payments APIs, it must request/receive a grant from the appropriate authorization server. The request must indicate the resource type the client intends to work with and the actions the client wants to take at the resource server. These code snippets enable a client to request a grant for the `incoming-payment`, `quote`, and `outgoing-payment` resource types. Each request includes all valid actions the client can take for the resource type. diff --git a/docs/src/content/docs/snippets/wallet-get-info.mdx b/docs/src/content/docs/snippets/wallet-get-info.mdx index 775c7b52..72c11b5a 100644 --- a/docs/src/content/docs/snippets/wallet-get-info.mdx +++ b/docs/src/content/docs/snippets/wallet-get-info.mdx @@ -11,7 +11,7 @@ import Js from '/src/partials/js-prerequisites.mdx' For a client to request a grant from an authorization server, the client must first verify the validity of the wallet address and get the URL of the wallet's authorization server. -These code snippets enable an authenticated client to verify a wallet address, get the basic information required to construct a new transaction, and discover the auth server’s URL. Note that unauthenticated clients can also call the OP API to get wallet address information. +These code snippets enable an authenticated client to verify a wallet address, get the basic information required to construct a new transaction, and discover the auth server’s URL. Note that unauthenticated clients can also call the Open Payments API to get wallet address information. ## Before you begin