Skip to content

docs: mi/520/split-payments #558

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hajjimo merged 8 commits into from
May 2, 2025
Merged

docs: mi/520/split-payments #558

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f2f6803
docs: mi/520/split-payments
hajjimo Mar 4, 2025
7d46b83
docs: mi/520/split-payments
hajjimo Mar 17, 2025
75787cd
docs: mi/520/split-payments
hajjimo Apr 10, 2025
308d1b9
mi/520/split-payments
hajjimo Apr 16, 2025
2b72c99
docs: mi/520/split-payments
hajjimo Apr 16, 2025
d3246a9
Merge branch 'main' into mi/520/split-payments
melissahenderson Apr 17, 2025
3a4f223
docs: finalizing guide
melissahenderson Apr 23, 2025
e6c0585
docs: mi/520/split-payments
hajjimo May 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 3 additions & 9 deletions docs/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,16 +229,10 @@ export default defineConfig({
{
label: 'Make recurring payments',
link: '/guides/make-recurring-payments/'
}
]
},
{
label: 'Tutorials',
collapsed: true,
items: [
},
{
label: 'Create a split-payments application',
link: '/tutorials/split-payments/'
label: 'Split an incoming payment',
link: '/guides/split-payments/'
}
]
},
Expand Down
49 changes: 9 additions & 40 deletions docs/src/content/docs/guides/make-onetime-payment.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,11 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'
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'
import StartInteraction from '/src/partials/grant-start-interaction.mdx'
import FinishInteraction from '/src/partials/grant-finish-interaction.mdx'

:::tip[Summary]
A client can support one-time payments by obtaining the necessary grants and calling the Open Payments APIs to create the incoming payment, quote, and outgoing payment resources.
Add support for one-time payments to your client. A one-time payment is a single, non-recurring payment.
:::

The Open Payments APIs facilitate multiple use cases for one-time payments to and from Open Payments-enabled wallets. Making a payment directly from one person to another, called a peer-to-peer payment, is one example. Purchasing an item from an online merchant and paying in full is another example.
Expand Down Expand Up @@ -143,42 +145,17 @@ Now indicate your client can receive a signal from the authorization server when

### 7. Start interaction with the user

Once your client receives the authorization server’s response, it must send the user to the `interact.redirect` URI contained in the response. This starts the interaction flow.

The response also includes a `continue` object, which is essential for managing the interaction and obtaining explicit user consent for outgoing payment grants. The `continue` object contains an access token and a URI that the client will use to finalize the grant request after the user has completed their interaction with the identity provider (IdP). This ensures that the client can securely obtain the necessary permissions to proceed with the payment process.

<CodeBlock title="Example response">
```json
{
"interact": {
"redirect": "https://auth.interledger-test.dev/4CF492MLVMSW9MKMXKHQ",
"finish": "4105340a-05eb-4290-8739-f9e2b463bfa7"
},
"continue": {
"access_token": {
"value": "33OMUKMKSKU80UPRY5NM"
},
"uri": "https://auth.interledger-test.dev/continue/4CF492MLVMSW9MKMXKHQ",
"wait": 30
}
}
```
</CodeBlock>
<StartInteraction />

### 8. Finish interaction with the user

The user interacts with the authorization server through the server’s interface and approves or denies the grant.

Provided the user approves the grant, the authorization server:

- Sends the user to your client’s previously defined `finish.uri`. The means by which the server sends the user to the URI is out of scope, but common options include redirecting the user from a web page and launching the system browser with the target URI.
- Secures the redirect by adding a unique hash, allowing your client to validate the `finish` call, and an interaction reference as query parameters to the URI.
<FinishInteraction />

### 9. Request a grant continuation

After the user completes their interaction with the identity provider (IdP), they should be redirected back to your application. At this point, you can make the grant continuation request. In scenarios where a user interface is not available, consider implementing a polling mechanism to check for the completion of the interaction.
After the user completes their interaction with the identity provider (IdP), they should be redirected back to your application. Now you can make the grant continuation request. In scenarios where a user interface is not available, consider implementing a polling mechanism to check for the completion of the interaction.

Add the authorization server’s interaction reference, as the `interact_ref` value, to the body of your continuation request.
Add the authorization server’s interaction reference as the `interact_ref` value to the body of your continuation request.

<ChunkedSnippet
source='https://raw.githubusercontent.com/interledger/open-payments-snippets/main/grant/grant-continuation.ts'
Expand All @@ -191,8 +168,7 @@ Issue the request to the `continue uri` supplied in the authorization server’s

A successful continuation response from the authorization server provides your client with an access token and other information necessary to continue the transaction.

<CodeBlock title="Example response">
```json wrap
```json title="Example response" wrap
{
"access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
Expand All @@ -201,13 +177,7 @@ A successful continuation response from the authorization server provides your c
"access": [
{
"type": "outgoing-payment",
"actions": [
"create",
"read",
"read-all",
"list",
"list-all"
],
"actions": ["create", "read", "read-all", "list", "list-all"],
"identifier": "https://ilp.interledger-test.dev/alice",
"limits": {
"receiver": "https://ilp.interledger-test.dev/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2",
Expand All @@ -230,7 +200,6 @@ A successful continuation response from the authorization server provides your c
}
}
```
</CodeBlock>

### 10. Create an Outgoing Payment

Expand Down
49 changes: 9 additions & 40 deletions docs/src/content/docs/guides/make-recurring-payments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,11 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'
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'
import StartInteraction from '/src/partials/grant-start-interaction.mdx'
import FinishInteraction from '/src/partials/grant-finish-interaction.mdx'

:::tip[Summary]
A client can support recurring payments by obtaining the necessary grants and calling the Open Payments APIs to create the incoming payment, quote, and multiple outgoing payment resources.
Add support for recurring payments to your client. A recurring payment requires the sender's authorization once, then automatically pays out at regular intervals.
:::

The Open Payments APIs facilitate multiple use cases for recurring payments to and from Open Payments-enabled wallets. Buy Now Pay Later (BNPL) is one example, where a purchaser pays for an item in installments over regularly scheduled intervals.
Expand Down Expand Up @@ -150,42 +152,17 @@ Now indicate your client can receive a signal from the authorization server when

### 7. Start interaction with the user

Once your client receives the authorization server’s response, it must send the user to the `interact.redirect` URI contained in the response. This starts the interaction flow.

The response also includes a `continue` object, which is essential for managing the interaction and obtaining explicit user consent for outgoing payment grants. The `continue` object contains an access token and a URI that the client will use to finalize the grant request after the user has completed their interaction with the identity provider (IdP). This ensures that the client can securely obtain the necessary permissions to proceed with the payment process.

<CodeBlock title="Example response">
```json
{
"interact": {
"redirect": "https://auth.interledger-test.dev/4CF492MLVMSW9MKMXKHQ",
"finish": "4105340a-05eb-4290-8739-f9e2b463bfa7"
},
"continue": {
"access_token": {
"value": "33OMUKMKSKU80UPRY5NM"
},
"uri": "https://auth.interledger-test.dev/continue/4CF492MLVMSW9MKMXKHQ",
"wait": 30
}
}
```
</CodeBlock>
<StartInteraction />

### 8. Finish interaction with the user

The user interacts with the authorization server through the server’s interface and approves or denies the grant.

Provided the user approves the grant, the authorization server:

- Sends the user to your client’s previously defined `finish.uri`. The means by which the server sends the user to the URI is out of scope, but common options include redirecting the user from a web page and launching the system browser with the target URI.
- Secures the redirect by adding a unique hash, allowing your client to validate the `finish` call, and an interaction reference as query parameters to the URI.
<FinishInteraction />

### 9. Request a grant continuation

After the user completes their interaction with the identity provider (IdP), they should be redirected back to your application. At this point, you can make the grant continuation request. In scenarios where a user interface is not available, consider implementing a polling mechanism to check for the completion of the interaction.
After the user completes their interaction with the identity provider (IdP), they should be redirected back to your application. Now you can make the grant continuation request. In scenarios where a user interface is not available, consider implementing a polling mechanism to check for the completion of the interaction.

Add the authorization server’s interaction reference, as the `interact_ref` value, to the body of your continuation request.
Add the authorization server’s interaction reference as the `interact_ref` value to the body of your continuation request.

<ChunkedSnippet
source='https://raw.githubusercontent.com/interledger/open-payments-snippets/main/grant/grant-continuation.ts'
Expand All @@ -198,8 +175,7 @@ Issue the request to the `continue uri` supplied in the authorization server’s

A successful continuation response from the authorization server provides your client with an access token and other information necessary to continue the transaction.

<CodeBlock title="Example response">
```json wrap
```json title="Example response" wrap
{
"access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
Expand All @@ -208,13 +184,7 @@ A successful continuation response from the authorization server provides your c
"access": [
{
"type": "outgoing-payment",
"actions": [
"create",
"read",
"read-all",
"list",
"list-all"
],
"actions": ["create", "read", "read-all", "list", "list-all"],
"identifier": "https://ilp.interledger-test.dev/alice",
"limits": {
"receiver": "https://ilp.interledger-test.dev/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2",
Expand All @@ -237,7 +207,6 @@ A successful continuation response from the authorization server provides your c
}
}
```
</CodeBlock>

### 10. Create an initial Outgoing Payment

Expand Down
Loading