Skip to content

Commit

Permalink
docs: general updates (#402)
Browse files Browse the repository at this point in the history 
Minor content updates to resolve various notes and to-do lists I have on my desk
  • Loading branch information
@melissahenderson
melissahenderson committed Dec 14, 2023
1 parent 811251f commit 7485da7
Show file tree
Hide file tree
Showing 4 changed files with 48 additions and 42 deletions.
41 changes: 24 additions & 17 deletions docs/src/content/docs/introduction/op-concepts.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
---
title: Open Payments concepts
tableOfContents:
maxHeadingLevel: 4
---

The Open Payments (OP) standard helps to facilitate the setup of payments between OP-enabled payment accounts.

When setting up a payment, the client must obtain the wallet addresses for both the payer's (typically the client's end-user) and payee's OP-enabled accounts. The client can choose to collect and store the payer's wallet address during onboarding, for example.
When setting up a payment, the client must obtain the wallet address for both the payer's and payee's OP-enabled account. The payer is typically the client's end-user, and the client can choose to collect and store the payer's wallet address during onboarding, for example.

After the requisite wallet addresses are known, the client can begin obtaining grants to set up one or more payments. The grants allow the client to access the Open Payments API for the purpose of creating and accessing resources for incoming payments, quotes, and outgoing payments.

## Wallet address
## Wallet address server

Every OP-enabled account is identified by one or more wallet addresses. A wallet address is a publicly shareable account identifier and a service endpoint for gaining access to the Open Payments API. The payer and payee must both have a wallet address to transact using Open Payments.

For more information, visit the [wallet addresses](/introduction/wallet-addresses) page.
A wallet address server provides basic details about a wallet address. For more information, visit the [wallet addresses](/introduction/wallet-addresses) page.

## Authorization server

Expand All @@ -26,28 +28,33 @@ The Open Payments API is served by a resource server. Operations on the API requ

### Resource types

The Open Payments API is a simple REST API with four resource types:
The Open Payments API is a simple REST API with three resource types: `incoming-payment`, `quote`, and `outgoing-payment`.

- wallet address, discussed [above](#wallet-address)
- [incoming-payment](#incoming-payment)
- [quote](#quote)
- [outgoing payment](#outgoing-payment)

#### Incoming-payment
#### incoming-payment

The first resource to be created when setting up a payment is the `incoming-payment` resource, created on the payee’s account. When created, the payee’s ASE returns unique payment details to the client that can be used to address payments to the account. Any payments received using these details are then associated with the `incoming-payment` resource.

It’s possible for an `incoming-payment` resource to be created without specifying an `incomingAmount`. When this occurs, the client can issue a request to manually complete the incoming payment to indicate no further payments will be sent.
A client can issue requests to get an incoming payment’s specific details, as well as list all incoming payments in order to, for example, provide the end-user with transaction details and history.

**Create an incoming payment without specifying an `incomingAmount`**

When a request to create an `incoming-payment` resource includes an `incomingAmount`, the `incomingAmount` is the maximum amount to pay into the payee's account. In other words, it's the amount that the payee should receive.

Instead of specifying the amount to be received, you can specify how much you want to send by:

A client can also issue requests to get an incoming payment’s specific details and list all incoming payments in order to, for example, provide the end-user with transaction details and history.
1. Excluding the `incomingAmount` in the request
2. Including a `debitAmount` of the amount you want to send within a [Create Quote](#quote) request (referred to as a fixed-send quote)
3. Creating an outgoing payment request that includes the `quoteId` of the above quote

Manually completing an incoming payment
The outgoing payment is created and funds are sent to the `incoming-payment` resource. However, the `incomingAmount` was never set, so there's no indicator on the payee's side for how much to expect. The payee's ASE won't know when the payment has completed.

The optional `incomingAmount` object in a [Create Incoming Payment](/apis/resource-server/operations/create-incoming-payment) request is used to specify the maximum amount to pay into the wallet address under the incoming payment.
Instead of waiting for the payment session to expire, the client can issue an explicit request to manually [complete the incoming payment](/apis/resource-server/operations/complete-incoming-payment) to indicate no further payments will be sent.

Streaming Web Monetization (WM) payments is one use case for _not_ specifying an `incomingAmount`. In streaming WM payments, the maximum amount to be paid is unknown to the payee’s ASE. Payments continue to stream until the WM agent ends the session. At this point, the WM agent can request to mark the incoming payment as [complete](/apis/resource-server/operations/complete-incoming-payment). This enables the payee’s ASE to be notified as soon as possible that no further payments will be sent and to credit the payee’s account.
:::tip[Use case: streaming Web Monetization (WM) payments]
In streaming WM payments, the maximum amount to be paid is unknown to the payee’s ASE. Payments continue to stream until the WM agent ends the session. At this point, the WM agent can request to mark the incoming payment as complete. This enables the payee’s ASE to be notified as soon as possible that no further payments will be sent and to credit the payee’s account.
:::

#### Quote
#### quote

After an `incoming-payment` resource is created on the payee’s account, a `quote` resource must be created on the payer’s account. A quote is only valid for a limited time.

Expand All @@ -61,7 +68,7 @@ There are three types of quotes.

A successfully created `quote` resource results in the generation of a quote `id` in the form of a URL.

#### Outgoing-payment
#### 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.

Expand Down
6 changes: 3 additions & 3 deletions docs/src/content/docs/resources/op-wallets.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ import { LinkOut } from '@interledger/docs-design-system'

The following digital wallet providers supply Open Payments-enabled accounts.

## Open Payments-enabled wallets
## Open Payments-enabled wallet providers

### Interledger testnet wallet
### Rafiki.Money (test wallet)

The Interledger testnet wallet is an ILP-enabled demo wallet application that developers can use to test their Open Payments integrations.
Rafiki.Money is a test wallet provider offering an ILP-enabled wallet that developers can use to test their Open Payments integrations. Rafiki.Money is offered as part of the Interledger testnet.

Sign up for an account at <LinkOut href='https://rafiki.money'>rafiki.money</LinkOut>.

Expand Down
41 changes: 20 additions & 21 deletions docs/src/content/docs/snippets/before-you-begin.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,48 +1,47 @@
---
title: Interledger testnet
title: Rafiki.Money
---

import { LinkOut } from '@interledger/docs-design-system'

Before you begin working with our code snippets, we recommend getting set up on the Interledger testnet on <LinkOut href='https://rafiki.money'>rafiki.money</LinkOut>.
Before working with our code snippets, we recommend creating a wallet account on <LinkOut href='https://rafiki.money'>Rafiki.Money</LinkOut>, a test wallet provider that's part of the Interledger testnet.

The Interledger testnet lets you create developer keys and test wallets funded with play money for making Interledger transactions via the Open Payments API.
Rafiki.Money lets you create developer keys and wallet accounts, funded with play money, for making Interledger transactions via the Open Payments API.

## Create an Interledger testnet account
## Create an account on Rafiki.Money

You can create an Interledger testnet account via <LinkOut href="https://rafiki.money">rafiki.money</LinkOut>.
1. Go to <LinkOut href="https://rafiki.money">rafiki.money</LinkOut>.
2. Click **Create an account** at the bottom right of the screen.
3. Enter your e-mail address, a password, confirm the password and click the arrowhead.
4. Go to your inbox and look for an e-mail sent by `[email protected]` with the subject "[Rafiki.Money] Verify your account" and click **Confirm my email address.** <br /><img src="/img/snippets/rafiki-money-step4.png" alt="Confirm email address" class="img-outline" width="350" height="auto" />
5. Click **Login to your account** at the email verification screen. <br /><img src="/img/snippets/rafiki-money-step5.png" alt="Log in with new account at rafiki.money" class="img-outline" width="350" height="auto" />
6. Log in with your credentials.
7. Enter any First and Last name on the Complete KYC screen and click **Get Wallet Account.** Note that since this is a test environment, the country, city and address fields will already be filled in. <br /><img src="/img/snippets/rafiki-money-step8.png" alt="Get wallet account at rafiki.money" class="img-outline" width="350" height="auto" />
8. Click **Verify your identity** on the pop-up window. <br /><img src="/img/snippets/rafiki-money-step9.png" alt="Identity verification at rafiki.money" class="img-outline" width="350" height="auto" />
9. Click **Verify Account** at the Complete KYC screen. Note that since this is a test environment "Passport" will be selected as the verification method and images will be uploaded by default. <br /><img src="/img/snippets/rafiki-money-step10.png" alt="Verify account at rafiki.money" class="img-outline" width="350" height="auto" />
10. Click **Go to your account overview** on the pop-up window. <br /><img src="/img/snippets/rafiki-money-step11.png" alt="Account overview dashboard on rafiki.money" class="img-outline" width="350" height="auto" />

1. Click **Create an account** at the bottom right of the screen.
2. Enter your e-mail address, a password, confirm the password and click the arrowhead.
3. Go to your inbox and look for an e-mail sent by `[email protected]` with the subject "[Rafiki.Money] Verify your account" and click **Confirm my email address.** <br /><img src="/img/snippets/rafiki-money-step4.png" alt="Confirm email address" class="img-outline" width="350" height="auto" />
4. Click **Login to your account** at the email verification screen. <br /><img src="/img/snippets/rafiki-money-step5.png" alt="Log in with new account at rafiki.money" class="img-outline" width="350" height="auto" />
5. Log in with your credentials.
6. Enter any First and Last name on the Complete KYC screen and click **Get Wallet Account.** Note that since this is a test environment, the country, city and address fields will already be filled in. <br /><img src="/img/snippets/rafiki-money-step8.png" alt="Get wallet account at rafiki.money" class="img-outline" width="350" height="auto" />
7. Click **Verify your identity** on the pop-up window. <br /><img src="/img/snippets/rafiki-money-step9.png" alt="Identity verification at rafiki.money" class="img-outline" width="350" height="auto" />
8. Click **Verify Account** at the Complete KYC screen. Note that since this is a test environment "Passport" will be selected as the verification method and images will be uploaded by default. <br /><img src="/img/snippets/rafiki-money-step10.png" alt="Verify account at rafiki.money" class="img-outline" width="350" height="auto" />
9. Click **Go to your account overview** on the pop-up window. <br /><img src="/img/snippets/rafiki-money-step11.png" alt="Account overview dashboard on rafiki.money" class="img-outline" width="350" height="auto" />
You're now ready to create a Rafiki.Money test wallet and add money to it!

You're now ready to create a testnet wallet and add money to it!
## Create a wallet account

## Create a testnet wallet
The first time you access <LinkOut href="https://rafiki.money">rafiki.money</LinkOut>, you'll be guided through creating a new wallet account.

The first time you access the <LinkOut href="https://rafiki.money">testnet</LinkOut>, you'll be guided through creating a new wallet account.

1. If you've completed or skipped the guide, you can create a wallet account by clicking **New Account.** <br /><img src="/img/snippets/rafiki-money-step13.png" alt="Set up new account at rafiki.money" class="img-outline" width="300" height="auto" />
1. If you've completed or skipped the onboarding guide, you can create a wallet account by clicking **New Account.** <br /><img src="/img/snippets/rafiki-money-step13.png" alt="Set up new account at rafiki.money" class="img-outline" width="300" height="auto" />
2. Enter a name for the account, choose an asset code from the drop-down menu and click **Create account.** <br /><img src="/img/snippets/rafiki-money-step15.png" alt="Enter name and create account on rafiki.money" class="img-outline" width="300" height="auto" />
3. Click **View Account.** <br /><img src="/img/snippets/rafiki-money-step16.png" alt="Click to view account created on rafiki.money" class="img-outline" width="350" height="auto" />
4. Click **Add payment pointer.** <br /><img src="/img/snippets/rafiki-money-step17.png" alt="Add a payment pointer for the new account on rafiki.money" class="img-outline" width="400" height="auto" />
5. Enter a Payment Pointer name and a Public name and then click **Create.** <br /><img src="/img/snippets/rafiki-money-step19.png" alt="Create payment pointer on rafiki.money" class="img-outline" width="400" height="auto" />
6. Click **Add money.** <br /><img src="/img/snippets/rafiki-money-step20.png" alt="Add money to payment pointer on rafiki.money" class="img-outline" width="400" height="auto" />
7. Fund your wallet by entering an amount, then click **Add money.** <br /><img src="/img/snippets/rafiki-money-step21.png" alt="Enter amount and add money to the payment pointer on rafiki.money" class="img-outline" width="400" height="auto" />

Congratulations, you now have a funded wallet on the Interledger testnet!
Congratulations, you now have a funded Rafiki.Money wallet!

## Obtain a public-private key pair and key ID

Before you can initialize an authenticated Open Payments client, you must obtain a public-private key pair and a key ID.

1. Sign in to the <LinkOut href='https://rafiki.money'>Interledger testnet</LinkOut>.
1. Sign in to <LinkOut href='https://rafiki.money'>rafiki.money</LinkOut>.
2. Select **Settings > Developer Keys**.
3. Expand the drop-down menu for your wallet account.<br /><img src="/img/snippets/generate-keys.png" alt="Expanded account showing payment pointer and Generate public & private key button" class="img-outline" style="max-width:600px;"/>
4. Click **Generate public & private key**. Your key ID and public key appear on the site. A private key file named `private.key` automatically downloads to your machine. <img src="/img/snippets/view-keys.png" alt="Expanded account showing key ID, option to show public key, and button to revoke public/private keys" class="img-outline" style="max-height:300px;"/>
Expand Down
2 changes: 1 addition & 1 deletion docs/src/partials/before-you-begin.mdx
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
We recommend creating an account on the [Interledger testnet](/snippets/before-you-begin) so you can test your client against the Open Payments API using a wallet funded with play money.
We recommend creating a wallet account on [Rafiki.Money](/snippets/before-you-begin), a test wallet provider that's part of the Interledger testnet. Creating an account allows you to test your client against the Open Payments API using an ILP-enabled wallet funded with play money.

0 comments on commit 7485da7

Please sign in to comment.