@@ -83,25 +87,29 @@ We also provide an
grant initialization request.
+Called by your IdP server to end the interaction and redirect the end-user's browser session to the URI of the
grant initialization request.
-The `result` query parameter will indicate the success or failure of the grant authorization. In case of success, the SHA-256 hash of the interaction is sent in the response along with an `interact_ref` that identifies the interaction on the authorization server and the URI of the grant initialization request.
+The `result` query parameter will indicate the success or failure of the grant authorization. When successful, the SHA-256 hash of the interaction is sent in the response along with an `interact_ref` that identifies the interaction on your authorization server and the URI of the grant initialization request.
-The following table lists examples of the possible response types on this endpoint.
+The following are examples of the possible response types.
-
+
| Response | Description | Example |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
@@ -113,16 +121,50 @@ The following table lists examples of the possible response types on this endpoi
#### Continue grant
-The client requests a grant from your authorization server for an accepted interaction. Your authorization server responds with an access token.
+Called by the client to request a grant from your authorization server if the interaction was successful (accepted). Your authorization server responds with an access token.
-## x-idp-secret header
+### x-idp-secret header
-`x-idp-secret` is the name of a header that is used for requests to the following endpoints:
+The purpose of the `x-idp-secret` header is to secure communications between your IdP and authorization servers.
+
+The header is used for requests to the following endpoints and its value should be a shared secret known to both entities.
- `GET /grant/:id/:nonce`
- `POST /grant/:id/:nonce/accept`
- `POST /grant/:id/:nonce/reject`
-The header's purpose is to secure communications between your IdP and authorization servers and its value should be a shared secret known to both entities. When your IdP server sends requests to your authorization server, your IdP must provide the secret via this header.
+When your IdP server sends requests to your authorization server, your IdP must provide the secret via this header.
To set up the header, set the [`IDENTITY_SERVER_SECRET`](#environment-variables) on your authorization server environment to a value that is also used to configure your IdP server's requests to your authorization server.
+
+### Sequence diagram
+
+The following diagram provides a high-level view of the flow from when a pending grant request is created through to the authorization server returning an access token to continue a successful (accepted) interaction.
+
+The diagram is for illustrative purposes and is not an exact representation of the flow. Additional information can be found in the Open Payments documentation.
+
+
+
+{/* prettier-ignore */}
+>Authorization Server: Sends interactive outgoing payment grant request
+ Authorization Server-->>Client: HTTP 200 request successful
+ Client->>Authorization Server: Starts user interaction session
+ Authorization Server->>Authorization Server: Sets session
+ Authorization Server-->>Client: HTTP 302 instructs client to redirect to Identity Provider
+ Client->>Identity Provider: Redirects end-user's browser to the Identity Provider's consent screen
+ Identity Provider->>Identity Provider: End-user accepts interaction
+ Identity Provider->>Authorization Server: Provides end-user's interaction choice
+ Authorization Server-->>Identity Provider: 202 HTTP choice accepted
+ Identity Provider->>Authorization Server: Instructs server to finish interaction
+ Authorization Server->>Authorization Server: Ends session
+ Authorization Server-->>Identity Provider: 302 HTTP instructs Identity Provider to redirect to client
+ Identity Provider->>Client: Redirects to Client
+ Client->>Client: Verifies hash
+ Client->>Authorization Server: Requests continuation of grant
+ Authorization Server->>Client: 200 HTTP OK, returns access token
+`}
+/>
+
+