docs: mi/547/update-sender-recipient #576
Conversation
- Updated payer/payee references to sender/recipient where contextually appropriate - Fix typos picked up by Vale
|
✅ Deploy Preview for openpayments-preview ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
|
||
| For details on how to facilitate an interactive grant please see the <LinkOut href='https://openpayments.dev/guides/create-interactive-grant/'> | ||
| For details on how to facilitate an interactive grant refer the <LinkOut href='https://openpayments.dev/guides/create-interactive-grant/'> |
There was a problem hiding this comment.
Missing "to". "...refer to the..."
|
|
||
| ## 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 APIs and perform allowed operations, such as creating incoming payments and listing outgoing payments, on behalf of the resource owner. | ||
| An authorization server 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 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. |
| @@ -4,15 +4,15 @@ title: Hash verification | |||
|
|
|||
| import { CodeBlock, LinkOut, Tooltip } from '@interledger/docs-design-system' | |||
|
|
|||
| Once a resource owner (RO) authorizes a client software, the authorization server (AS) will redirect the RO's [identity provider (IdP)](/introduction/idp/) to the finish URI if the client had provided an `interact.finish` object in the intial request. In order to secure this communication and verify that the redirect indeed emanated from the AS, the AS will provide a hash parameter in the request to the client's callback URI. The client **_must_** verify this hash. | |||
| Once a resource owner authorizes a client software, the authorization server will redirect the resource owner's [identity provider (IdP)](/introduction/idp/) to the finish URI if the client had provided an `interact.finish` object in the initial request. In order to secure this communication and verify that the redirect indeed emanated from the authorization server, the authorization server will provide a hash parameter in the request to the client's callback URI. The client **_must_** verify this hash. | |||
There was a problem hiding this comment.
There's a merge conflict on this because I just recently changed this paragraph. I think you can resolve the conflict by either undoing your changes or just copy/paste from the live doc.
|
|
||
| ## Hashing method | ||
|
|
||
| The hash base is generated by concatentating the following values in sequence using a single newline `(/n)` character to separate them: | ||
| The hash base is generated by concatenating the following values in sequence using a single newline `(/n)` character to separate them: |
There was a problem hiding this comment.
I also caught this, but it's the same change I made, so it's probably not causing a conflict.
| - **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. | ||
| After a quote resource is created, it’s almost time to create the outgoing-payment resource on the sender's account. The purpose of the outgoing-payment resource is to serve as an instruction to make a payment from the sender's account. |
There was a problem hiding this comment.
Add code format to outgoing-payment x2
There's a number of instances in this section where the resource name needs to be code
| @@ -59,15 +60,15 @@ The client first <LinkOut href='/apis/auth-server/operations/post-request'>reque | |||
|
|
|||
| ## Quote | |||
|
|
|||
| The client <LinkOut href='/apis/auth-server/operations/post-request'>requests/receives a grant</LinkOut> from the end-user's authorization server to create a `quote` resource. The client then sends a request to the end-user's resource server to <LinkOut href='/apis/resource-server/operations/create-quote'>create the resource</LinkOut>. When created, the resource server returns, among other things, a quote `id` and the amount it will cost to make the payment. | |||
| The client <LinkOut href='/apis/auth-server/operations/post-request'>requests/receives a grant</LinkOut> from the authorization server of the sender's <Tooltip content="Account servicing entity" client: load><span>ASE</span></Tooltip> to create a `quote` resource. The client then sends a request to the resource server to <LinkOut href='/apis/resource-server/operations/create-quote'>create the resource</LinkOut>. When created, the resource server returns, among other things, a quote `id` and the amount it will cost to make the payment. | |||
|
|
|||
| <MermaidWrapper client:load> | |||
|
|
|||
| <Mermaid | |||
| graph={`sequenceDiagram | |||
| participant C as Client instance | |||
There was a problem hiding this comment.
We use both Client and Client instance as a participant in the diagrams. I'm pretty sure the inconsistency is my fault 😕 Can you change them all to just Client?
| @@ -14,7 +14,7 @@ Before a client can call the Open Payments APIs, it must request and receive a g | |||
| 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. | |||
|
|
|||
| :::note | |||
| When setting up a payment, the client first requests a grant from the recipient's (payee's) authorization server to create an `incoming-payment` resource. The client then requests grants to create the `quote` and `outgoing-payment` resources from the sender's (payer's) authorization server. | |||
| When setting up a payment, the client first requests a grant from the authorization server of the recipient's <Tooltip content="Account servicing entity" client: load><span>ASE</span></Tooltip> to create an `incoming-payment` resource. The client then requests grants to create the `quote` and `outgoing-payment` resources from the authorization server of the sender's ASE. | |||
There was a problem hiding this comment.
Given that the sentence above the note specifies incoming-payment, quote, and outgoing-payment resource types, what do you think about this:
When setting up a payment, the client first requests an incoming payment grant from the authorization server of the recipient's ASE. Then, the client requests quote and outgoing payment grants from the authorization server of the sender's ASE.
Just a suggestion.
| 4. Send request to create a quote resource to the payer's RS | ||
| 5. Request an interactive `outgoing-payment` grant from the payer's AS | ||
| 6. Send request to create an outgoing payment resource to the payer's RS | ||
| 1. Request an `incoming-payment` grant from the authorization server of recipient's <Tooltip content="Account servicing entity" client: load><span>ASE</span></Tooltip> |
There was a problem hiding this comment.
I've spent some time looking at this path and path 2. By spelling out authorization server and resource server, and by better indicating who the server belongs to, I think it makes the sentences too complex. In these specific instances, it's a case of something sounding good in theory but ending up not so good after execution.
What do you think about this format for the paths?
- Request an incoming-payment grant from the recipient-side authorization server.
- Send request to create an incoming-payment resource to the recipient-side resource server.
- Request a quote grant from the sender-side authorization server.
- Etc...
Updated payer/payee references to sender/recipient where contextually appropriate
Fix typos picked up by Vale