Skip to content
This repository was archived by the owner on Mar 8, 2024. It is now read-only.

getting-started.md

Latest commit

 

History

History
161 lines (118 loc) · 6.88 KB

getting-started.md

File metadata and controls

161 lines (118 loc) · 6.88 KB
id 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.

Your contributions are welcome. Check out the PayID repository on GitHub, and note the Contributing guidelines.

Experiment with the PayID Sandbox

The PayID 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, 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.

Run a PayID Server

To familiarize yourself and experiment with PayID, you can set up a local PayID server. Here is a simple method. For more options, including PayID deployment for production environments, see Deployment Overview.

  1. If you haven't already, install Docker and Node on your machine.

  2. The reference implementation server is available at https://github.com/payid-org/payid. You can download the reference implementation server by cloning the repository at the command line: git clone https://github.com/payid-org/payid.git

  3. Go to the /payid directory that you just created: cd payid

  4. Boot up the PayID HTTP server and a Postgres database to develop against: npm run devEnvUp

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.

To create a PayID, with an XRP Ledger Testnet account, send this request to your server:

curl --location --request POST 'http://127.0.0.1:8081/users' \
  --header 'PayID-API-Version: 2020-06-18' \
  --header 'Content-Type: application/json' \
  --data-raw '{
       "payId": "alice$127.0.0.1",
       "addresses": [
           {
               "paymentNetwork": "XRPL",
               "environment": "TESTNET",
               "details": {
                   "address": "rDk7FQvkQxQQNGTtfM2Fr66s7Nm3k87vdS",
                   "tag": "123"
               }
           }
       ]
   }'

PayID supports various payment networks. To create a second user with a Bitcoin testnet account, send this request to your server:

curl --location --request POST 'http://127.0.0.1:8081/users' \
  --header 'PayID-API-Version: 2020-06-18' \
  --header 'Content-Type: application/json' \
  --data-raw '{
       "payId": "bob$127.0.0.1",
       "addresses": [
           {
               "paymentNetwork": "BTC",
               "environment": "TESTNET",
               "details": {
                   "address": "mxNEbRXokcdJtT6sbukr1CTGVx8Tkxk3DB"
               }
           }
       ]
   }'

Request a PayID

After setting up a server and creating 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.

To request the PayID you created for Alice:

curl --location --request GET 'http://127.0.0.1:8080/alice' \
   --header 'PayID-Version: 1.0' \
   --header 'Accept: application/xrpl-testnet+json'

The response should have the following payload:

{
  "payId": "alice$127.0.0.1",
  "addresses": [
    {
      "paymentNetwork": "XRPL",
      "environment": "TESTNET",
      "addressDetailsType": "CryptoAddressDetails",
      "addressDetails": {
        "address": "rDk7FQvkQxQQNGTtfM2Fr66s7Nm3k87vdS",
        "tag:": "123"
      }
    }
  ]
}

To request the PayID you created for Bob:

curl --location --request GET 'http://127.0.0.1:8080/bob' \
   --header 'PayID-Version: 1.0' \
   --header 'Accept: application/btc-testnet+json'

That's it! You've set up a PayID server locally, created new PayIDs on your server, and requested those PayIDs by using the PayID Protocol.

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 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.

RippleX Dev Kit Integration

PayID support is integrated into RippleX Dev Kit.

RippleX Dev Kit provides the ability to work with PayID. It provides three language libraries:

These libraries help you connect your application to PayID without having to worry about the specifics of PayID. Try Get Started With RippleX Dev Kit and PayID.

Learn More

You now have a good foundation for learning more about the PayID Protocol. Here are some next steps you can take:

  • How to convert the user$domain.com format to a URL
  • Learn how to use relevant HTTP headers
  • Learn how to handle different types of responses you could receive from a PayID server

You can use extended PayID features:

Learn about: