You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* docs: update outgoing grant guide
Update guide to more closely follow the new format introduced with the Split Payment guide revisions.
Summary:
* Revised intro
* Added Scenario heading
* Removed Dependencies section
* Other wording updates
* Added example responses
* Minor updates to some existing TS examples
* docs: added badges to guide
* docs: add token expiry note
@@ -12,25 +12,29 @@ import FinishInteraction from '/src/partials/grant-finish-interaction.mdx'
12
12
Learn how to get an outgoing payment grant for future payments without specifying any recipients.
13
13
:::
14
14
15
-
Often, a transaction will start with the client getting the recipient's details and asking the recipient's ASE for permission to send money. However, Open Payments also supports a different approach, where the client gets permission from the sender's ASE to send money before knowing who the recipient will be. Web Monetization's pay-as-you-browse model uses this approach.
15
+
Often, a transaction starts with the client getting the payment recipient's details and asking the recipient's ASE for permission to send money. However, Open Payments also supports a different approach: the client gets permission from the sender's ASE to send money before knowing who the recipient will be. Web Monetization's pay-as-you-browse model uses this approach.
16
16
17
-
In this model, a user installs a browser extension and visits a web monetized site. The extension uses Open Payments to issue continuous outgoing payments to the site, on behalf of the user, for as long as the user is on the site. The extension has no idea who the recipient will be until the user visits the site.
17
+
**Real-life use case: Web Monetization browser extension**
18
18
19
-
Setting up the extension requires the user to connect it to their wallet account. They specify a maximum amount they're willing to spend and select whether the amount should renew monthly. The extension then receives an outgoing payment grant from the user's wallet provider, allowing the extension to initiate future payments.
19
+
The Web Monetization extension uses Open Payments to issue continuous outgoing payments to a web monetized site. The payments are issued on behalf of the user for as long as the user is on the site. The extension has no idea who the recipient will be until the user visits the site.
20
20
21
-
In this guide, you'll assume the role of an app developer. The guide takes you through the steps your app will perform to receive an outgoing payment grant with a specified debit amount but no known recipients. The example scenario illustrates how to allow your app's user to send payments of up to $100 CAD a month for three months.
21
+
Setting up the extension requires the user to connect it to their wallet account. They specify a maximum amount they're willing to spend and select whether the amount should automatically renew each month. The extension then receives an outgoing payment grant from the user's wallet provider, allowing the extension to initiate future payments.
22
+
23
+
## Scenario
24
+
25
+
For this guide, you'll assume the role of an app developer. The guide explains how to allow your app's user to send payments of up to $100 CAD a month for three months without specifying a recipient beforehand.
Let's assume your user saved their wallet address in their account profile when setting up your app. Call the [Get Wallet Address API](/apis/wallet-address-server/operations/get-wallet-address) to get required details about your user's wallet account.
37
+
Let's assume your user saved their wallet address in their account profile when setting up your app. Call the <Badgetext="GET"variant="note" /> [Get Wallet Address API](/apis/wallet-address-server/operations/get-wallet-address).
Use the authorization server information received in the previous step to call the [Grant Request API](/apis/auth-server/operations/post-request). The purpose of this call is to obtain a token that allows your client to request outgoing payment resources be created on your user's wallet account.
62
+
### 2. Request an interactive outgoing payment grant
48
63
49
-
<InteractionReq />
64
+
Use the authorization server information received in the previous step to call the <Badgetext="POST"variant="success" /> [Grant Request API](/apis/auth-server/operations/post-request).
50
65
51
-
In addition to any required parameters, include the following in the request:
66
+
This call obtains a token that allows your app to request outgoing payment resources be created on your user's wallet account.
52
67
53
-
-`limits` object
54
-
-`debitAmount` - The maximum amount that your user can send per interval. When the next interval begins, the value resets.
55
-
-`interval` - The [time interval](#about-the-interval) under which the grant is valid.
68
+
<InteractionReq />
56
69
57
-
Your user indicates they want to make payments of up to $100 CAD a month for three months. The amount resets each month and any unspent portions don't roll over.
70
+
Remember, your user wants to send payments of up to $100 CAD a month for three months. The amount resets each month and any unspent portions don't roll over.
uri: 'https://paymentplatform.example/finish/{...}', // where to redirect the user to after they've completed the interaction
90
103
nonce: NONCE,
91
104
},
92
105
},
@@ -96,14 +109,34 @@ Your user indicates they want to make payments of up to $100 CAD a month for thr
96
109
</TabItem>
97
110
</Tabs>
98
111
112
+
113
+
<details>
114
+
<summary>Example response</summary>
115
+
```json wrap
116
+
{
117
+
"interact": {
118
+
"redirect": "https://auth.interledger-test.dev/{...}", // uri to redirect the user to, to begin interaction
119
+
"finish": "..."// unique key to secure the callback
120
+
},
121
+
"continue": {
122
+
"access_token": {
123
+
"value": "..."// access token for continuing the outgoing payment grant request
124
+
},
125
+
"uri": "https://auth.interledger-test.dev/continue/{...}", // uri for continuing the outgoing payment grant request
126
+
"wait": 30
127
+
}
128
+
}
129
+
```
130
+
</details>
131
+
99
132
#### About the interval
100
133
101
-
The interval used in this guide is `R3/2025-05-20T13:00:00Z/P1M`. Remember that your user wants to send payments up to $100 CAD a month for three months. The interval breaks down like this:
134
+
The interval used in this guide is `R3/2025-05-20T13:00:00Z/P1M`. Your user wants to send payments up to $100 CAD a month for three months. The interval breaks down like this:
102
135
103
136
-`R3/` is the number of repetitions - three.
104
137
-`2025-05-20` is the start date of the repeating interval - 20 May 2025
105
138
-`T13:00:00Z/` is the start time of the repeating interval - 1:00 PM UTC.
106
-
-`P1M` is the period between each interval - one month. Used with `R3`, you have a grant that's valid once a month for three months.
139
+
-`P1M` is the period between each interval - one month. Used with `R3/`, you have a grant that's valid once a month for three months.
107
140
108
141
Altogether, your user can send up to $100 CAD from:
109
142
@@ -121,28 +154,61 @@ Altogether, your user can send up to $100 CAD from:
121
154
122
155
### 5. Request a grant continuation
123
156
124
-
In this guide, we're assuming the IdP has a user interface with which your user interacts. When the interaction completes, your user is directed back to your app. Now the client can make a grant continuation request.
157
+
In our example, we're assuming the IdP the user interacted with has a user interface. When the interaction completes, your user is directed back to your app. Now the client can make a grant continuation request.
125
158
126
159
:::note
127
160
In a scenario where a user interface isn't available, consider implementing a polling mechanism to check for the completion of the interaction.
128
161
:::
129
162
130
-
Add the `interact_ref` returned in the redirect URI's query parameters.
163
+
Call the <Badgetext="POST"variant="success" /> [Grant Continuation Request API](/apis/auth-server/operations/post-continue/). This call requests an access token that allows your app to request outgoing payment resources be created on the user's wallet account.
164
+
165
+
Issue the request to the `continue.uri` provided in the initial outgoing payment grant response (Step 2).
166
+
167
+
Include the `interact_ref` returned in the redirect URI's query parameters.
A successful response provides your app with an access token. Now your app can issue outgoing payment requests to future recipients against the grant. Each request must reference the access token.
186
+
187
+
<details>
188
+
<summary>Example response</summary>
189
+
```json wrap
190
+
{
191
+
"access_token": {
192
+
"value": "...", // final access token required before creating outgoing payments
193
+
"manage": "https://auth.cloudninebank.example.com/token/{...}", // management uri for access token
"value": "..."// access token for continuing the request
205
+
},
206
+
"uri": "https://auth.cloudninebank.example.com/continue/{...}"// continuation request uri
207
+
}
208
+
}
209
+
```
210
+
</details>
211
+
212
+
:::note[Access token expiry]
213
+
If an outgoing payment request fails because the grant's access token has expired, you can call the <Badgetext="POST"variant="success" /> [Rotate Access Token API](/apis/auth-server/operations/post-token/), then use the new token in the outgoing payment request.
Copy file name to clipboardExpand all lines: docs/src/content/docs/sdk/before-you-begin.mdx
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -82,11 +82,11 @@ Before you can initialize an authenticated Open Payments client, you must obtain
82
82
<imgsrc='/img/snippets/tw-dev-keys-tab.png'alt='Developer keys tab with account expanded, showing the upload key and the generate public and private key buttons'class='img-outline'style='max-width:400px'/>
83
83
4. Click **Generate public & private key**.
84
84
5. Enter any **nickname** for the key pair, then click **Generate keys**. A file named `private.key` automatically downloads to your machine
85
-
85
+
86
86
<imgsrc='/img/snippets/tw-generate-key-pair.png'alt='Generate public and private key screen with nickname field'class='img-outline'style='max-width:400px'/>
6. Click **Close**. Your key ID appears on the screen, along with a **Show/Hide** option for your public key.
91
91
<imgsrc='/img/snippets/tw-key-id.png'alt='Developer keys tab with account expanded, showing the newly generated key id and an option to show the public key'class='img-outline'style='max-width:400px'/>
Outgoing payments require an interactive grant. This type of grant will obtain the customer's consent before an outgoing payment is made against their wallet account. You can find more information in the [Open Payments flow](/concepts/op-flow/#outgoing-payment) and [identity providers](/identity/idp) pages.
2
+
Outgoing payments require an interactive grant. This type of grant will obtain the resource owner's consent before an outgoing payment is made against their wallet account. You can find more information in the [Open Payments flow](/concepts/op-flow/#outgoing-payment) and [identity providers](/identity/idp) pages.
0 commit comments