Mi/337 (#457)

* Add section on Payment Methods to Concepts * Update op-concepts.mdx * re-ran with prettier * Resolve LinkOut/prettier conflict * Update op-concepts.mdx * payment_method-complete_flow - Reworked text for payment method. - Renamed Complex Flow to Complete Flow and brought it over to the concepts page with added text and links. * trying to fix prettier error * Prettier again --------- Co-authored-by: Melissa Henderson <[email protected]>
interledger · Apr 22, 2024 · 065e4be · 065e4be
1 parent 75198e6
commit 065e4be
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 61 deletions.
diff --git a/docs/src/content/docs/introduction/op-concepts.mdx b/docs/src/content/docs/introduction/op-concepts.mdx
@@ -4,7 +4,11 @@ tableOfContents:
   maxHeadingLevel: 4
 ---
 
-import { LinkOut } from '@interledger/docs-design-system'
+import {
+  MermaidWrapper,
+  Mermaid,
+  LinkOut
+} from '@interledger/docs-design-system'
 
 The Open Payments (OP) standard helps to facilitate the setup of payments between OP-enabled payment accounts.
 
@@ -84,13 +88,73 @@ An outgoing-payment resource can represent a payment that will be, is currently
 
 ## Payment Methods
 
-While OP specifies a standard way of specifying payment instructions to ASEs, it doesn’t fulfill the payment obligations that result from the creation and consumption of OP resources. The payment method specifies the payment rails that the payee's ASE and the payer's ASE will to use to fulfill their obligations.
+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 as 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, <LinkOut href='https://interledger.org'>Interledger (ILP) </LinkOut>is the only payment method that currently integrates with OP readily.
 
 To set up ILP as a payment method in OP, the following are required:
 
-- The <LinkOut href='https://interledger.org/developers/rfcs/ilp-addresses/'>ILP address </LinkOut> 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). The `ilpAddress` field must be sent by the payee’s ASE in the `methods` object on an `incoming-payment` response.
-- Shared secret: A cryptographically secured secret exchanged between the sender and receiver to ensure that packets sent over the Interledger network through a <LinkOut href='https://interledger.org/developers/rfcs/stream-protocol/'>STREAM</LinkOut> connection can only be read by the two parties. The payee’s ASE must return the `sharedSecret` field in the `methods` object on an `incoming-payment` response.
-- The payee's ASE must return the value `ilp` in the `type` field of the `methods` object on an `incoming-payment` response.
-- The payer's ASE must send the value `ilp` in the `method` field when creating a `quote`.
+- The <LinkOut href='https://interledger.org/developers/rfcs/ilp-addresses/'>ILP address</LinkOut> 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). The `ilpAddress` must be sent by the payee’s ASE in the `incoming-payment.methods` object.
+- Shared secret: A cryptographically secured secret exchanged between the sender and receiver to ensure that packets sent over the Interledger network through a <LinkOut href='https://interledger.org/developers/rfcs/stream-protocol/'>STREAM</LinkOut> connection can only be read by the two parties. The payee’s ASE must return a `sharedSecret` in the `incoming-payment.methods` object to initiate a STREAM connection.
+
+* The payee's ASE must return `ilp` in the `incoming-payment.methods.type` field.
+* The payer's ASE must send `ilp` in the `quote.method` field.
+
+## Complete flow
+
+We bring the aforementioned concepts together and present them visually in the following sequence diagram. Note that this diagram represents an overview of a complete OP transaction life cycle from an `incoming-payment` grant request to an `outgoing-payment`. Thus, it may be missing details for a particular flow. For more details please see the [Open Payments Flow](/introduction/op-flow) page.
+
+In order to facilitate OP payments, both the payer's ASE and the payee's ASE need to operate their own authorization and resource servers. The client will obtain requisite grants from the authorization servers and create the subsequent resources on the resource servers as necessary. As the creation of the `outgoing-payment` requires explicit consent from the payer (i.e. the client's end-user), the client will issue a redirect to the payer's Identity Provider to obtain the payer's consent. Please see the [GNAP](/introduction/grants) page for more information.
+
+<MermaidWrapper client:load>
+
+<Mermaid
+  graph={`sequenceDiagram
+    participant IP as Identity Provider
+    actor Cu as Payer
+    participant A2 as Payer-side Auth Server
+    participant R2 as Payer-side Resource Server
+    participant R1 as Payee-side Resource Server
+    participant A1 as Payee-side Auth Server
+    participant Cl as Client
+
+    activate Cl
+    Cl->>+A1: incoming payment grant request
+    A1->>-Cl: grant + access token
+    Cl->>+R1: incoming payment creation request
+    R1->>+A1: token introspection
+    A1->>-R1: token valid + grant details
+    R1->>-Cl: incoming payment
+    rect rgba(0, 0, 255, .1)
+    Cl->>+Cu: request wallet address
+    Cu->>Cl: wallet address
+    end
+    Cl->>+R2: query customer's wallet address
+    R2->>-Cl: wallet address details including auth server endpoint
+    Cl->>+A2: quote grant request
+    A2->>-Cl: grant + access token
+    Cl->>+R2: quote creation request
+    R2->>+A2: token introspection
+    A2->>-R2: token valid + grant details
+    R2->>-Cl: quote
+    Cl->>+A2: outgoing payment grant request
+    A2->>-Cl: IdP redirect info
+    rect rgba(0, 0, 255, .1)
+    Cl->>IP: redirect to IdP
+    IP->>Cu: consent to grant request
+    Cu->>IP: consent given
+    Cu->>-Cl: interaction finished
+    end
+    Cl->>+A2: continue grant request
+    A2->>-Cl: grant + access token
+    Cl->>+R2: outgoing payment creation request
+    R2->>+A2: token introspection
+    A2->>-R2: token valid + grant details
+    R2->>R2: grant accounting
+    R2->>-Cl: outgoing payment
+    deactivate Cl
+
+`}
+/>
+
+</MermaidWrapper>
diff --git a/docs/src/content/docs/introduction/op-flow.mdx b/docs/src/content/docs/introduction/op-flow.mdx
@@ -147,58 +147,3 @@ Similarly, the client can provide the end-user with details about a specific <Li
 />
 
 </MermaidWrapper>
-
-## Complex flow
-
-<MermaidWrapper client:load>
-
-<Mermaid
-  graph={`sequenceDiagram
-    participant IP as Identity Provider
-    participant Cu as Payer
-    participant A2 as Payer-side Auth Server
-    participant R2 as Payer-side Resource Server
-    participant R1 as Payee-side Resource Server
-    participant A1 as Payee-side Auth Server
-    participant Cl as Client
-
-    activate Cl
-    Cl->>+A1: incoming payment grant request
-    A1->>-Cl: grant + access token
-    Cl->>+R1: incoming payment creation request
-    R1->>+A1: token introspection
-    A1->>-R1: token valid + grant details
-    R1->>-Cl: incoming payment
-    rect rgba(0, 0, 255, .1)
-    Cl->>+Cu: request wallet address
-    Cu->>Cl: wallet address
-    end
-    Cl->>+R2: query customer's wallet address
-    R2->>-Cl: wallet address details including auth server endpoint
-    Cl->>+A2: quote grant request
-    A2->>-Cl: grant + access token
-    Cl->>+R2: quote creation request
-    R2->>+A2: token introspection
-    A2->>-R2: token valid + grant details
-    R2->>-Cl: quote
-    Cl->>+A2: outgoing payment grant request
-    A2->>-Cl: IdP redirect info
-    rect rgba(0, 0, 255, .1)
-    Cl->>IP: redirect to IdP
-    IP->>Cu: consent to grant request
-    Cu->>IP: consent given
-    Cu->>-Cl: interaction finished
-    end
-    Cl->>+A2: continue grant request
-    A2->>-Cl: grant + access token
-    Cl->>+R2: outgoing payment creation request
-    R2->>+A2: token introspection
-    A2->>-R2: token valid + grant details
-    R2->>R2: grant accounting
-    R2->>-Cl: outgoing payment
-    deactivate Cl
-
-`}
-/>
-
-</MermaidWrapper>