### Run the PayRam Analytics Agent Setup Script

Source: https://docs.payram.com/mcp/analytics-mcp

Executes the setup script to install and configure the PayRam Analytics MCP server. During setup, you will be prompted to provide the PayRam server URL, admin credentials, OpenAI API key, Telegram bot token, allowed users, and optional auto-update and container start choices.

```bash
./setup_payram_agent.sh
```

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

### Run PayRam installer script

Source: https://docs.payram.com/deployment-guide/quick-setup

Executes the PayRam setup script via curl and bash. Add sudo if elevated privileges are required.

```bash
bash <(curl -fsSL https://payram.com/setup_payram.sh)
```

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

### Install PayRam Shopify plugin via bash script

Source: https://docs.payram.com/plugins

Run this command in your terminal to download and execute the PayRam Shopify installation script. It can be run on any server and will guide you through setup with default values unless you have specific needs.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/PayRam/payram-shopify/main/setup_payram_shopify.sh)"
```

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

### Install PayRam SDK with pnpm

Source: https://docs.payram.com/payram-sdk

Installs the PayRam package using pnpm.

```bash
pnpm add payram
```

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

### Install PayRam on Mainnet

Source: https://docs.payram.com/script/script-usage

Installs PayRam on the mainnet for production environments.

```bash
bash <(curl -fsSL https://payram.com/setup_payram.sh) --mainnet
```

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

### Install PayRam SDK with yarn

Source: https://docs.payram.com/payram-sdk

Installs the PayRam package using yarn.

```bash
yarn add payram
```

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

### Install PayRam on Testnet

Source: https://docs.payram.com/script/script-usage

Installs PayRam on the testnet for development environments.

```bash
bash <(curl -fsSL https://payram.com/setup_payram.sh) --testnet
```

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

### Install PayRam SDK with npm

Source: https://docs.payram.com/payram-sdk

Installs the PayRam npm package using npm.

```bash
npm install payram
```

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

### Run the updated PayRam container

Source: https://docs.payram.com/deployment-guide/advanced-setup

Starts the updated container using the previously saved configuration values. Ensure all environment variables and volume mappings match the previous setup to avoid data loss or startup errors.

```bash
docker run -d \
--name payram \
--publish 80:80 \
--publish 443:443 \
-e AES_KEY="" \ # Use the saved AES_KEY
-e SSL_CERT_PATH="" \ # Use the saved SSL_CERT_PATH
-e BLOCKCHAIN_NETWORK_TYPE="" \ # Use the saved BLOCKCHAIN_NETWORK_TYPE
-e SERVER="" \ # Use the saved SERVER value
-e POSTGRES_HOST="" \ # Use the saved POSTGRES_HOST
-e POSTGRES_PORT="" \ # Use the saved POSTGRES_PORT
-e POSTGRES_DATABASE="" \ # Use the saved POSTGRES_DATABASE
-e POSTGRES_USERNAME="" \ # Use the saved POSTGRES_USERNAME
-e POSTGRES_PASSWORD="" \ # Use the saved POSTGRES_PASSWORD
-e POSTGRES_SSLMODE="prefer" \
-v "$WORKDIR:/root/payram" \ # Map your application data directory (WORKDIR)
-v "$WORKDIR/log/supervisord:/var/log" \ 
-v "$WORKDIR/db/postgres:/var/lib/payram/db/postgres" \ # Map Postgres data directory
-v /etc/letsencrypt:/etc/letsencrypt \ # Mount host certs (if SSL_CERT_PATH set previously)
payramapp/payram:<version>
```

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

### PostgreSQL Connection URL Example

Source: https://docs.payram.com/deployment-guide/advanced-setup

Example of a standard PostgreSQL connection string provided by managed database services.

```text
postgres://payram_user:very_strong_password_here@mydb.xxxxxx.us-east-1.rds.amazonaws.com:5432/payram
```

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

### Example Request with curl

Source: https://docs.payram.com/api-integration/payouts-apis/get-all-payouts

Example curl request to fetch payouts with pagination, sorting, and status filter. Replace ${BASE_URL} and <API_KEY> with your server URL and project API key.

```bash
curl --location --request GET \
  '${BASE_URL}/api/v1/withdrawal/merchant?limit=10&offset=0&order=DESC&sortBy=created_at&status=sent' \
  --header 'API-Key: <API_KEY>' \
  --header 'Content-Type: application/json'
```

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

### Example Response (200 OK)

Source: https://docs.payram.com/api-integration/payouts-apis/get-all-payouts

Example 200 OK response showing a JSON array of payout objects. Fields include status, type, amount, addresses, and timestamps; note that attributes may contain a JSON string with approval reason.

```json
[
  {
    "id": 159,
    "createdAt": "2026-06-19T18:44:02.511Z",
    "updatedAt": "2026-06-19T18:45:10.882Z",
    "blockchainCode": "BASE",
    "currencyCode": "USDC",
    "currencyType": "token",
    "amount": "1.00",
    "priceInUSD": "1",
    "amountInUSD": "1.000000",
    "fee": "0.000021",
    "fromAddress": "0x21d4cF2E…EA8d45",
    "toAddress": "0x6df1fc38…133ddf",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "recipientEmail": "akash@payram.com",
    "txHash": "0xf382aa63…ea103b",
    "uniqueTxHash": "0xf382aa63…ea103b-12",
    "txIndex": 12,
    "blockHash": "0x…",
    "blockNumber": 21897412,
    "status": "processed",
    "type": "payout_merchant",
    "attributes": null,
    "failureReason": null,
    "webhookStatus": "received",
    "retryCount": 0,
    "timestamp": "2026-06-19T18:44:02.511Z",
    "memberID": 1,
    "externalPlatformID": 1,
    "currencyID": 3,
    "blockchainID": 4,
    "createdBy": "user"
  },
  {
    "id": 160,
    "blockchainCode": "POLYGON",
    "currencyCode": "POL",
    "currencyType": "coin",
    "amount": "14.00",
    "amountInUSD": "1.068102",
    "toAddress": "0xd553af7e…f7f11f",
    "tokenAddress": "0x0000000000000000000000000000000000000000",
    "recipientEmail": "akash@payram.com",
    "txHash": null,
    "status": "pending-approval",
    "type": "payout_merchant",
    "attributes": "{\"approvalReason\":\"daily_limit_exceeded\"}",
    "failureReason": null,
    "createdBy": "user"
  }
]
```

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

### Example Response for Single Payout

Source: https://docs.payram.com/api-integration/payouts-apis/get-single-payout

Example 200 OK response containing a single payout object. The shape matches the items in Get All Payouts; see Key Response Fields there for field meanings.

```json
{
  "id": 120,
  "createdAt": "2026-06-19T13:14:41.806Z",
  "updatedAt": "2026-06-19T13:18:02.114Z",
  "blockchainCode": "ETH",
  "currencyCode": "USDC",
  "currencyType": "token",
  "amount": "100",
  "priceInUSD": "1",
  "amountInUSD": "100.000000",
  "fee": "0.000412",
  "fromAddress": "0x21d4cF2E…EA8d45",
  "toAddress": "0x9F8E7D6C…65432",
  "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "recipientEmail": "test@test.com",
  "txHash": "0xabc123…def456",
  "status": "sent",
  "type": "payout_merchant",
  "attributes": null,
  "failureReason": null,
  "webhookStatus": "received",
  "createdBy": "user"
}
```

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

### Get Ticker Request

Source: https://docs.payram.com/api-integration/payouts-apis/create-payouts

Example cURL request to fetch live USD prices for configured currencies.

```curl
curl --location --request GET '${BASE_URL}/api/v1/ticker'
```

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

### GET /api/v1/withdrawal/{id}/merchant

Source: https://docs.payram.com/api-integration/payouts-apis/get-single-payout

Documentation for retrieving a single payout by ID, including authentication, parameters, request/response examples, and error handling.

```APIDOC
## GET {BASE_URL}/api/v1/withdrawal/{id}/merchant

### Description
Retrieves a single payout record by its ID, including details and current status. Use this endpoint to poll the status of a payout after creating it.

### Method
GET

### Endpoint
{BASE_URL}/api/v1/withdrawal/{id}/merchant

### Parameters
#### Path Parameters
- **id** (string) - Required - The payout ID returned by Create Payout.

### Headers
- **API-Key** (string) - Required - Project API key. Example: `be703fa47ebe07121102ee260fb3d5c0`
- **Content-Type** (string) - Required - `application/json`

### Request Example
```
curl --location --request GET \
  '${BASE_URL}/api/v1/withdrawal/120/merchant' \
  --header 'API-Key: <API_KEY>' \
  --header 'Content-Type: application/json'
```

### Response
#### Success Response (200)
Returns a single payout object with the same shape as items in Get All Payouts. Key fields include:
- **id** (number) - Payout ID.
- **createdAt** (string) - Creation timestamp.
- **updatedAt** (string) - Last update timestamp.
- **blockchainCode** (string) - Blockchain code (e.g., ETH).
- **currencyCode** (string) - Currency code (e.g., USDC).
- **currencyType** (string) - Type of currency (e.g., token).
- **amount** (string) - Payout amount.
- **priceInUSD** (string) - Price in USD.
- **amountInUSD** (string) - Amount in USD.
- **fee** (string) - Transaction fee.
- **fromAddress** (string) - Sender address.
- **toAddress** (string) - Recipient address.
- **tokenAddress** (string) - Token contract address.
- **recipientEmail** (string) - Recipient email.
- **txHash** (string) - Transaction hash.
- **status** (string) - Current status (e.g., sent).
- **type** (string) - Payout type (e.g., payout_merchant).
- **attributes** (object|null) - Additional attributes.
- **failureReason** (string|null) - Failure reason if failed.
- **webhookStatus** (string) - Webhook status.
- **createdBy** (string) - Creator identifier.

#### Response Example
```
{
  "id": 120,
  "createdAt": "2026-06-19T13:14:41.806Z",
  "updatedAt": "2026-06-19T13:18:02.114Z",
  "blockchainCode": "ETH",
  "currencyCode": "USDC",
  "currencyType": "token",
  "amount": "100",
  "priceInUSD": "1",
  "amountInUSD": "100.000000",
  "fee": "0.000412",
  "fromAddress": "0x21d4cF2E…EA8d45",
  "toAddress": "0x9F8E7D6C…65432",
  "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "recipientEmail": "test@test.com",
  "txHash": "0xabc123…def456",
  "status": "sent",
  "type": "payout_merchant",
  "attributes": null,
  "failureReason": null,
  "webhookStatus": "received",
  "createdBy": "user"
}
```

### Error Responses
- **401** - Missing/invalid API-Key, or a non-project key.
- **404** - No payout with that id in your project (or endpoint not present on PayRam < v3.1.1). Response: `{ "message": "not found" }`.

### Notes
- Requires PayRam v3.1.1 or later.
- Results are scoped to the API key's own project; a payout ID from a different project returns 404.
- Type-restricted to merchant payouts (`payout_merchant`).
- Poll this endpoint until the payout reaches a terminal state (`processed`, `failed`, `rejected`, `cancelled`).
```

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

### Get Blockchain Currencies - curl response

Source: https://docs.payram.com/api-integration/payments-api/get-blockchain-currencies

Example response from the Get Blockchain Currencies API. Returns an array of blockchain currencies with deposit options, including network, currency, token address, precision, and family. customerAddress is empty for first-time users until a deposit address is assigned.

```json
[
  {
    "id": 7,
    "blockchainCode": "BASE",
    "network": "Base",
    "currencyCode": "USDC",
    "currency": "USDC",
    "customerAddress": "",
    "tokenAddress": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
    "standard": "ERC20",
    "walletPrecision": 6,
    "family": "ETH_Family",
    "recommended": false,
    "mostUsed": false,
    "blockchainID": 4,
    "currencyID": 2
  },
  ...
]
```

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

### Get Payout Status using payram.payouts.getPayoutById

Source: https://docs.payram.com/payram-sdk

Retrieve the latest payout details by its ID to check whether the payout is pending, awaiting approval, processing, completed, or failed. The example logs the payout status.

```JavaScript
const payout = await payram.payouts.getPayoutById(42);

console.log(payout.status);
```

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

### Initialize Data Directory

Source: https://docs.payram.com/deployment-guide/advanced-setup

Create a local directory for PayRam data and set the WORKDIR environment variable to point to it.

```bash
mkdir -p <your-folder>
export WORKDIR="<your-folder>"
```

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

### Initiate Payment with payram.payments.initiatePayment

Source: https://docs.payram.com/payram-sdk

Creates a new payment session by sending customer details and the amount to PayRam. Requires customerEmail, customerId, and amountInUSD. Returns a reference_id for tracking and a url to redirect the customer to the PayRam payment page.

```javascript
// Start a new payment
const checkout = await payram.payments.initiatePayment({
  customerEmail: 'customer@example.com',
  customerId: 'cust_123',
  amountInUSD: 49.99,
});

console.log(checkout.reference_id);  // unique payment ID
console.log(checkout.url);  // redirect your customer here
```

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

### Run PayRam Container (arm64)

Source: https://docs.payram.com/deployment-guide/advanced-setup

Start the PayRam container on arm64 architecture (Apple Silicon, AWS Graviton, Raspberry Pi). Verify your architecture with 'uname -m' (should return 'aarch64').

```bash
docker run -d \
  --name payram-testnet \
  --publish 80:80 \
  -e AES_KEY="$AES_KEY" \
  -e SSL_CERT_PATH="" \
  -e BLOCKCHAIN_NETWORK_TYPE="testnet" \
  -e SERVER="DEVELOPMENT" \
  -e POSTGRES_HOST="localhost" \
  -e POSTGRES_PORT="5432" \
  -e POSTGRES_DATABASE="payram" \
  -e POSTGRES_USERNAME="payram" \
  -e POSTGRES_PASSWORD="payram123" \
  -e POSTGRES_SSLMODE="prefer" \
  -e PAYMENTS_APP_SERVER_URL="https://x.payram.com" \
  -v "$WORKDIR:/root/payram" \
  -v "$WORKDIR/log/supervisord:/var/log" \
  -v "$WORKDIR/db/postgres:/var/lib/payram/db/postgres" \
  payramapp/payram:latest-arm64
```