diff --git a/docs/getting-started-sandbox.md b/docs/getting-started-sandbox.md new file mode 100644 index 0000000..6961c3f --- /dev/null +++ b/docs/getting-started-sandbox.md @@ -0,0 +1,127 @@ +--- +id: getting-started-sandbox +title: Get Started With PayID Sandbox +sidebar_label: Get Started With PayID Sandbox +--- + +With the [PayID Sandbox](https://payid.org/sandbox), you can experiment with PayID without deploying your own server. The PayID Sandbox does not directly support Verifiable PayID. + +**Caution:** Although the PayID Sandbox can be used to create PayIDs, do not use PayIDs that rely on this virtual server to send or receive real cryptocurrency. + +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. + +## 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 `.sandbox.payid.org`. + 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 response 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. +3. Click **Run**. The JSON response provides information about the PayID. + +## 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. + + ```json + { + "payId": "starlight$loisrp.sandbox.payid.org", + "addresses": [ + { + "paymentNetwork": "XRPL", + "environment": "TESTNET", + "details": { + "address": "rUAuauaXNTskaHdsz1TWnHWvB8goNXQaVy" + } + } + ], + "verifiedAddresses": [] + } + ``` + +```` + +If you enter a nonexistent PayID, you get the response `"Failed to find the PayID "`. + +## 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. In this example, `starlight` is replaced with `moonlight`. +3. Enter the address information as if you were creating a user. +4. Select either **cURL** or **JavaScript**. +5. Click **Run**. + ```json + { + "payId": "moonlight$loisrp.sandbox.payid.org", + "addresses": [ + { + "paymentNetwork": "XRPL", + "environment": "TESTNET", + "details": { + "address": "rUAuauaXNTskaHdsz1TWnHWvB8goNXQaVy" + } + } + ], + "verifiedAddresses": [] +} +```` + +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 is returned. + `"moonlight$loisrp.sandbox.payid.org"` + +The PayID you have deleted is returned in the response. Even if the PayID did not exist, you will get the same response. diff --git a/docs/getting-started.md b/docs/getting-started.md index 8fa3fb2..6f456f6 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,15 +1,14 @@ --- id: getting-started -title: Getting Started -sidebar_label: Getting Started +title: Get Started Overview +sidebar_label: Get Started Overview --- PayID is a simple, web-based protocol designed to make it as easy to send someone money as it is to send them an email. This guide walks you through the following. - [Experiment With the PayID Sandbox](#experiment-with-the-payid-sandbox) - [Run a PayID Server](#run-a-payid-server) -- [Create a PayID](#create-a-payid) -- [Request a PayID](#request-a-payid) +- [Run PayID CLI](#run-payid-cli) - [Learn More](#learn-more) - [RippleX Dev Kit Integration](#ripplex-dev-kit-integration) @@ -19,7 +18,7 @@ Your contributions are welcome. Check out the [PayID repository on GitHub](https The [PayID Sandbox](https://payid.org/sandbox) lets you experiment with PayID in a test environment. Your work is not saved between sessions, and the sandbox may be reset at any time. -To use [PayID Sandbox](https://payid.org/sandbox), log in with your Github account and follow the prompts. You can quickly set up a virtual test server, and then create users with simple PayID addresses that map to addresses on various networks such as XRPL, Interledger, BTC, and ETH. Using the provided cURL or Javascript code, you can create, update, and delete users, and get payment information about a PayID address. While the session is running, you can also run operations from your command line. +To use [PayID Sandbox](https://payid.org/sandbox), log in with your Github account and follow the prompts. You can quickly set up a virtual test server, and then create users with simple PayID addresses that map to addresses on various networks such as XRPL, Interledger, BTC, and ETH. Using the provided cURL or Javascript code, you can create, update, and delete users, and get payment information about a PayID address. While the session is running, you can also run operations from your command line. See [Get Started With PayID Sandbox](getting-started-sandbox). ## Run a PayID Server @@ -36,7 +35,7 @@ To familiarize yourself and experiment with PayID, you can set up a local PayID 4. Boot up the PayID HTTP server and a Postgres database to develop against: `npm run devEnvUp` -## Create a PayID +### Create a PayID Now that you have a PayID server running, you can create a PayID. If your server is publicly accessible, other people could query your account information from your PayID server. @@ -81,7 +80,7 @@ curl --location --request POST 'http://127.0.0.1:8081/users' \ }' ``` -## Request a PayID +### Request a PayID After setting up a server and [creating a PayID](#create-a-payid) on the server, the next step is to request the PayID from the server. The PayID Protocol is what allows you to make these requests. And, when the server is publicly available, other wallets and entities can make similar requests to query any PayID and related account information stored on the server. @@ -126,6 +125,10 @@ If you want to clean up the Docker containers, you can run `npm run devDown`. Now that you've set up the basics, [learn more](#learn-more) about PayID and what you can do with it. +## Run PayID CLI + +PayID CLI allows you to manage PayIDs and get user information from the command line. See [Get Started With PayID CLI](payid-cli). + ## RippleX Dev Kit Integration PayID support is integrated into [RippleX Dev Kit](https://github.com/xpring-eng/ripplex-dev-kit). diff --git a/docs/metrics-tutorial.md b/docs/metrics-tutorial.md index b1f507f..1c8bad5 100644 --- a/docs/metrics-tutorial.md +++ b/docs/metrics-tutorial.md @@ -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 diff --git a/docs/payid-cli.md b/docs/payid-cli.md index 221393d..5028312 100644 --- a/docs/payid-cli.md +++ b/docs/payid-cli.md @@ -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. diff --git a/docs/payid-use-cases.md b/docs/payid-use-cases.md new file mode 100644 index 0000000..c7bc818 --- /dev/null +++ b/docs/payid-use-cases.md @@ -0,0 +1,54 @@ +--- +id: payid-use-cases +title: PayID Use Cases +sidebar_label: PayID Use Cases +--- + +PayID can be used anywhere that a payment workflow occurs. Due to the ease of PayID, you can also consider new ways to monetize products and services. + +If you are using PayID for your app, you can use the reference implementation as a basis for your PayID methodology, or you can develop your own implementation. + +You can see some examples of [PayID technology in action](https://docs.payid.org/). These apps cover use cases like these. Payments may be done end-to-end in cryptocurrency, but do not have to be. Some ideas implemented by partners or hackathon participants include the following: + +- Create a PayID with a mobile phone +- Create QR codes that represent a PayID +- Game key marketplace +- International money transfers +- International payments for work +- Wallet that performs cross-chain transfers directly to a PayID +- Central gateway to send and receive crypto and fiat payments +- A physical store of value on a card + +## Wallets and exchanges + +A wallet is a software program in which you store your cryptocurrency. An exchange can host a wallet, but primarily an exchange is used primarily to store cryptocurrency and to convert between cryptocurrency and fiat currency. PayID can be used for all of these transaction types: + +- Wallet to wallet +- Exchange to exchange +- Exchange to wallet +- Wallet to exchange + +## Building with PayID + +PayID can become part of payment flows. Wherever there is a credit card request or an option to pay by PayID or Venmo or another such service, PayID can be used as well. + +A harder question is: Where can PayID be used where it's not an obvious option? + +## Tutorials based on PayID use cases + +Stripe can be deployed to implement much of a bank's machinery, as [shown here[(https://stripe.com/docs/payments/charges-api) and [here](https://stripe.com/docs). PayID simply lacks that level of functionality, and it's not what it is trying to do anyway. We should concentrate on simple options at first. + +We have simple tutorials showing how to use the PayID APIs, how to use PayID CLI, how to use Verifiable PayID, how to deploy PayID, and how to use metrics. + +A simple tutorial could show the following: + +- Use a Payburner wallet (or maybe look at incorporating a workflow on creating a walllet) and load it with a few XRP. +- Create a different wallet, or another Payburner wallet. +- Create a PayID (signed) for each wallet. +- Use one wallet to pay the other. +- Use Get Payment Information, and Get User. +- For bonus points, use RippleX Dev Kit. + +A related tutorial could show transfers between different networks (so maybe two different types of wallets?). + +As new features come into play, then we have more options. diff --git a/docs/welcome-to-payid.md b/docs/what-is-payid.md similarity index 92% rename from docs/welcome-to-payid.md rename to docs/what-is-payid.md index a0b19f6..cbc5768 100644 --- a/docs/welcome-to-payid.md +++ b/docs/what-is-payid.md @@ -1,10 +1,10 @@ --- -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? --- -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`. +PayID is a simple, web-based protocol designed to make it as easy to send someone money as it is to send them an email. With the PayID protocol, you use human-readable addresses to transmit value in the currency of your choice. The PayID network allows participants to reach one another through standardized addresses. An address such as `alice$example.com` maps to the corresponding URL `https://example.com/alice`. When you make an HTTP GET request that follows the PayID protocol, it resolves to an address on the underlying payment network. PayID is a payment-network-agnostic protocol, capable of sending payments in BTC, ETH, XRP, or fiat networks like ACH. diff --git a/sidebars.js b/sidebars.js index fad9045..fec5ead 100644 --- a/sidebars.js +++ b/sidebars.js @@ -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', @@ -19,7 +25,6 @@ module.exports = { label: 'Reference Implementation', items: [ 'payid-reference-overview', - 'payid-cli', 'verifiable-payid', 'payid-discovery', 'payid-best-practices', diff --git a/static/img/docs/api-constructor1.png b/static/img/docs/api-constructor1.png new file mode 100644 index 0000000..46a48fd Binary files /dev/null and b/static/img/docs/api-constructor1.png differ diff --git a/static/img/docs/sandbox-start.png b/static/img/docs/sandbox-start.png new file mode 100644 index 0000000..04ed16b Binary files /dev/null and b/static/img/docs/sandbox-start.png differ