Skip to content
This repository was archived by the owner on Mar 8, 2024. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
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
91 changes: 91 additions & 0 deletions docs/getting-started-sandbox.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
---
id: getting-started-sandbox
title: Getting Started With PayID Sandbox
sidebar_label: Getting Started With PayID Sandbox
---

With the [PayID Sandbox](https://payid.org/sandbox), you can experiment with PayID without deploying your own server. Although the PayID Sandbox can be used to create PayIDs, do not use these PayIDs that rely on this virtual server to send or receive real cryptocurrency. The PayID Sandbox does not directly support Verifiable PayID.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do not use these PayIDs that rely on this virtual server to send or receive real cryptocurrency.

This is probably worth a separate callout (a Caution, perhaps).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also suggest small tweak:

do not use PayIDs that rely on this virtual server to send or receive real cryptocurrency.

(remove "these")

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done


You can also experiment with PayID by using [PayID CLI](payid-cli), which does support Verifiable PayID.

The sandbox allows you to experiment with PayID, but does not create an application that allows you to send or receive currency using the PayID.

You are encouraged to copy the cURL or JavaScript code snippets that the sandbox provides and adapt them to your app.

Requirements:

- GitHub account. You will use this GitHub account to log in to PayID Sandbox.
- Crypto addresses on other wallets or exchanges. You can map your PayID to these crypto addresses.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not for this PR, but in the future would be great to see a link to another resource about wallets or how to generate the addresses.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On its way!


## Open PayID Sandbox and Create a User

1. Open [PayID Sandbox](https://payid.org/sandbox) and log in with your GitHub account.
The sandbox sets up a virtual server for you at _github_user_name_.sandbox.payid.org.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

github_user_name.sandbox.payid.org

Trivial but consider placing all of the above in code format and making the variable obnoxiously obvious, i.e.:

<YOUR_GITHUB_USERNAME>.sandbox.payid.org

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

You also get an Admin API token that can be used to create and manage users. Save this token for later use. By default, the sandbox incorporates this token into the **Authorization: Bearer** heading.
![Sandbox start](/img/docs/sandbox-start.png)
2. Click **Try API Constructor**.
![API Constructor](/img/docs/api-constructor1.png)
On the **API Constructor** page, you have access to all of PayID's capabilities. The **Create User** page opens by default.
3. Under **API Details**, enter the value for this PayID to create a full PayID address. Example: `starlight$loisrp.sandbox.payid.org`. This is a PayID that you can use to send or receive currency.
4. Under **Address1**, select the network you want to use. For experimentation, you can choose any of the networks, and you can use a real or fake address for it. This example uses a live address on the XRPL network.
- Select **XRPL** for the **Payment Network**
- Enter `rUAuauaXNTskaHdsz1TWnHWvB8goNXQaVy` for the **Payment Address**.
- The **Destination Tag** can be used to enter a number that is typically used to map to a user in another system. You can experiment by adding a value.
- Select **Testnet** or **Mainnet**, depending whether you want to have the address be valid for test currency or real currency.
- If you want to associate another address to this PayID, click **+** and repeat the process for another address. Your PayID can have multiple addresses on multiple networks on the same PayID.
5. By default, **cURL** is selected on the top right. The sandbox constructs the cURL snippet you need to create a user. You can also select **JavaScript** to run a script to create a user.
6. Click **Run**. Whether you used cURL or JavaScript, the JSON for the newly created user looks the same.
```json
{
"payId": "starlight$loisrp.sandbox.payid.org",
"addresses": [
{
"paymentNetwork": "XRPL",
"details": {
"address": "rUAuauaXNTskaHdsz1TWnHWvB8goNXQaVy",
"tag": "56"
}
}
]
}
```

## Get Payment Information

**Get Payment Information** is a public API, and does not require your Admin API token. You can use this API for any PayID.

1. Click **Get Payment Information** on the left.
2. Enter the PayID. On the sandbox, you are restricted to PayIDs on your server. Enter the PayID you just created, or another one you happen to know. Select either **cURL** or **JavaScript** at the top right.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there any well-known public servers we could point users to? (I'm guessing no.)

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can't change the server in the UI. The sandbox only allows your specific local server.

3. Click **Run**. The JSON response provides information about the PayID.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any reason not to include a sample response here as well?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now I see what you mean. Have added there as well.


## Get User

**Get User** provides the same information as **Get Payment Information**, but **Get User** does so through the private Admin API.

1. Click **Get User** on the left.
2. Enter the PayID you want to look up.
3. Select either **cURL** or **JavaScript**.
4. Click **Run**. The JSON response provides information about the PayID.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For all of these, I think it would be useful to provide an example of the response. In this case, it would be useful to see the successful return as well as the error case you note below.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.


If you enter a nonexistent PayID, you get the response "Failed to find the PayID <_value_>".
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Failed to find the PayID <value>"

Trivial again, but consider making this code font if it's part of the response. And if you capitalize the variable, you won't need to use the underscores, too.

Failed to find the PayID <NONEXISTENT_PAYID_VALUE>

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added code font. Kept quotes, because they are part of the response.


## Replace User

With **Replace User**, you can rename a PayID, and enter new address information. The address information from the "old" PayID does not transfer to the new PayID, so you have to enter the address information again.

1. Click **Replace User** on the left.
2. Enter the PayID you want to rename, and the new PayID.
3. Enter the address information as if you were creating a user.
4. Select either **cURL** or **JavaScript**.
5. Click **Run**.

The new PayID information is returned in JSON format.

## Delete a User

1. Click **Delete User** on the left.
2. Enter the PayID you want to delete.
3. Select either **cURL** or **JavaScript**.
4. Click **Run**.

The PayID you have deleted is returned in the response. Even if the PayID did not exist, you will get the same response.
4 changes: 2 additions & 2 deletions docs/metrics-tutorial.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
id: metrics-tutorial
title: Metrics Tutorial
sidebar_label: Metrics Tutorial
title: Get Started With Metrics
sidebar_label: Get Started With Metrics
---

## Deploy a PayID server with Docker, and pull PayID metrics into Prometheus
Expand Down
4 changes: 2 additions & 2 deletions docs/payid-cli.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
id: payid-cli
title: PayID CLI
sidebar_label: PayID CLI
title: Get Started With PayID CLI
sidebar_label: Get Started With PayID CLI
---

With the PayID CLI, you can run PayID commands from the command line, and access all PayID features.
Expand Down
6 changes: 3 additions & 3 deletions docs/welcome-to-payid.md → docs/what-is-payid.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
id: welcome-to-payid
title: Welcome to PayID
sidebar_label: Welcome to PayID
id: what-is-payid
title: What is PayID?
sidebar_label: What is PayID?
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Out of scope of this PR but it would be great to tweak the text in this section to directly answer this question in the first sentence, e.g. "PayID is..." That will take a little more work, though.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did a bit on this.

---

With PayID, you use human-readable addresses to transmit value in the currency of your choice. The PayID network allows participants to reach one another through a standardized address. For example, `alice$example.com` maps to the corresponding URL `https://example.com/alice`.
Expand Down
7 changes: 6 additions & 1 deletion sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,17 @@ module.exports = {
type: 'doc',
id: 'home',
},
{
type: 'doc',
id: 'what-is-payid',
},
{
type: 'category',
label: 'Get Started',
items: [
'getting-started',
'getting-started-sandbox',
'payid-cli',
'verifiable-payid-tutorial',
'ripplex-dev-kit-payid-get-started',
'metrics-tutorial',
Expand All @@ -19,7 +25,6 @@ module.exports = {
label: 'Reference Implementation',
items: [
'payid-reference-overview',
'payid-cli',
'verifiable-payid',
'payid-discovery',
'payid-best-practices',
Expand Down
Binary file added static/img/docs/api-constructor1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/docs/sandbox-start.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.