PayString

https://github.com/paystring/paystring-documentation
Admin
PayString is an open-source standard that simplifies sending and receiving payments by mapping...
Tokens:27,889
Snippets:175
Trust Score:7.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Start Prometheus Docker Container and Scrape Metrics

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/metrics-tutorial.md

Starts a Prometheus Docker container, mounting a local 'prometheus.yml' configuration file and exposing the Prometheus UI. Includes example metric queries.

```bash
docker run -d --network paystrings-network -p 9090:9090 -v $PWD/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus
```

```text
sum(payid_count)
```

```text
sum(payid_count) by (paymentNetwork)
```

```text
sum(payid_lookup_request)
```

```text
rate(payid_lookup_request[5m])
```

--------------------------------

### Local Development Server Setup - PayString

Source: https://context7.com/paystring/paystring-documentation/llms.txt

Instructions for setting up a local PayString server and PostgreSQL database using Docker. Requires Docker and Node.js as prerequisites. Includes commands to start and stop the development environment.

```bash
# Install prerequisites
# - Docker: https://docs.docker.com/get-docker/
# - Node.js: https://nodejs.org/en/ 

# Clone PayString reference implementation
git clone https://github.com/paystring/paystring.git

# Navigate to repository
cd paystring

# Start PayString server and PostgreSQL database
npm run devEnvUp

# Server starts on:
# - Public API: http://127.0.0.1:8080
# - Admin API: http://127.0.0.1:8081

# Clean up Docker containers when done
npm run devDown
```

--------------------------------

### PayString CLI - Install and Load (Bash)

Source: https://context7.com/paystring/paystring-documentation/llms.txt

Instructions for installing and using the PayString CLI tool. It covers global installation via npm and demonstrates how to run the CLI in interactive mode or load a PayString from a remote server.

```bash
# Install PayString CLI globally
npm install -g @payid-org/payid-cli

# Run in interactive mode
payid

# Load PayString from remote server
load loisrp$xpring.money
```

--------------------------------

### Start PayString Development Environment

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/deploy-with-docker.md

Boots up the PayString HTTP server and a PostgreSQL database for development. Requires Node.js and npm to be installed and the repository to be cloned.

```shell
npm run devEnvUp
```

--------------------------------

### Install PayString CLI Globally

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/paystring-cli.md

Installs the PayString CLI as a global npm module, making it accessible as an executable on your system. Ensure Node.js and npm are installed beforehand.

```bash
npm install -g @payid-org/payid-cli
```

--------------------------------

### Start Postgres Database Docker Container

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/metrics-tutorial.md

Starts a PostgreSQL database container named 'paystring-postgres' on the 'paystring-network'. Uses 'password' as the database password. Requires Docker.

```bash
docker run -d --rm --name paystring-postgres --network paystring-network -e POSTGRES_PASSWORD=password postgres
```

--------------------------------

### Start and Test PayString Server Docker Container

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/metrics-tutorial.md

Starts the PayString server in a Docker container, mapping ports and connecting to the 'paystring-postgres' database via the 'paystring-network'. Includes commands to create and query a PayString.

```bash
docker run -it -p 8080:8080 -p 8081:8081 --name paystring-server --network paystring-network -e DB_PASSWORD=password -e
    DB_NAME=postgres -e DB_HOSTNAME=paystring-postgres paystring-server
```

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

```bash
curl http://127.0.0.1:8080/charlie -H "PayID-Version: 1.0" -H "Accept: application/xrpl-testnet+json"
```

--------------------------------

### GET /:user - General Request Example

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/paystring-headers.md

Example of a GET request to retrieve user address information, specifying the payment network and environment via the Accept header.

```APIDOC
## GET /{user}

### Description
Retrieves user address information for a specified payment network and environment.

### Method
GET

### Endpoint
`/{user}`

### Parameters
#### Query Parameters
- **Accept** (string) - Required - Specifies the payment network and environment (e.g., `application/xrpl-testnet+json`).

### Request Example
```http
GET /{user} HTTP/1.1

Accept: application/xrpl-testnet+json
```

### Response
#### Success Response (200)
- **address** (string) - The user's address for the specified network.
- **tag** (string) - Optional - The user's tag for the specified network (e.g., for XRP).
- **account** (string) - The user's account number (e.g., for ACH).
- **routing** (string) - The user's routing number (e.g., for ACH).
- **memo** (string) - Optional - The user's memo for the specified network (e.g., for CRO).

#### Response Example
```json
{
  "address": "rw2ciyaNshpHe7bCHo4bRWq6pqqynnWKQg",
  "tag": "67298042"
}
```
```

--------------------------------

### Build Docker Container for PayString Server

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/metrics-tutorial.md

Builds a Docker container for the PayString server from the GitHub repository. Requires git, Docker, and npm to be installed.

```bash
git clone https://github.com/paystring/paystring.git
cd paystring
docker build -t paystring-server .
```

--------------------------------

### Install Docker and Docker Compose on Ubuntu

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/remote-deployment.md

Commands to install Docker and Docker Compose on an Ubuntu instance. These are essential for running the PayString service in containers.

```bash
sudo apt-get update
sudo apt install docker.io docker-compose
```

--------------------------------

### Create Bitcoin Testnet PayString

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/getting-started-local.md

Creates a PayString for a Bitcoin Testnet account by sending a POST request to the local PayString server. Requires a running PayString server and a Bitcoin Testnet account.

```bash
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"
               }
           }
       ]   }'
```

--------------------------------

### Run PayString CLI from Docker

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/paystring-cli.md

Executes the PayString CLI using a Docker container. This is an alternative installation method that does not require local installation of Node.js or npm.

```bash
docker run xpring/payid-cli
```

--------------------------------

### Create a PayString (BTC Testnet)

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/getting-started-local.md

This endpoint allows you to create a new PayString associated with a Bitcoin Testnet account.

```APIDOC
## POST /users

### Description
Creates a new PayString with associated payment network addresses.

### Method
POST

### Endpoint
`http://127.0.0.1:8081/users`

### Parameters

#### Headers
- **PayID-API-Version** (string) - Required - Specifies the API version, e.g., `2020-06-18`.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **payId** (string) - Required - The unique identifier for the PayString (e.g., `bob$127.0.0.1`).
- **addresses** (array) - Required - A list of addresses associated with the PayString.
  - **paymentNetwork** (string) - Required - The payment network (e.g., `BTC`).
  - **environment** (string) - Required - The environment for the network (e.g., `TESTNET`).
  - **details** (object) - Required - Specific details for the address.
    - **address** (string) - Required - The actual payment address (e.g., `mxNEbRXokcdJtT6sbukr1CTGVx8Tkxk3DB`).

### Request Example
```json
{
    "payId": "bob$127.0.0.1",
    "addresses": [
        {
            "paymentNetwork": "BTC",
            "environment": "TESTNET",
            "details": {
                "address": "mxNEbRXokcdJtT6sbukr1CTGVx8Tkxk3DB"
            }
        }
    ]
}
```

### Response
#### Success Response (200)
- **payId** (string) - The created PayString identifier.
- **addresses** (array) - The list of successfully created addresses.

#### Response Example
```json
{
  "payId": "bob$127.0.0.1",
  "addresses": [
    {
      "paymentNetwork": "BTC",
      "environment": "TESTNET",
      "addressDetailsType": "CryptoAddressDetails",
      "addressDetails": {
        "address": "mxNEbRXokcdJtT6sbukr1CTGVx8Tkxk3DB"
      }
    }
  ]
}
```
```

--------------------------------

### Create a PayString (XRPL Testnet)

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/getting-started-local.md

This endpoint allows you to create a new PayString associated with an XRPL Testnet account.

```APIDOC
## POST /users

### Description
Creates a new PayString with associated payment network addresses.

### Method
POST

### Endpoint
`http://127.0.0.1:8081/users`

### Parameters

#### Headers
- **PayID-API-Version** (string) - Required - Specifies the API version, e.g., `2020-06-18`.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **payId** (string) - Required - The unique identifier for the PayString (e.g., `alice$127.0.0.1`).
- **addresses** (array) - Required - A list of addresses associated with the PayString.
  - **paymentNetwork** (string) - Required - The payment network (e.g., `XRPL`).
  - **environment** (string) - Required - The environment for the network (e.g., `TESTNET`).
  - **details** (object) - Required - Specific details for the address.
    - **address** (string) - Required - The actual payment address (e.g., `rDk7FQvkQxQQNGTtfM2Fr66s7Nm3k87vdS`).
    - **tag** (string) - Optional - A tag associated with the address (e.g., `123`).

### Request Example
```json
{
    "payId": "alice$127.0.0.1",
    "addresses": [
        {
            "paymentNetwork": "XRPL",
            "environment": "TESTNET",
            "details": {
                "address": "rDk7FQvkQxQQNGTtfM2Fr66s7Nm3k87vdS",
                "tag": "123"
            }
        }
    ]
}
```

### Response
#### Success Response (200)
- **payId** (string) - The created PayString identifier.
- **addresses** (array) - The list of successfully created addresses.

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

--------------------------------

### Request Bitcoin Testnet PayString

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/getting-started-local.md

Requests the PayString information for 'bob$127.0.0.1' from the local PayString server using the PayString Protocol. Requires a PayString to be previously created.

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

--------------------------------

### Request XRPL Testnet PayString

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/getting-started-local.md

Requests the PayString information for 'alice$127.0.0.1' from the local PayString server using the PayString Protocol. Requires a PayString to be previously created.

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

--------------------------------

### Start PayString Server Locally

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/local-deployment.md

Starts the PayString server locally. This command configures the database connection using environment variables and generates the schema if it doesn't exist. Ensure Postgres is running and accessible.

```bash
DB_HOSTNAME=localhost DB_NAME=dev_payid DB_USERNAME=payid_dev
DB_PASSWORD='xxxxx' npm run start
```

--------------------------------

### Create XRPL Testnet PayString

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/getting-started-local.md

Creates a PayString for an XRPL Testnet account by sending a POST request to the local PayString server. Requires a running PayString server and an XRP Ledger Testnet account.

```bash
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"
               }
           }
       ]   }'
```

--------------------------------

### Run PayString Server Continuously with Forever

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/local-deployment.md

Starts the PayString server using 'forever' to ensure it runs continuously in the background. This command utilizes the same database environment variables as the basic start command.

```bash
DB_HOSTNAME=localhost DB_NAME=dev_payid DB_USERNAME=payid_dev
DB_PASSWORD='xxxxx' forever start build/src/index.js
```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/local-deployment.md

Installs all the necessary Node.js package dependencies required for the PayString project to build and run. This command should be executed after cloning the repository.

```bash
npm i
```

--------------------------------

### HTTP Request with Accept Header for XRPL Testnet

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/paystring-headers.md

This snippet demonstrates a typical HTTP GET request to a PayString endpoint. The 'Accept' header specifies the payment network (XRPL) and environment (testnet), enabling PayString to return user address information for that specific configuration. This is a foundational example for interacting with PayString services.

```HTTP
GET /{user} HTTP/1.1

Accept: application/xrpl-testnet+json
```

--------------------------------

### Example PayString JSON Schema

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/aws-lambda-deploy.md

This is an example of a JSON file that can be uploaded to the S3 bucket to represent a single user's PayString. It includes payment network, environment, and address details.

```json
{
    "addresses":[
        {
            "paymentNetwork":"XRPL",
            "environment":"TESTNET",
            "addressDetailsType":"CryptoAddressDetails",
            "addressDetails":{
                "address":"T772A73My52QaUonaai6VE4X98zLu7VBQSXJKLYimjXDAJi"
            }
        }
    ]
}
```

--------------------------------

### Install Forever for Continuous Process Management

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/local-deployment.md

Installs the 'forever' tool globally, which is a simple CLI tool for ensuring a given script runs continuously. This is useful for keeping the PayString server running.

```bash
npm install forever -g
```

--------------------------------

### Get Payment Information via cURL and JavaScript in PayString Sandbox

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/getting-started-sandbox.md

This snippet shows how to retrieve payment information for a given PayString using the public API. It's available for any PayString and does not require an Admin API token. Examples are provided for both cURL and JavaScript.

```curl
curl -X GET \
  https://sandbox.paystring.org/payid/starlight$loisrp.sandbox.paystring.org
```

```javascript
fetch('https://sandbox.paystring.org/payid/starlight$loisrp.sandbox.paystring.org')
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

--------------------------------

### Dockerfile for PayString Documentation Deployment

Source: https://context7.com/paystring/paystring-documentation/llms.txt

A Dockerfile to containerize the PayString documentation website for deployment. It uses a Node.js base image, installs dependencies, copies source files, builds the documentation site, exposes port 3000, and sets the command to serve the static files.

```dockerfile
# Dockerfile
FROM node:12

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci

# Copy source files
COPY . .

# Build documentation site
RUN npm run build

# Expose port
EXPOSE 3000

# Serve static files
CMD ["npm", "run", "serve"]

# Build and run

```

--------------------------------

### Get User via cURL and JavaScript in PayString Sandbox

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/getting-started-sandbox.md

This snippet demonstrates how to retrieve detailed user information using the private Admin API. It requires the Admin API token and is specific to PayStrings on your sandbox server. Examples are provided for cURL and JavaScript, with the output being a JSON object containing user and address details.

```curl
curl -X GET \
  https://sandbox.paystring.org/users/starlight$loisrp.sandbox.paystring.org \
  -H 'Authorization: Bearer <YOUR_ADMIN_API_TOKEN>'
```

```javascript
const options = {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <YOUR_ADMIN_API_TOKEN>'
  }
};

fetch('https://sandbox.paystring.org/users/starlight$loisrp.sandbox.paystring.org', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

```json
{
  "payId": "starlight$loisrp.sandbox.paystring.org",
  "addresses": [
    {
      "paymentNetwork": "XRPL",
      "environment": "TESTNET",
      "details": {
        "address": "rUAuauaXNTskaHdsz1TWnHWvB8goNXQaVy"
      }
    }
  ],
  "verifiedAddresses": []
}
```

--------------------------------

### Install Certbot for NGINX SSL

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/nginx-ssl-deploy.md

Installs Certbot and its NGINX plugin on Ubuntu systems to manage SSL certificates. This is a prerequisite for enabling HTTPS for your PayString server.

```bash
apt-get update
apt-get install software-properties-common
add-apt-repository ppa:certbot/certbot
apt-get update
apt-get install python-certbot-nginx
```

--------------------------------

### Start Prometheus Container with Configuration

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/metrics.md

Runs a Prometheus monitoring server in a Docker container, exposing its web interface on port 9090. It connects to the 'paystring-network' and mounts a local 'prometheus.yml' file into the container for configuration.

```bash
docker run -d --network paystring-network -p 9090:9090 -v $PWD/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus
```

--------------------------------

### Request a PayString (BTC Testnet)

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/getting-started-local.md

Retrieves the PayString information for a specific PayID, including its associated Bitcoin Testnet address.

```APIDOC
## GET /{payId}

### Description
Requests and retrieves the PayString information for a given PayID.

### Method
GET

### Endpoint
`http://127.0.0.1:8080/{payId}`

### Parameters

#### Path Parameters
- **payId** (string) - Required - The PayString identifier to retrieve (e.g., `bob`).

#### Headers
- **PayID-Version** (string) - Required - The version of the PayID protocol (e.g., `1.0`).
- **Accept** (string) - Required - The desired response format (e.g., `application/btc-testnet+json`).

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

### Response
#### Success Response (200)
- **payId** (string) - The requested PayString identifier.
- **addresses** (array) - A list of addresses associated with the PayString.
  - **paymentNetwork** (string) - The payment network.
  - **environment** (string) - The environment for the network.
  - **addressDetailsType** (string) - The type of address details.
  - **addressDetails** (object) - Details about the address.
    - **address** (string) - The payment address.

#### Response Example
```json
{
  "payId": "bob$127.0.0.1",
  "addresses": [
    {
      "paymentNetwork": "BTC",
      "environment": "TESTNET",
      "addressDetailsType": "CryptoAddressDetails",
      "addressDetails": {
        "address": "mxNEbRXokcdJtT6sbukr1CTGVx8Tkxk3DB"
      }
    }
  ]
}
```
```

--------------------------------

### Request a PayString (XRPL Testnet)

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/getting-started-local.md

Retrieves the PayString information for a specific PayID, including its associated XRPL Testnet address.

```APIDOC
## GET /{payId}

### Description
Requests and retrieves the PayString information for a given PayID.

### Method
GET

### Endpoint
`http://127.0.0.1:8080/{payId}`

### Parameters

#### Path Parameters
- **payId** (string) - Required - The PayString identifier to retrieve (e.g., `alice`).

#### Headers
- **PayID-Version** (string) - Required - The version of the PayID protocol (e.g., `1.0`).
- **Accept** (string) - Required - The desired response format (e.g., `application/xrpl-testnet+json`).

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

### Response
#### Success Response (200)
- **payId** (string) - The requested PayString identifier.
- **addresses** (array) - A list of addresses associated with the PayString.
  - **paymentNetwork** (string) - The payment network.
  - **environment** (string) - The environment for the network.
  - **addressDetailsType** (string) - The type of address details.
  - **addressDetails** (object) - Details about the address.
    - **address** (string) - The payment address.
    - **tag** (string) - The tag associated with the address.

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

--------------------------------

### Build PayString Project

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/local-deployment.md

Generates the build files, including application code and SQL scripts, typically located in the `build/*` directory. This step is essential before starting the server.

```bash
npm run build
```

--------------------------------

### Start PayString Server Container

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/metrics.md

Launches the PayString server within a Docker container, making it accessible on ports 8080 and 8081. This server requires access to the 'paystring-network' to communicate with the PostgreSQL database, using 'password' as the database password and 'postgres' as the database name.

```bash
docker run -it -p 8080:8080 -p 8081:8081 --name paystring-server --network paystring-network -e DB_PASSWORD=password -e DB_NAME=postgres -e DB_HOSTNAME=paystring-postgres paystring-server
```

--------------------------------

### Create User via cURL and JavaScript in PayString Sandbox

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/getting-started-sandbox.md

This snippet demonstrates how to create a new user in the PayString Sandbox. It includes examples for both cURL and JavaScript, which can be adapted from the sandbox's API Constructor. The output is a JSON object containing the created PayString and its associated addresses.

```curl
curl -X POST \
  https://sandbox.paystring.org/users \
  -H 'Authorization: Bearer <YOUR_ADMIN_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ 
    "payId": "starlight$loisrp.sandbox.paystring.org", 
    "addresses": [ 
      { 
        "paymentNetwork": "XRPL", 
        "environment": "TESTNET", 
        "details": { 
          "address": "rUAuauaXNTskaHdsz1TWnHWvB8goNXQaVy", 
          "tag": "56" 
        } 
      } 
    ] 
  }'
```

```javascript
const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_ADMIN_API_TOKEN>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payId: 'starlight$loisrp.sandbox.paystring.org',
    addresses: [
      {
        paymentNetwork: 'XRPL',
        environment: 'TESTNET',
        details: {
          address: 'rUAuauaXNTskaHdsz1TWnHWvB8goNXQaVy',
          tag: '56'
        }
      }
    ]
  })
};

fetch('https://sandbox.paystring.org/users', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

```json
{
  "payId": "starlight$loisrp.sandbox.paystring.org",
  "addresses": [
    {
      "paymentNetwork": "XRPL",
      "details": {
        "address": "rUAuauaXNTskaHdsz1TWnHWvB8goNXQaVy",
        "tag": "56"
      }
    }
  ]
}
```

--------------------------------

### GET /.well-known/webfinger

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/paystring-discovery.md

This endpoint is used by wallet applications to discover the PayString URI for a given PayString by performing a WebFinger query.

```APIDOC
## GET /.well-known/webfinger

### Description
This endpoint is used by wallet applications to discover the PayString URI for a given PayString by performing a WebFinger query.

### Method
GET

### Endpoint
`/.well-known/webfinger?resource=payid%3A<paystring>`

### Parameters
#### Query Parameters
- **resource** (string) - Required - The PayString to discover, encoded as `payid:<paystring>`.

### Request Example
```
GET /.well-known/webfinger?resource=payid%3Abob%24receiver.example.com
HTTP/1.1
Host: receiver.example.com
```

### Response
#### Success Response (200)
- **subject** (string) - The subject of the WebFinger response, typically the PayString.
- **links** (array) - An array of links, including a `rel` of `https://paystring.org/ns/payid-uri-template/1.0` with a `template` property.
  - **rel** (string) - The relation type of the link.
  - **template** (string) - A URL template used to construct the PayString URL.

#### Response Example
```json
{
  "subject" : "payid:bob$receiver.example.com",
  "links" :
  [
    {
      "rel": "https://paystring.org/ns/payid-uri-template/1.0",
      "template": "https://receiver.example.com/users/{acctpart}"
    }
  ]
}
```

#### Error Response (404)
- **Description**: Returned when the server does not support the PayString Discovery endpoint or the requested PayString cannot be found.
```

--------------------------------

### GET /:paystring

Source: https://context7.com/paystring/paystring-documentation/llms.txt

Query a PayString address to retrieve payment information for a specific network and environment. The desired network and environment are specified using the `Accept` header.

```APIDOC
## GET /:paystring

### Description
Query a PayString address to retrieve payment information for a specific network and environment. The desired network and environment are specified using the `Accept` header.

### Method
GET

### Endpoint
`/:paystring`

### Headers
- **PayID-Version** (string) - Required - The version of the PayID API.
- **Accept** (string) - Required - Specifies the payment network and environment (e.g., `application/xrpl-testnet+json`, `application/btc-mainnet+json`, `application/payid+json`).

### Response
#### Success Response (200)
- **payId** (string) - The PayString identifier.
- **addresses** (array) - An array of payment addresses.
  - **paymentNetwork** (string) - The payment network (e.g., `XRPL`, `BTC`, `ETH`).
  - **environment** (string) - The environment of the payment network (e.g., `TESTNET`, `MAINNET`).
  - **addressDetailsType** (string) - The type of address details (e.g., `CryptoAddressDetails`).
  - **addressDetails** (object) - Details of the payment address.
    - **address** (string) - The payment address.
    - **tag** (string) - Optional tag for certain networks.

#### Response Example (XRPL Testnet)
```json
{
  "payId": "alice$example.com",
  "addresses": [
    {
      "paymentNetwork": "XRPL",
      "environment": "TESTNET",
      "addressDetailsType": "CryptoAddressDetails",
      "addressDetails": {
        "address": "rDk7FQvkQxQQNGTtfM2Fr66s7Nm3k87vdS",
        "tag": "123"
      }
    }
  ]
}
```

#### Response Example (ACH)
```json
{
  "address": {
    "account": "363023456079",
    "routing": "011302838"
  }
}
```

#### Response Example (Crypto.com Chain with memo)
```json
{
  "address": "cro1w2kvwrzp23aq54n3amwav4yy4a9ahq2kz2wtmj",
  "memo": "3979714512"
}
```
```

--------------------------------

### Specify Payment Network Accept Headers (Bash)

Source: https://context7.com/paystring/paystring-documentation/llms.txt

Demonstrates how to use the `Accept` header in cURL requests to specify the desired payment network and environment for PayString queries. Includes examples for XRP Ledger, Bitcoin, Ethereum, ACH, Interledger Protocol, and Crypto.com Chain.

```bash
# XRP Ledger networks
curl 'https://example.com/alice' \
  --header 'Accept: application/xrpl-mainnet+json'

curl 'https://example.com/alice' \
  --header 'Accept: application/xrpl-testnet+json'

curl 'https://example.com/alice' \
  --header 'Accept: application/xrpl-devnet+json'

# Bitcoin networks
curl 'https://example.com/alice' \
  --header 'Accept: application/btc-mainnet+json'

curl 'https://example.com/alice' \
  --header 'Accept: application/btc-testnet+json'

# Ethereum networks
curl 'https://example.com/alice' \
  --header 'Accept: application/eth-mainnet+json'

curl 'https://example.com/alice' \
  --header 'Accept: application/eth-ropsten+json'

curl 'https://example.com/alice' \
  --header 'Accept: application/eth-kovan+json'

# ACH (traditional banking)
curl 'https://example.com/alice' \
  --header 'Accept: application/ach+json'

# Response for ACH
{
  "address": {
    "account": "363023456079",
    "routing": "011302838"
  }
}

# Interledger Protocol
curl 'https://example.com/alice' \
  --header 'Accept: application/interledger-mainnet+json'

# Crypto.com Chain
curl 'https://example.com/alice' \
  --header 'Accept: application/cro-mainnet+json'

# Response with memo
{
  "address": "cro1w2kvwrzp23aq54n3amwav4yy4a9ahq2kz2wtmj",
  "memo": "3979714512"
}
```

--------------------------------

### Create PayString User (Bash)

Source: https://context7.com/paystring/paystring-documentation/llms.txt

Adds a new PayString user with payment addresses to the server using cURL POST requests. Examples include creating a user with an XRP Ledger testnet address and another with multiple payment networks (BTC and ETH).

```bash
# Create user with XRP Ledger testnet address
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"
        }
      }
    ]
  }'

# Create user with multiple payment networks
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"
        }
      },
      {
        "paymentNetwork": "ETH",
        "environment": "MAINNET",
        "details": {
          "address": "0x1234567890123456789012345678901234567890"
        }
      }
    ]
  }'
```

--------------------------------

### Fetch PayString via cURL

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/remote-deployment.md

Example cURL command to fetch a PayString from the deployed server. This demonstrates how to retrieve payment details for a given PayString, specifying the desired payment network and environment.

```bash
curl -X GET 'https://<domain.com/user>' --header 'Accept: application/xrpl-mainnet+json' --header 'PayID-version: 1.0'
```

--------------------------------

### Prometheus Query for PayString Count

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/metrics.md

An example Prometheus query to calculate the total sum of PayString counts. This can be used to verify that metrics are being collected successfully by Prometheus.

```prometheus
sum(payid_count)
```

--------------------------------

### WebFinger Query for PayString Discovery

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/paystring-discovery.md

This snippet shows the HTTP GET request a wallet application makes to discover a PayString. It uses the WebFinger protocol to query a server for PayString information. The 'resource' parameter is URL-encoded to represent the PayString.

```http
GET /.well-known/webfinger?resource=payid%3Abob%24receiver.example.com
HTTP/1.1
Host: receiver.example.com
```

--------------------------------

### Stop PayString with Docker Compose (npm)

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/remote-deployment.md

NPM script to stop and remove the PayString service and its associated Docker containers. This is used to bring down the environment started with `npm run devEnvUp`.

```bash
npm run devDown
```

--------------------------------

### PayString Accept Headers for Various Currencies

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/paystring-headers.md

This collection shows example 'Accept' headers for different cryptocurrencies and payment networks supported by PayString. Each header is associated with a specific currency and environment (e.g., mainnet, testnet), and indicates the expected address payload format. This is useful for understanding how to query for addresses across diverse payment systems.

```JSON
{
  "address": "1BvBMSEYstWetAu4m4GFg7xJaNVN2"
}
```

```JSON
{
  "address": "rw2ciyaNshpHe7bCHo4bRWq6pqqynnWKQg",
  "tag": "67298042"
}
```

```JSON
{
  "account": "363023456079",
  "routing": "011302838"
}
```

```JSON
{
  "address": "cro1w2kvwrzp23aq54n3amwav4yy4a9ahq2kz2wtmj",
  "memo": "3979714512"
}
```

```JSON
Variable, depending on the contents of each address
```

--------------------------------

### Add PayString User via Admin API (cURL)

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/remote-deployment.md

Example cURL command to add a new PayString user and their payment addresses to the PayString server. This uses the Admin API and requires JSON data for the user and addresses.

```bash
curl --location --request POST 'http://127.0.0.1:8081/users' \
--header 'PayID-API-Version: 2020-06-16' \
--header 'Content-Type: application/json' \
--data-raw '{
 "payId": "<user$domain.com>",
 "addresses": [{
   "paymentNetwork": "XRPL",
   "environment": "MAINNET",
   "details": {
     "address": "<your-address>"
   }
 }]
}'
```

--------------------------------

### Single User Schema Example (JSON)

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/paystring-schemas.md

This JSON schema represents a single user's payment addresses. It can be used as a payload when creating a user or retrieving user information. A user can have multiple addresses across different payment networks and environments.

```json
{
  "payId": "johndoe$xpring.money",
  "addresses": [
    {
      "paymentNetwork": "XRPL",
      "environment": "TESTNET",
      "details": {
        "address": "TVQWr6BhgBLW2jbFyqqufgq8T9eN7KresB684ZSHKQ3oDth"
      }
    },
    {
      "paymentNetwork": "XRPL",
      "environment": "MAINNET",
      "details": {
        "address": "X7zmKiqEhMznSXgj9cirEnD5sWo3iZSbeFRexSFN1xZ8Ktn"
      }
    }
  ]
}
```

--------------------------------

### Request AWS Certificate for PayString Domain (Shell)

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/aws-lambda-deploy.md

Requests an AWS certificate for a specified domain using the AWS Certificate Manager (ACM) service. This script is a prerequisite for launching the PayString Lambda stack and requires the AWS CLI to be installed and configured. It outputs the necessary CNAME record to validate domain ownership.

```shell
#!/bin/bash

if [ -z "$1" ]; then
  echo "Usage: $0 <domain-name>"
  exit 1
fi

DOMAIN_NAME=$1

echo "Requesting certificate for $DOMAIN_NAME"
CERT_ARN=$(aws acm request-certificate --domain-name $DOMAIN_NAME --validation-method DNS --region us-east-1 --query 'CertificateArn' --output text)

if [ -z "$CERT_ARN" ]; then
  echo "Failed to request certificate."
  exit 1
fi

echo "Certificate requested. ARN: $CERT_ARN"

CNAME_VALIDATION=$(aws acm describe-certificate --certificate-arn $CERT_ARN --region us-east-1 --query 'Certificate.DomainValidationOptions[0].ResourceRecord.Name' --output text)
CNAME_TARGET=$(aws acm describe-certificate --certificate-arn $CERT_ARN --region us-east-1 --query 'Certificate.DomainValidationOptions[0].ResourceRecord.Value' --output text)

echo "Please create the following CNAME record for your domain:"
echo "$CNAME_VALIDATION\tCNAME\t$CNAME_TARGET"

```

--------------------------------

### PayString Data Interfaces (TypeScript)

Source: https://context7.com/paystring/paystring-documentation/llms.txt

TypeScript interfaces defining the data structures for the PayString protocol. This includes interfaces for payment information, address details types, crypto addresses, fiat addresses, and the main address object. An example usage is provided to illustrate how these interfaces can be applied.

```typescript
// Payment Information Response
interface PaymentInformation {
  addresses: Address[]
  payId?: string
  memo?: string
}

// Address Details Type Enum
enum AddressDetailsType {
  CryptoAddress = 'CryptoAddressDetails'
  FiatAddress = 'FiatAddressDetails'
}

// Cryptocurrency Address Details
interface CryptoAddressDetails {
  address: string
  tag?: string  // Optional destination tag for networks like XRP
}

// Fiat/ACH Address Details
interface FiatAddressDetails {
  accountNumber: string
  routingNumber?: string
}

// Address Object
interface Address {
  paymentNetwork: string      // e.g., 'XRPL', 'BTC', 'ETH'
  environment?: string         // e.g., 'MAINNET', 'TESTNET'
  addressDetailsType: AddressDetailsType
  addressDetails: CryptoAddressDetails | FiatAddressDetails
}

// Example usage
const paymentInfo: PaymentInformation = {
  payId: "alice$example.com",
  addresses: [
    {
      paymentNetwork: "XRPL",
      environment: "MAINNET",
      addressDetailsType: AddressDetailsType.CryptoAddress,
      addressDetails: {
        address: "rP3t3JStqWPYd8H88WfBYh3v84qqYzbHQ6",
        tag: "12345"
      }
    },
    {
      paymentNetwork: "ACH",
      addressDetailsType: AddressDetailsType.FiatAddress,
      addressDetails: {
        accountNumber: "363023456079",
        routingNumber: "011302838"
      }
    }
  ]
}

```

--------------------------------

### Docker Deployment for PayString Docs

Source: https://context7.com/paystring/paystring-documentation/llms.txt

Commands to build and run the PayString documentation site using Docker. Supports environment variable configuration for release environments.

```bash
# docker build -t paystring-docs .
# docker run -p 3000:3000 paystring-docs

# With environment variables
# docker run -p 3000:3000 \
#   -e RELEASE_ENV=prod \
#   paystring-docs
```

--------------------------------

### Clone PayString Reference Implementation

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/deploy-with-docker.md

Clones the official PayString reference implementation from GitHub. This is the first step to setting up a local PayString server for development.

```shell
git clone https://github.com/paystring/paystring.git
```

--------------------------------

### PayString Server Development Commands (npm)

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/paystring-reference-overview.md

These npm commands are used to manage the local development environment for the PayString reference implementation. They facilitate setting up, managing, and tearing down Docker containers for the database and the server.

```bash
npm run devEnvUp
npm run devDbUp
npm run devDown
```

--------------------------------

### PayString CLI - Create and Manage

Source: https://context7.com/paystring/paystring-documentation/llms.txt

Commands for initializing new PayStrings, adding various cryptocurrency addresses (XRP Ledger, Bitcoin), saving configurations, and removing addresses. Supports chained commands for streamlined workflows.

```bash
# Initialize new PayString
payid init cleopatra$example.com

# Add XRP Ledger mainnet address with destination tag
payid crypto-address add xrpl mainnet rP3t3JStqWPYd8H88WfBYh3v84qqYzbHQ6 12345

# Add Bitcoin mainnet address
payid crypto-address add btc mainnet 3M2CH71P6uZTra1PsjiEhNFB7kCENShCgt

# Save to local file (creates example.json)
payid save

# Remove a specific address
payid crypto-address remove "rwcBVJwXdXusY5SgNMjHbMWbR2Nnt2U3R6"

# Chain commands together in single-command mode
payid init 'my$pay.id' && \
  payid crypto-address add btc mainnet notARealAddress && \
  payid save
```

--------------------------------

### Create Docker Network for PayString

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/metrics-tutorial.md

Creates a Docker network named 'paystring-network' to allow communication between PayString server containers.

```bash
docker network create paystring-network
```

--------------------------------

### Create and Save a New PayString with Address Mappings

Source: https://github.com/paystring/paystring-documentation/blob/master/docs/paystring-cli.md

This snippet shows how to initialize a new PayString, add multiple cryptocurrency address mappings for different networks and protocols, and then save the resulting PayString configuration to a JSON file. It's a foundational workflow for setting up a PayString.

```bash
init cleopatra$example.com
crypto-address add xrpl mainnet rP3t3JStqWPYd8H88WfBYh3v84qqYzbHQ6 12345
crypto-address add btc mainnet 3M2CH71P6uZTra1PsjiEhNFB7kCENShCgt
save
```