# Welcome to PayRam

**The complete self-hosted payments stack for global commerce.**\
Accept payments globally, monetize anything in minutes, with **no middlemen**, **censorship-resistant settlement**, and full custody, data, and control on your own infrastructure.

***

<figure><img src="/files/Hl5JDjBfGnZby0QiIHMH" alt=""><figcaption></figcaption></figure>

### What is PayRam?

PayRam is a self-hosted PayFi platform for stablecoin and cryptocurrency payments.

It lets you accept and settle payments directly onchain, with no middlemen, no custody risk, and full control over your funds and data.

Built for **financial liberalization**, PayRam is censorship-resistant, programmable, and designed to help anyone run global commerce on infrastructure they own without any middlemen.

***

### Get started with PayRam

Deploy your own PayRam instance, connect wallets, and start accepting stablecoin payments globally, all in minutes, on infrastructure you control.

Simply Copy this and get started

{% code title="Copy paste to terminal for guided quick install" overflow="wrap" fullWidth="true" expandable="true" %}

```bash

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

```

{% endcode %}

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>Deployment Guide</strong></td><td>Set up and host PayRam in in under 10 minutes</td><td><a href="https://docs.payram.com/deployment-guide/introduction">https://docs.payram.com/deployment-guide/introduction</a></td><td><a href="/files/SnWVsIhF28qTl691Yiq8">/files/SnWVsIhF28qTl691Yiq8</a></td></tr><tr><td><strong>Onboarding Guide</strong></td><td>Connect wallets and start accepting payments</td><td><a href="https://docs.payram.com/onboarding-guide/introduction">https://docs.payram.com/onboarding-guide/introduction</a></td><td><a href="/files/kGC4ireNwPt7vgK3NmxL">/files/kGC4ireNwPt7vgK3NmxL</a></td></tr><tr><td><strong>PayRam Features</strong></td><td>See what makes PayRam powerful</td><td><a href="https://docs.payram.com/features/payment-links">https://docs.payram.com/features/payment-links</a></td><td><a href="/files/OqYt91p4gZaSdLi9KWQJ">/files/OqYt91p4gZaSdLi9KWQJ</a></td></tr></tbody></table>

***

### For Agents, Copilot, Claude or OpenClaw

Get tons of help from our hosted MCP server

```
https://mcp.payram.com
// Copy this to your AI chat and ask
// "Setup payram for crypto payments and share link with me, take help from mcp.payram.com
```

If you are an agent then you can install a full stack payment solution for your humans. There is no signup or KYC so its agent friendly. You can explore the hosted <https://mcp.payram.com> to explore all skills including Crypto Payments comparison.

### Need help?

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Community Support</strong></td><td>Drop us a DM or tag us on X (formerly Twitter)</td><td><a href="https://x.com/PayRamApp">https://x.com/PayRamApp</a></td></tr><tr><td><strong>Contact Support</strong></td><td>Setup faster! Get direct help from our team.</td><td><a href="https://payram.short.gy/payram-gitbook-contact">https://payram.short.gy/payram-gitbook-contact</a></td></tr></tbody></table>

<figure><img src="/files/XHQikxsfafkh5QdiLR0O" alt=""><figcaption></figcaption></figure>

***

<br>


# What's New

### <mark style="color:$primary;">15-August-2025: Announcing PayRam 1.5 release.</mark>

<a href="https://chatgpt.com/?prompt=Please+read+and+explain+this+documentation+page%3A+https%3A%2F%2Fdocs.payram.com%2Fintroduction%2Fwhats-new%2F%0A%0APlease+provide+a+clear+summary+and+help+me+understand+the+key+concepts+covered+in+this+documentation" class="button primary" data-icon="up-right">Ask ChatGPT about this page</a>

This release marks a major milestone for us. We’ve reworked the architecture of our core blockchain orchestration stack, pushing forward our mission to make crypto payments effortless, secure, and future-ready.

At PayRam, our guiding principle has always been security. We don’t store private keys, and we never compromise on how funds are received and swept. Today, we’re taking that philosophy even further.

### Meet PayRam SmartSweep

With **SmartSweep**, you no longer need to set up xPUBs or manually authorize wallets across chains. For any blockchain that supports smart contracts, deposit wallets are now nearly instant to configure. It’s the simplest way to start accepting crypto.

Seamlessly, you can support multiple ERC-20 and TRC-20 tokens without worrying about orchestration, consolidation, or sweeps. PayRam automatically deploys a family of smart contracts that securely collect and route funds straight to your cold wallets—without ever exposing a private key on your servers.

SmartSweep isn’t just an upgrade. It’s a new industry standard.

### Faster onboarding, zero hassle

Getting started has never been easier. We’ve redesigned our onboarding flow to guide you step-by-step, so you can set up and begin accepting funds in as little as **10 minutes**.

### In the works

This is just the beginning. Support for **Solana** and **Ton** with SmartSweep is already in the works, and we can’t wait to share more.

Thank you for building with us. With your support, we’re setting a higher bar for the future of payments.


# PayRam Usecases

PayRam is global payment infrastructure built for internet-native businesses that want to accept crypto and stablecoins with flexibility and control. This section outlines who it’s designed for and how different business models can use it.

PayRam enables:

* **Global payments** (crypto + stablecoins, with fiat interoperability where needed)
* **Onramp and card-to-crypto payments**, allowing users to convert traditional payment methods into crypto seamlessly
* **Flexible custody models** (hosted or self-hosted)
* **Fast settlement with onchain transparency**
* **Simple integration via APIs, payment links, and webhooks**
* **Agentic payments support**, including compatibility with MCP for AI-driven and autonomous payment flows

### Primary User Categories

PayRam serves a wide range of digital-first businesses, from merchants and SaaS platforms to crypto-native startups and enterprises. Below is a high-level overview of the primary user segments that benefit from its infrastructure.

* [Online Merchants](https://calendly.com/payram-sales/payram-demo-accept-crypto-payments-docs)
* [SaaS & Subscription Businesses](https://calendly.com/payram-sales/payram-demo-accept-crypto-payments-docs)
* [Crypto-native Businesses](https://docs.payram.com/introduction/payram-usecases#crypto-native-startups)
* [Marketplaces & Platforms](https://docs.payram.com/introduction/payram-usecases#marketplaces-and-platforms)
* [Charities & Non-profits](https://docs.payram.com/introduction/payram-usecases#marketplaces-and-platforms)
* [Freelancers & Remote Professionals](https://docs.payram.com/introduction/payram-usecases#freelancers-and-remote-professionals)
* [High-Risk & Cross-Border Businesses](https://docs.payram.com/introduction/payram-usecases#high-risk-and-cross-border-businesses)
* [iGaming & Casino Platforms](https://docs.payram.com/introduction/payram-usecases#igaming-and-casino-platforms)
* [Enterprises & Traditional Businesses Expanding into Crypto](https://docs.payram.com/introduction/payram-usecases#enterprises-and-traditional-businesses-expanding-into-crypto)
* [Developers & Technical Teams](https://docs.payram.com/introduction/payram-usecases#developers-and-technical-teams)
* [Infrastructure Partners & Platforms](https://docs.payram.com/introduction/payram-usecases#infrastructure-partners-and-platforms)
* [Agentic Payments (AI & Autonomous Systems)](https://docs.payram.com/introduction/payram-usecases#agentic-payments-ai-and-autonomous-systems)

***

### Online Merchants

Merchants are at the core of PayRam’s ecosystem, enabling them to accept global payments without relying entirely on traditional gateways. Whether selling online or in-store, PayRam provides faster settlement and greater payment control.

#### Online Stores (Digital & Physical Goods and Services)

**What merchants can do:**

* Accept crypto & stablecoins at checkout
* Offer seamless self-hosted payment pages
* Integrate via API for custom checkout flows
* Use webhooks for real-time payment confirmations
* Get faster settlement compared to traditional gateways
* Reduce exposure to chargebacks

This is ideal for:

* Shopify/WooCommerce stores
* D2C brands
* Digital product sellers
* Cross-border sellers targeting global audiences
* VPN/VPS hosting providers

#### Physical & Hybrid Businesses

For businesses operating both online and offline:

* QR-based payments for in-store transactions
* Cross-border acceptance without relying solely on local banking rails
* Stablecoin settlement for predictable cash flow

This is particularly valuable in regions with unstable banking access or high FX volatility.

***

### SaaS & Subscription Businesses

SaaS platforms can use PayRam to monetize global users without depending solely on card networks. It enables stablecoin payments, automation, and improved payment reliability across borders.

(**Note:** Native subscription billing is not yet supported, but it is on the PayRam roadmap.)

**Current capabilities:**

* One-time payments via links or API
* Stablecoin acceptance for global customers
* Reduced failed payments (no card expiration issues)
* Automation via webhooks and backend integrations

**Coming Soon:**

* Native recurring billing in stablecoins

**PayRam is especially useful for:**

* SaaS with global user bases
* AI tools monetizing worldwide
* Platforms serving regions underserved by card networks

***

### Crypto-native Startups

For web3-native companies, PayRam aligns with decentralized principles while simplifying monetization. It provides multi-chain acceptance and flexible custody without compromising onchain transparency.

**Capabilities:**

* Multi-chain payment acceptance
* Onchain settlement visibility
* Custodial and self-custodial flexibility
* Stablecoin-first architecture
* Programmatic fund handling

Use cases include:

* NFT platforms
* DeFi dashboards
* Web3 gaming
* Token-gated services

PayRam allows crypto-native businesses to monetize without reverting to traditional intermediaries.

***

### Marketplaces & Platforms

Marketplaces require programmable payment flows, vendor payouts, and split settlements. PayRam supports these complex payment structures while reducing chargeback and operational friction.

PayRam supports:

* Split payments between platform and vendors
* Vendor payouts in stablecoins
* Programmatic routing of funds
* Reduced chargeback exposure
* Transparent settlement

Ideal for:

* Service marketplaces
* Creator platforms
* Gig economy platforms
* B2B trade platforms

***

### Charity & Non-profits

For charities and social initiatives:

* Accept global donations in crypto & stablecoins
* Operate without complex international banking setups
* Get started with minimal paperwork
* Increase transparency via onchain settlement

This opens access to global donors without relying solely on card processors.

***

### Freelancers & Remote Professionals

Independent professionals can use PayRam to receive cross-border payments quickly and efficiently. Payment links and stablecoin settlement reduce FX costs and gateway dependency.

**Key benefits:**

* Shareable payment links & invoices
* Stablecoin settlement
* Lower FX friction
* Faster cross-border payments
* Reduced risk of payment gateway bans

Perfect for:

* Designers
* Developers
* Consultants
* Creators
* Remote contractors

Instead of waiting for bank wires or losing money to FX spreads, freelancers can receive direct onchain payments.

***

### High-Risk & Cross-Border Businesses

Businesses facing payment restrictions or account freezes can leverage PayRam for more predictable cash flow. Crypto-based payments reduce chargebacks and expand global accessibility.

Many legitimate businesses struggle with:

* Sudden account freezes
* Gateway bans
* Chargebacks
* Limited geographic coverage

PayRam helps by offering:

* Chargeback-free crypto payments
* Predictable cash flow
* Reduced dependency on centralized processors
* Global accessibility

This is especially relevant for:

* Cross-border service providers
* Content platforms
* Businesses operating in emerging markets

***

### iGaming & Casino Platforms

iGaming platforms can use PayRam to serve underserved markets with stablecoin-based deposits. It reduces reliance on traditional processors while improving settlement speed and privacy.

PayRam supports:

* Serving underserved regions
* Stablecoin-based deposits
* Reduced reliance on card networks
* No sharing of user-personifying payment data with third parties
* Faster settlement cycles

This enables smoother player onboarding and improved liquidity management.

***

### Enterprises & Traditional Businesses Expanding into Crypto

Enterprises can integrate crypto payments without replacing their existing financial stack. PayRam enables stablecoin pilots, international expansion, and modular deployment options.

For established companies exploring crypto:

* Add crypto payments without replacing existing systems
* Run stablecoin pilot programs
* Enable crypto checkout for select markets
* Use hosted solutions or deploy self-hosted infrastructure
* Expand internationally without fully rebuilding payment rails

PayRam acts as an extension to your existing stack, not a forced replacement.

***

### Developers & Technical Teams

PayRam is built for technical teams that need APIs, webhooks, and programmable workflows. It removes the need to run blockchain infrastructure while maintaining flexibility.

**Technical features:**

* REST APIs
* Webhooks for event-driven automation
* Hosted + self-hosted deployment flexibility
* No need to run your own blockchain infrastructure
* Modular architecture

Developers can integrate:

* Custom checkout flows
* Automated accounting logic
* Internal treasury dashboards
* Platform-level fund routing

***

### Infrastructure Partners & Platforms

Fintech platforms and payment enablers can integrate PayRam to power their own merchant ecosystems. White-label opportunities and embedded finance models make it adaptable for infrastructure-level use.

PayRam can also serve:

* Platforms enabling payments for their merchants
* White-label payment providers
* Fintech infrastructure companies
* Embedded finance platforms

**Opportunities include:**

* White-label integrations
* Payment enablement layers
* Value-added financial services on top of PayRam rails

***

### Agentic Payments (AI & Autonomous Systems)

PayRam supports autonomous, machine-to-machine transactions for AI agents and programmable systems. It enables a future where software can generate, receive, and manage payments independently.

**Supported concepts:**

* PayRam MCP (Model Context Protocol support)
* x402-based payment authentication
* ERC-8004 programmable payment standards
* Integration with AI frameworks like OpenClaw agents

Use cases:

* AI agents selling services
* Autonomous API-to-API payments
* Machine-to-machine transactions
* Monetized AI tools

This moves payments from “human checkout” to programmable, agent-driven value exchange.

***

### Summary: Is PayRam Right for You?

PayRam is best suited for:

* Internet-native businesses
* Cross-border operators
* Crypto-aligned founders
* Marketplaces and platforms
* High-growth startups
* Teams that value control over custody and settlement
* Builders preparing for agentic commerce

You might prefer fully self-hosted alternatives if:

* You want to run all blockchain infrastructure internally
* You require completely custom treasury logic from day one
* You operate under regulatory constraints requiring traditional-only payment rails

PayRam is global, programmable payment infrastructure for businesses that want control, flexibility, and borderless monetization, without rebuilding the entire financial stack from scratch.

There are zero setup costs, no subscription fees, and no collateral deposit requirements. Merchants can simply install and self-host PayRam on their own servers. With just one line of code, you can deploy your entire payments stack in under 10 minutes.

Whether you’re a startup, marketplace, SaaS platform, or enterprise expanding into crypto, PayRam gives you the infrastructure to accept, manage, and route payments globally with full control.

***

### Deploy or Talk to Us

#### **Deploy Now**

Install PayRam and launch your payment infrastructure in minutes

<a href="https://docs.payram.com/deployment-guide/introduction?utm_source=usecase" class="button primary">Deployment Guide</a>

#### **Get a Demo**

Want to see how it fits your use case?

<a href="https://calendly.com/payram-sales/payram-demo-accept-crypto-payments-docs" class="button primary">Book a Call</a>


# Introduction

In this section, you’ll explore two ways to deploy your PayRam server using the setup script or Docker. By the end, you’ll be able to install, configure, and launch PayRam securely and efficiently.

<figure><img src="/files/SnWVsIhF28qTl691Yiq8" alt=""><figcaption></figcaption></figure>

## PayRam installation methods

You can set up your PayRam server using one of two deployment methods, each designed to suit different experience levels and setup preferences.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>⚡ <strong>Quick Setup</strong></td><td>Use the PayRam script to install, configure, and start accepting payments in under 10 minutes!</td><td><a href="https://docs.payram.com/deployment-guide/quick-setup">https://docs.payram.com/deployment-guide/quick-setup</a></td></tr><tr><td>⚙️ <strong>Advanced Setup</strong></td><td>Install PayRam on Docker by manually configuring containers, storage, networks, and variables.</td><td><a href="https://docs.payram.com/deployment-guide/advanced-setup">https://docs.payram.com/deployment-guide/advanced-setup</a></td></tr></tbody></table>


# Quick Setup

Deploy, configure, and start accepting payments on PayRam in under 10 minutes!

In this section, you’ll go through the complete setup of your PayRam server, including installation, security configuration, and encryption, to ensure it is fully prepared and running smoothly.

***

## **Prerequisites**

Before starting, please ensure your system meets the following requirements:

### **Server configuration**

* Use a VPS or dedicated server with the minimum specifications required to host the PayRam server.

{% hint style="info" %} <mark style="color:$primary;">**Recommended VPS Providers:**</mark>

* **AWS**
* **Google Cloud (GCP)**
* **Azure**
* **Hetzner**
* **Hostinger**
  {% endhint %}

### **Minimum server requirements**

* **CPU**: 2 cores
* **RAM**: 4 GB
* **Storage**: 50 GB SSD
* **Operating System**: Ubuntu 22.04

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: Depending on your expected usage and scale, additional resources may be required.</mark>
{% endhint %}

### **Network requirements**

* Ensure the following ports are open on your server or VPS:

  | Port | Purpose                                                                                |
  | ---- | -------------------------------------------------------------------------------------- |
  | 80   | Used for running the Frontend (FE) on standard HTTP protocol.                          |
  | 8080 | Used for running the Backend (BE) services on HTTP.                                    |
  | 443  | Required for the Frontend when serving the application over HTTPS (secure connection). |
  | 8443 | Required for the Backend when serving APIs over HTTPS (secure connection).             |
  | 5432 | Used by the PostgreSQL Database for database connections.                              |

### Database configuration&#x20;

* To run PayRam smoothly, you must provision a PostgreSQL database with the following minimum configuration:

  **Minimum database requirements**:

  * **Database engine**: PostgreSQL
  * **vCPUs**: 1 CPU cores
  * **Memory**: 1 GB
  * **Storage**: 50 GB SSD

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark> <mark style="color:$info;">: These are the baseline requirements. Using a smaller configuration may cause performance issues during high transaction loads or while processing sweeps. You can scale up depending on the expected transaction volume.</mark>
{% endhint %}

***

## PayRam setup

{% stepper %}
{% step %}

### Connect to your VPS

* Use SSH to connect to your server instance.
  {% endstep %}

{% step %}

### &#x20;Choose your network

* Decide whether to install on mainnet or testnet, based on your requirements.

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark> <mark style="color:$info;">: Based on your requirements, choose the network on which you want to install PayRam. The Mainnet is used for production purposes, while the Testnet is used for development and testing PayRam features.</mark>
{% endhint %}

{% tabs %}
{% tab title="Mainnet" %}

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

{% endtab %}

{% tab title="Testnet" %}

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

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Run the command

* Now, open your terminal and enter the command. Add sudo before the command if elevated privileges are required.

<figure><img src="/files/ksEgZXFtUMdY7JvZiBZs" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Installing necessary dependencies

* When you run the command, the script handles the entire PayRam setup automatically. It checks for previous installations, validates required ports, detects the operating system, and ensures compatibility. Next, it installs or verifies Docker and PostgreSQL, creates the needed directories, and performs a disk space check. If any problems are found (such as low storage), the script will display a warning and ask you to confirm whether to proceed by typing Y or N.

<figure><img src="/files/VgKHxEO2pHFJqzSLbITO" alt="This is darwins masterpiece"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Database setup

* Once the installation is complete, you will be prompted to choose between an External PostgreSQL Database or a Containerized PostgreSQL Database for setup.

<figure><img src="/files/pzyJx2hdDUUOvKQEhiYb" alt=""><figcaption></figcaption></figure>

* You can select any of the options based on your requirement&#x20;
  * Option 1
  * Option 2

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark> <mark style="color:$info;">: Option 1 is recommended for production environments.</mark>
{% endhint %}

{% tabs %}
{% tab title="Option 1" %}

* If you select **Option 1**, you’ll be prompted to enter the following details:

  * **Database Host**
  * **Port**
  * **Database Name**
  * **Username**
  * **Password**

  These details establish the connection between PayRam and your PostgreSQL database.
* You can find them in your PostgreSQL server configuration or your hosting provider’s control panel. If you’re using a managed PostgreSQL service (for example, AWS RDS, Azure Database, or DigitalOcean), these values are available in the database connection settings.
* **Example connection string**:

  ```bash
  postgresql://myuser:mypassword@db.example.com:5432/mydatabase
  ```

  * In this example:
    * `myuser` → Database username
    * `mypassword` → Database password
    * `db.example.com` → Database host
    * `5432` → Database port
    * `mydatabase` → Database name
      {% endtab %}

{% tab title="Option 2" %}
{% hint style="info" %} <mark style="color:$primary;">**Note**</mark> <mark style="color:$info;">: This option is for testing only. For production environments, always use Option 1.</mark>
{% endhint %}

* If you select **Option 2**, the script creates a local PostgreSQL database using Docker with the following default credentials:

  ```bash
    postgres.host: "localhost"
    postgres.port: "5432"
    postgres.database: "payram"
    postgres.username: "payram"
    postgres.password: "payram123"
  ```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### SSL configuration

* After setting up the database, the script will prompt you to configure SSL by choosing from Let’s Encrypt (auto-generate free SSL), Custom Certificates (upload your own), or External SSL (cloud/proxy services).

<figure><img src="/files/GIPWLReqfrz5ctWD1bxd" alt=""><figcaption></figcaption></figure>

* You need to select one option from the three
  * Option 1
  * Option 2
  * Option 3

{% tabs %}
{% tab title="Option 1" %}

* If you select Option 1, Let’s Encrypt will automatically generate and install a free SSL certificate for your domain within minutes, with certificates trusted by all browsers and auto-renewed every 90 days.

<figure><img src="/files/qopqzjdWWPQhCXl65dL3" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Option 2" %}

* Select Option 2 if you already have your own SSL certificates. When prompted, provide the file path to the certificate files. The path you specify must contain two files: fullchain.pem and privkey.pem.

<figure><img src="/files/Ze9yQPlj9UVLPO3rl3Es" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Option 3" %}

* Select Option 3 if you’re generating SSL through a cloud service or if you want to skip SSL configuration.

<figure><img src="/files/UCGiWvU5KGfT2dLVEQmB" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### AES key encryption

* After selecting your SSL option, you will be prompted with the Hot Wallet Encryption Setup screen. At this step, press Enter to generate the AES-256 encryption key for your hot wallet.

<figure><img src="/files/Pnv4InlYzlU7BCf8DOzB" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Review the settings

* The script then displays all the configurations you selected. Review the settings carefully to make sure they are correct before proceeding.

<figure><img src="/files/SG98dsKkIDtmU6De1Om5" alt=""><figcaption></figcaption></figure>

* If the configuration is correct, press Enter and the script will set up the PayRam server based on the options you selected. This will start installing the payram server based on your configurations

<figure><img src="/files/X37uHL3nPfFtFB1nptnU" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Installation completed

* After the installation completes, a confirmation message appears in the terminal.

<figure><img src="/files/9idKFVtXkOEq59nJqT59" alt=""><figcaption></figcaption></figure>

Once the installation is complete, you’ll see “PayRam installation completed successfully” in the logs. You can then go to [http://](http://yourserverip.com/)[yourserverip](http://yourserverip.com/)[.com](http://yourserverip.com/), replacing yourserverip with the IP address or domain where the PayRam server is hosted.
{% endstep %}
{% endstepper %}

***

Now that you’ve successfully completed the setup, please go to the [onboarding configuration](/onboarding-guide/root-account-setup) to start setting up your root account for PayRam.


# Advanced Setup

In this section, you’ll set up your PayRam server using Docker, covering installation, security configuration, and encryption to ensure your server is fully prepared and running smoothly.

***

## Docker installation

PayRam can be run using Docker, which provides a clean, isolated environment and avoids operating system or tooling incompatibilities. It also makes managing the database and environment variables simple and straightforward.

You can run PayRam inside a Docker container in any os with a simple command, either on testnet for development or on mainnet for production.

***

## Technical knowledge requirements for self-hosting

Running PayRam on your own servers requires understanding of technical concepts such as:

* Installing and managing Docker containers
* Allocating system resources effectively
* Securing servers and sensitive data
* Configuring environment variables and application settings correctly

Incorrect setup can result in data loss, security risks, or downtime.

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark> <mark style="color:$info;">: If you do not have Docker installed or have limited technical knowledge, there is a Easy Method available that can install and configure your PayRam server in just less than 5 minutes.</mark>&#x20;

<mark style="color:$success;">**Checkout the Easy Method here :**</mark> [Quick Setup](/deployment-guide/quick-setup)
{% endhint %}

***

## Hardware requirements

### Server configuration

* Use a VPS or dedicated server with the minimum specifications required to host the PayRam server.

### **Minimum server requirements:**

* **CPU**: 2 cores
* **RAM**: 4 GB
* **Storage**: 50 GB SSD
* **Operating System**: Ubuntu 22.04

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: Depending on your expected usage and scale, additional resources may be required.</mark>
{% endhint %}

### **Network requirements**

* Ensure the following ports are open on your server or VPS:

  | Port | Purpose                                                                                |
  | ---- | -------------------------------------------------------------------------------------- |
  | 80   | Used for running the Frontend (FE) on standard HTTP protocol.                          |
  | 8080 | Used for running the Backend (BE) services on HTTP.                                    |
  | 443  | Required for the Frontend when serving the application over HTTPS (secure connection). |
  | 8443 | Required for the Backend when serving APIs over HTTPS (secure connection).             |
  | 5432 | Used by the PostgreSQL Database for database connections.                              |

***

## Quick start

* Use this guide to run PayRam with Docker on testnet for local setup and testing. See below for instructions on deploying PayRam in production on the mainnet.
* Assuming you have Docker installed and running, pull the latest PayRam image and start a container

{% hint style="info" %} <mark style="color:$success;">**Note**</mark><mark style="color:$info;">: When running the Docker command, do not modify the port mappings. Changing the default ports may cause PayRam to stop working correctly or prevent it from connecting to required services.</mark>
{% endhint %}

{% tabs %}
{% tab title="amd64" %}

```dockerfile
docker run -d \
  --name payram-testnet \
  --publish 8080:8080 \
  --publish 80:80 \
  --publish 5432:5432 \
  -e AES_KEY="366502f6c3e3d828d903691bcc8f46e0d009b70477076b6417cef0a3974b78e8" \
  -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 "home/payram:/root/payram" \
  -v "home/payram/log/supervisord:/var/log" \
  -v "home/payram/db/postgres:/var/lib/payram/db/postgres" \
  payramapp/payram:latest
```

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark>**&#x20;:** <mark style="color:$info;">Use this build if your machine runs on an Intel or AMD processor. This covers most Linux servers, Windows PCs, and default cloud VMs (AWS EC2, Google Cloud, Azure). To confirm your architecture, run</mark> <mark style="color:$info;"></mark><mark style="color:$info;">`uname -m`</mark> <mark style="color:$info;"></mark><mark style="color:$info;">in your terminal — if it returns</mark> <mark style="color:$info;"></mark><mark style="color:$info;">`x86_64`</mark><mark style="color:$info;">, you're good to go with this build.</mark>
{% endhint %}
{% endtab %}

{% tab title="arm64" %}

```docker
docker run -d \
  --name payram-testnet \
  --publish 8080:8080 \
  --publish 80:80 \
  --publish 5432:5432 \
  -e AES_KEY="366502f6c3e3d828d903691bcc8f46e0d009b70477076b6417cef0a3974b78e8" \
  -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 "home/payram:/root/payram" \
  -v "home/payram/log/supervisord:/var/log" \
  -v "home/payram/db/postgres:/var/lib/payram/db/postgres" \
  payramapp/payram:latest-arm64
```

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark>**&#x20;:** <mark style="color:$info;">Use this build if you're on an Apple Silicon Mac (M1, M2, M3), AWS Graviton instance, or Raspberry Pi. To confirm, run</mark> <mark style="color:$info;"></mark><mark style="color:$info;">`uname -m`</mark> <mark style="color:$info;"></mark><mark style="color:$info;">in your terminal — if it returns</mark> <mark style="color:$info;"></mark><mark style="color:$info;">`aarch64`</mark><mark style="color:$info;">, use this build.</mark>
{% endhint %}
{% endtab %}
{% endtabs %}

This command does the following:

* **Runs PayRam in the background** (-d) with the name payram-testnet.
* **Exposes ports**:
  * 8080 → PayRam internal API access
  * 80 → HTTP access
  * 5432 → Postgres database access
* **Sets environment variables**:
  * AES\_KEY: Encryption key used for securing data.
  * SSL\_CERT\_PATH: Path to SSL certificates (optional in testnet).
  * BLOCKCHAIN\_NETWORK\_TYPE: Configures the blockchain network (testnet).
  * SERVER: Marks the environment as DEVELOPMENT.
  * POSTGRES\_\*: Database connection details.
* **Mounts volumes**:
  * home/payram:/root/payram → Application data.
  * home/payram/log/supervisord:/var/log → Log files.
  * home/payram/db/postgres\:/var/lib/payram/db/postgres → Database storage.
  * Pulls and runs the PayRam Docker image: payramapp/payram:1.6.0.

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: After the installation is complete, you can access PayRam at <https://your-domain.com/login>.</mark>

<mark style="color:$info;">For detailed configuration steps, refer to the</mark> [<mark style="color:$info;">Merchant Guide</mark>](/onboarding-guide/introduction) <mark style="color:$info;">for further instructions.</mark>
{% endhint %}

***

## Advance setup

* If you’re running PayRam in production, keep the following in mind: you need to configure an external database, set up proper SSL certificates, and generate your own unique AES key for security.

### AES key generation

* A secure encryption key required by PayRam.
* In production, you should generate your own **AES key** using:

  ```bash
  openssl rand -hex 32
  ```
* Example in Docker:

  ```bash
  -e AES_KEY="366502f6c3e3d828d903691bcc8f46e0d009b70477076b6417cef0a3974b78e8"
  ```

### Postgres setup

To run **PayRam** safely and reliably in a production environment, you must connect it to an **external PostgreSQL database** hosted by a trusted and managed provider. Local or containerized databases should not be used in production, as they are not secure, scalable, or fault-tolerant.

* Recommended PostgreSQL providers include:
  * **Amazon RDS for PostgreSQL / Aurora PostgreSQL**
  * **Google Cloud SQL for PostgreSQL**
  * **Azure Database for PostgreSQL**
  * **DigitalOcean Managed PostgreSQL**

#### **Required environment variables**

* When your provider gives you a connection URL, simply take each part of it and map it to PayRam’s required environment variables.

  <pre class="language-bash" data-full-width="false"><code class="lang-bash">postgres://payram_user:very_strong_password_here@mydb.xxxxxx.us-east-1.rds.amazonaws.com:5432/payram
  </code></pre>
* The following example shows how this connection URL can be expressed as environment variables for PayRam:

```bash
-e POSTGRES_HOST="mydb.xxxxxx.us-east-1.rds.amazonaws.com"
-e POSTGRES_PORT="5432"
-e POSTGRES_DATABASE="payram"
-e POSTGRES_USERNAME="payram_user"
-e POSTGRES_PASSWORD="very_strong_password_here"
```

### SSL configuration

* PayRam requires **SSL/TLS certificates** to enable secure **HTTPS** connections in production.
* If you are using a third-party provider such as **Cloudflare** or **AWS Load Balancer** that manages HTTPS for you, you can leave this value empty:

  ```bash
  -e SSL_CERT_PATH=""
  ```
* If you are managing certificates yourself on the PayRam server, you must point this variable to the directory where your domain’s SSL/TLS certificates are stored.
* The most common setup is with **Let’s Encrypt**, which stores certificates in:

  ```bash
  -e SSL_CERT_PATH="/etc/letsencrypt/live/your-domain.com"
  ```
* Ensure the directory contains the correct certificate files for your domain (commonly fullchain.pem and privkey.pem).

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: Setting the SSL\_CERT\_PATH is required only if you manage HTTPS directly on your PayRam server.If you’re using a third-party service such as Cloudflare that already handles HTTPS, you can leave this value "</mark><mark style="color:blue;">**SSL\_CERT\_PATH**</mark><mark style="color:$info;">" empty.</mark>
{% endhint %}

### Production setup

Before starting PayRam for the first time, make sure you **note down and store all necessary configurations securely**. These will be required for future updates or troubleshooting:

* **AES\_KEY** → Keep a copy of the key securely; required for decrypting data in future updates.
* **Postgres details** → Database name, username, password, and port. You will need the same details to reconnect or update.
* **Volume paths (WORKDIR)** → Note the host paths you plan to use for data, logs, and database files (e.g., `/home/payram`). These must remain consistent for updates

{% tabs %}
{% tab title="amd64" %}

```
docker run -d \                                    
  --name payram-mainnet \                          
  --publish 8080:8080 \                            
  --publish 8443:8443 \                           
  --publish 80:80 \                                
  --publish 443:443 \                              
  --publish 5432:5432 \                            
  -e AES_KEY="replace_with_random_hex_key" \       # Secure AES encryption key (MUST generate your own for production)
  -e SSL_CERT_PATH="" \  # Path to SSL certs (mandatory in production unless using external TLS termination)
  -e BLOCKCHAIN_NETWORK_TYPE="mainnet" \           
  -e SERVER="PRODUCTION" \                         
  -e POSTGRES_HOST="" \                   # External Postgres host (replace if using cloud DB)
  -e POSTGRES_PORT="" \                        # Postgres port
  -e POSTGRES_DATABASE="" \                  # Database name (replace with production DB)
  -e POSTGRES_USERNAME="" \                  # Database username (replace with production user)
  -e POSTGRES_PASSWORD="" \     # Database password (replace with production password)
  -e POSTGRES_SSLMODE="prefer" \
  -e PAYMENTS_APP_SERVER_URL="https://x.payram.com" \
  -v "$WORKDIR:/root/payram" \                     # Application data directory (replace $WORKDIR with your path)
  -v "$WORKDIR/log/supervisord:/var/log" \         # Log files directory
  -v "$WORKDIR/db/postgres:/var/lib/payram/db/postgres" \ # Postgres data directory (if self-hosted)
  -v /etc/letsencrypt:/etc/letsencrypt \           # Mount host certs into container (needed if SSL_CERT_PATH set)
  payramapp/payram:latest                         
```

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark>**&#x20;:** <mark style="color:$info;">Use this build if your machine runs on an Intel or AMD processor. This covers most Linux servers, Windows PCs, and default cloud VMs (AWS EC2, Google Cloud, Azure). To confirm your architecture, run</mark> <mark style="color:$info;"></mark><mark style="color:$info;">`uname -m`</mark> <mark style="color:$info;"></mark><mark style="color:$info;">in your terminal — if it returns</mark> <mark style="color:$info;"></mark><mark style="color:$info;">`x86_64`</mark><mark style="color:$info;">, you're good to go with this build.</mark>
{% endhint %}
{% endtab %}

{% tab title="arm64" %}

```
docker run -d \                                    
  --name payram-mainnet \                          
  --publish 8080  :8080 \                            
  --publish 8443:8443 \                           
  --publish 80:80 \                                
  --publish 443:443 \                              
  --publish 5432:5432 \                            
  -e AES_KEY="replace_with_random_hex_key" \       # Secure AES encryption key (MUST generate your own for production)
  -e SSL_CERT_PATH="" \  # Path to SSL certs (mandatory in production unless using external TLS termination)
  -e BLOCKCHAIN_NETWORK_TYPE="mainnet" \           
  -e SERVER="PRODUCTION" \                         
  -e POSTGRES_HOST="" \                   # External Postgres host (replace if using cloud DB)
  -e POSTGRES_PORT="" \                        # Postgres port
  -e POSTGRES_DATABASE="" \                  # Database name (replace with production DB)
  -e POSTGRES_USERNAME="" \                  # Database username (replace with production user)
  -e POSTGRES_PASSWORD="" \     # Database password (replace with production password)
  -e POSTGRES_SSLMODE="prefer" \
  -e PAYMENTS_APP_SERVER_URL="https://x.payram.com" \
  -v "$WORKDIR:/root/payram" \                     # Application data directory (replace $WORKDIR with your path)
  -v "$WORKDIR/log/supervisord:/var/log" \         # Log files directory
  -v "$WORKDIR/db/postgres:/var/lib/payram/db/postgres" \ # Postgres data directory (if self-hosted)
  -v /etc/letsencrypt:/etc/letsencrypt \           # Mount host certs into container (needed if SSL_CERT_PATH set)
  payramapp/payram:latest-arm64                         
```

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark>**&#x20;:** <mark style="color:$info;">Use this build if you're on an Apple Silicon Mac (M1, M2, M3), AWS Graviton instance, or Raspberry Pi. To confirm, run</mark> <mark style="color:$info;"></mark><mark style="color:$info;">`uname -m`</mark> <mark style="color:$info;"></mark><mark style="color:$info;">in your terminal — if it returns</mark> <mark style="color:$info;"></mark><mark style="color:$info;">`aarch64`</mark><mark style="color:$info;">, use this build.</mark>
{% endhint %}
{% endtab %}
{% endtabs %}

#### **What does this command do?**

* **Runs PayRam on mainnet** in a Docker container.
* **Maps and exposes ports**:
  * 8080 → internal API access
  * 8443 → secure HTTPS API
  * 80 → standard HTTP
  * 443 → HTTPS (requires valid SSL certs)
  * 5432 → Postgres access

⚠️ **Important on HTTPS:**

* If you **set SSL\_CERT\_PATH and mount certs**, HTTPS (443, 8443) will work and PayRam will serve securely.
* If you **leave SSL\_CERT\_PATH=""**, PayRam will only serve over HTTP. This is acceptable if you use an external TLS termination service (like Cloudflare, reverse proxy, or load balancer).
* **Configures environment variables**:
  * AES\_KEY must be a secure random hex string in production.
  * SERVER=PRODUCTION ensures PayRam runs in production mode.
  * Postgres settings must point to your **production-grade database**.
* **Mounts volumes**:
  * $WORKDIR:/root/payram → application data.
  * $WORKDIR/log/supervisord:/var/log → logs.
  * $WORKDIR/db/postgres\:/var/lib/payram/db/postgres → Postgres storage (only if self-hosted).
  * /etc/letsencrypt:/etc/letsencrypt → host SSL certs (required if SSL\_CERT\_PATH is set).

***

## Updating PayRam Docker container

{% stepper %}
{% step %}

### Prepare before updating

Before stopping or removing any containers, make sure you **note down all current configurations**:

* **AES\_KEY** → Must be the same as the current container, otherwise PayRam will fail to decrypt data.
* **Postgres details** → Database name, username, password, and port must remain the same.
* **Volume mappings** → Use the exact same host paths to persist data (e.g., /home/ubuntu/payram, /home/ubuntu/payram/log/supervisord, /home/ubuntu/payram/db/postgres).
* **SSL\_CERT\_PATH** → Keep the same configuration (empty for testnet, or set if using SSL).
* **Network type and SERVER environment** → Must be the same as the current container (testnet & DEVELOPMENT, mainnet & PRODUCTION) or it will cause issues.

{% hint style="info" %} <mark style="color:$info;">**If any of these are changed, you may lose access to stored data or encounter startup errors.**</mark>
{% endhint %}
{% endstep %}

{% step %}

### Check running containers

```
docker ps
```

This shows the currently running PayRam container. Note the **CONTAINER ID** or **NAME**.
{% endstep %}

{% step %}

### Stop the running container

```
docker stop <CONTAINER_ID_OR_NAME>
```

{% endstep %}

{% step %}

### Remove the stopped container

```
docker rm <CONTAINER_ID_OR_NAME>
```

{% endstep %}

{% step %}

### Check existing images

```
docker images
```

{% endstep %}

{% step %}

### Remove the old image

```
docker rmi <IMAGE_ID>
```

{% endstep %}

{% step %}

### Run the updated container

Start PayRam again with the new version using your saved configuration values. Make sure to use the same AES key, database, server, and other details as before to avoid errors.

```docker
docker run -d \\
--name payram \\
--publish 8080:8080 \\ 
--publish 8443:8443 \\
--publish 80:80 \\
--publish 443:443 \\
--publish 5432:5432 \\
-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>
```

{% endstep %}

{% step %}

### Verify the update

```
docker ps
```

You should now see the container running with the new version.
{% endstep %}
{% endstepper %}

***

Done! All your data and configurations are preserved while updating PayRam.


# Introduction

<figure><img src="/files/kGC4ireNwPt7vgK3NmxL" alt=""><figcaption></figcaption></figure>

The Merchant Guide provides a step-by-step walkthrough to help you set up and manage PayRam for accepting payments.&#x20;

Each section covers an essential part of the process, starting from onboarding and node configuration, to wallet management, payment link generation, hot wallet setup, and funds sweeping.&#x20;

Follow this guide in order to ensure a smooth integration and secure payment flow for your business.


# Root Account Setup

In this section, you’ll complete the initial setup for your root account, which serves as the main administrator account for your PayRam server. By the end, your root account will be ready to manage a

***

## **Prerequisites**

Before you proceed with the onboarding configuration, make sure the following steps are completed:

* Install the PayRam server and ensure it is running.
* If you haven’t completed the installation, do that first by following the Installation Guide.

***

## Root account setup

{% stepper %}
{% step %}

### Go to the IP address

* Open your browser and go to your domain’s IP address or the URL where you hosted your PayRam server. The PayRam welcome page appears.

<figure><img src="/files/Nr67oGfk93lm8ydxySLw" alt=""><figcaption></figcaption></figure>

* If you’re seeing this page that means you’re payram server is up and running

{% endstep %}

{% step %}

### Navigate to signup page

* Navigate to the signup URL, for example: http\://\<your-ip-address>/signup, and replace with the actual IP address or domain of your PayRam server.
* Create your root account. This account will have full administrative control over all configurations and settings

<figure><img src="/files/hePimDcvg4EXJhNFMFH1" alt=""><figcaption></figcaption></figure>

* Click on Next Button

{% endstep %}

{% step %}

### Setup root email

* Enter your root email in the input box. Make sure to remember this email, as it will be the root/admin account for your PayRam server.

<figure><img src="/files/qlq7iGkP6sYgXdchV8I6" alt=""><figcaption></figcaption></figure>

* Enter your email address and select Continue.
  {% endstep %}

{% step %}

### Setup root password

* Now you need to set up a password for your root/admin account and make sure to save it securely or remember it, so you don’t lose access to your root account. You can change your password later from the dashboard if needed.

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: When creating your root account, make sure to remember or securely store the email and password. These credentials are required to log in as the main administrator of your PayRam server.</mark>
{% endhint %}

<figure><img src="/files/RBBpFpfOI3D0QoqBHgzU" alt=""><figcaption></figcaption></figure>

* Create a password that meets the required criteria and click the Continue button.
  {% endstep %}

{% step %}

### Setup project name

* Now you need to set up your project name. A project refers to a website or product where you plan to integrate the PayRam payment system.

<figure><img src="/files/cixV6eOLD9LKzmNGQGhY" alt=""><figcaption></figcaption></figure>

* Enter the name of your project and click the Continue to Dashboard button.
  {% endstep %}
  {% endstepper %}

***

You have successfully completed the onboarding configuration. Now, proceed to Node Details Configuration to set up your dashboard settings.


# Node Details Configuration

In this section, you will configure the node details of the blockchain where you want to accept payments. You can set up any blockchain that you wish to use for receiving payments.

***

## **Prerequisites**

Before you proceed with the node configuration, make sure the following steps are completed:

* Install the [PayRam](https://www.notion.so/PayRam-Setup-2782637ada87802ba500e9d01a595075?pvs=21) and complete the [onboarding configuration](https://docs.payram.com/onboarding-guide/root-account-setup).
* Ensure the server is running and ready, so you can connect your blockchain nodes without issues.

***

## Nodes configuration :

{% stepper %}
{% step %}

### Dashboard page

* Once you have successfully completed the Onboarding configuration, you will be redirected to the dashboard .

<figure><img src="/files/55G2TeIueuTtvoUrhJik" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Settings

* Before accepting any payments, you need to configure the blockchain nodes based on the network you selected while installing PayRam. For example, if you chose mainnet, configure the mainnet nodes, and if you chose testnet, configure the testnet nodes accordingly.
* Now click on the Settings

<figure><img src="/files/8emJZnpAvM1JQgB5cYC0" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Integrations

* Then select integrations

<figure><img src="/files/Va8wJejIERO6A12XT5e0" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Node configurations

* Under **Node Details**, you will find the node configuration information

<figure><img src="/files/uGte1Y2CzFOGZnV7sZwn" alt=""><figcaption></figcaption></figure>

* The node details are already set up with some public RPC URLs. However, if you want to use any private RPC URLs, you can update the configuration according

> <mark style="color:$success;">**Note**</mark><mark style="color:$info;">: If the “</mark><mark style="color:$danger;">**Last Block Processed**</mark><mark style="color:$info;">” rows are not updating, you’ll need to restart your PayRam server. Please run the restart command script on the server where PayRam is hosted.</mark>
>
> [👉 View Restart Command Guide](https://docs.payram.com/script/script-usage#restart)
> {% endstep %}
> {% endstepper %}

***

If you do not want to use the default node RPC provided by us and instead prefer to use your own private RPC, you can change the node configuration details by following the link below and updating the RPC URL with your custom endpoint.

***

You’ve successfully added the required node details for a blockchain, the node configuration is complete. The next step is to add the corresponding wallets for those blockchains, which is necessary before you can start receiving PayRam payments.


# Wallet Integration

In this section, you will begin the process of setting up your wallets, ensuring that everything is ready so you can start receiving payments seamlessly.

***

## **Prerequisites**

Before you proceed with setting up your wallets, make sure the following steps are completed:

* Install [PayRam](/deployment-guide/quick-setup) and ensure it is fully set up on your server.
* Successfully [configure the Blockchain node](/onboarding-guide/node-details-configuration) where you plan to accept payments.

***

## Understanding some key terms&#x20;

* Before configuring your wallets, it's essential to understand how the different wallet types work together in our payment system. This section explains the key components and their relationships
  * Master account
  * Deposit wallets
  * Cold wallet
  * Sweep contract

### <sub>Master account</sub>&#x20;

* The master account is the merchant’s primary blockchain account that serves as the foundation for generating deposit wallet addresses. Every deposit wallet provided to customers for making payments is derived from this master account, ensuring all payment addresses remain linked to a single, consistent source. This setup allows the system to track, manage, and associate payments accurately under the merchant’s account
* In addition to generating deposit wallets, the master account is also used to deploy the sweep contract.

### Deposit wallets

* A deposit wallet is a blockchain address where customers send their payments. All deposit wallets are derived from the merchant’s master account and can exist on different supported blockchains. Each deposit wallet acts as a unique payment destination for a transaction or customer, while still being linked to the same master account for tracking and management purposes.

### Cold wallet&#x20;

* A cold wallet is a secure blockchain wallet used for storing funds offline or in a highly secure environment. Unlike deposit wallets, which are generated for receiving payments from customers, the cold wallet serves as the merchant’s main storage address where funds are ultimately consolidated. Cold wallets are not directly exposed to customers, reducing the risk of unauthorized access and improving overall fund security.

{% hint style="info" %} <mark style="color:$primary;">**NOTE**</mark> <mark style="color:$info;">: While configuring wallets, make sure to use different wallets for the master account and the cold wallet. Do not use the same wallet for both; always configure separate ones.</mark>
{% endhint %}

***

## Configuring wallets&#x20;

{% stepper %}
{% step %}

### Open wallet management tab

* Click on the Wallet Management tab and select Deposit Wallet to set up your wallets.

<figure><img src="/files/AyrrPXDIpC7HePGoS7yz" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Choose blockchain

* Now select the blockchain where you want to accept payments and configure your wallet accordingly. This setup ensures you'll only receive payments on your specific chosen chain.
  {% endstep %}

{% step %}

### Configure wallets on each chain

* Below are the steps for each chain how you can configure the wallet&#x20;
  * EVM Family (Base & Ethereum)
  * TRX
  * Bitcoin

{% tabs %}
{% tab title="Base" %}
{% hint style="info" %} <mark style="color:$primary;">**Note**</mark>**:** <mark style="color:$info;">When deploying contract addresses within the EVM family (e.g., Base, Ethereum), make sure to use the same master account for all networks in the family to ensure users receive consistent deposit addresses across blockchains</mark>
{% endhint %}

### Step 1

* Click on EVM family to expand the section. You will see options to deploy the contract

<figure><img src="/files/FcmYYABJJG7scnYXwIP8" alt=""><figcaption></figcaption></figure>

### Step 2

* In the EVM Family section, you can deploy contracts on both the Base and Ethereum blockchains. This means you will be able to accept payments on Base and Ethereum once the contracts are deployed there.

<figure><img src="/files/01ZpSPpE7cN1JpHPeYZa" alt=""><figcaption></figcaption></figure>

### Step 3

* Now click on Deploy Contract and choose either Base or Ethereum. The process is the same for both; in this example, I am deploying the contract on the Base chain.

<figure><img src="/files/vap6nLN4iJreDF73pCSF" alt=""><figcaption></figcaption></figure>

### Step 4

* You will see a pop-up screen where you can enter the required details, such as the master account and the cold wallet address.

<figure><img src="/files/q8Qsvua6nzy2zs1QqKuN" alt=""><figcaption></figcaption></figure>

### Step 5

* Enter the required details, connect your master account, provide the cold wallet address, and add a wallet name. You can connect your master account using any wallet provider, such as MetaMask or WalletConnect, but it must support the Base network because we are deploying the contract on the Base blockchain. Therefore, it should be a Base-compatible wallet.
* Once you’ve added all the necessary details click on deploy contract

<figure><img src="/files/5fjFEDIvQWOJrHXuL6yG" alt=""><figcaption></figcaption></figure>

* Wait until the contract get Deployed, Once deployed it will look like this

<figure><img src="/files/htKBDMJ3IUTYLz9GfAVW" alt=""><figcaption></figcaption></figure>

### Step 6

* Once you’ve successfully deployed the contract and entered all the necessary details, the screen will look like this. It will display information such as the fund sweeper address, the master account address, and confirming that your setup is ready to receive payments.

<figure><img src="/files/kJbyCGzksURELF1KMVY4" alt=""><figcaption></figcaption></figure>

* Congratulations, you are now ready to accept payments from your customers on the Base blockchain and its supported tokens.
  {% endtab %}

{% tab title="Ethereum" %}
{% hint style="info" %} <mark style="color:$primary;">**Note**</mark>**:** <mark style="color:$info;">When deploying contract addresses within the EVM family (e.g., Base, Ethereum), make sure to use the same master account for all networks in the family to ensure users receive consistent deposit addresses across blockchains</mark>
{% endhint %}

### Step 1

* Click on EVM family to expand the section. You will see options to deploy the contract

<figure><img src="/files/FcmYYABJJG7scnYXwIP8" alt=""><figcaption></figcaption></figure>

### Step 2

* In the EVM Family section, you can deploy contracts on both the Base and Ethereum blockchains. This means you will be able to accept payments on Base and Ethereum once the contracts are deployed there.

<figure><img src="/files/01ZpSPpE7cN1JpHPeYZa" alt=""><figcaption></figcaption></figure>

### Step 3

* Now click on Deploy Contract and choose either Base or Ethereum. The process is the same for both; in this example, I am deploying the contract on the Base chain.

<figure><img src="/files/vap6nLN4iJreDF73pCSF" alt=""><figcaption></figcaption></figure>

### Step 4

* You will see a pop-up screen where you can enter the required details, such as the master account and the cold wallet address.

<figure><img src="/files/51Ck592X4SYPCwVtgtzh" alt=""><figcaption></figcaption></figure>

### Step 5

* Enter the required details, connect your master account, provide the cold wallet address, and add a wallet name. You can connect your master account using any wallet provider, such as MetaMask or WalletConnect, but it must support the Base network because we are deploying the contract on the Base blockchain. Therefore, it should be a Base-compatible wallet.
* Once you’ve added all the necessary details click on deploy contract

<figure><img src="/files/a4FAr1z7PXHI3O2nl2ij" alt=""><figcaption></figcaption></figure>

* Wait until the contract get Deployed, Once deployed it will look like this

<figure><img src="/files/htKBDMJ3IUTYLz9GfAVW" alt=""><figcaption></figcaption></figure>

### Step 6

* Once you’ve successfully deployed the contract and entered all the necessary details, the screen will look like this. It will display information such as the fund sweeper address, the master account address, and confirming that your setup is ready to receive payments.

<figure><img src="/files/GMzSzi7VGzTJhDJJ9eGl" alt=""><figcaption></figcaption></figure>

* Congratulations, you are now ready to accept payments from your customers on the Etheruem blockchain and its supported tokens.
  {% endtab %}

{% tab title="Tron" %}

### Step 1

* Click on Tron to expand the section. You will see options to deploy the contract

<figure><img src="/files/8xrQyi4WS9xe7vz2hs2P" alt=""><figcaption></figcaption></figure>

* Now click on Deploy contract

<figure><img src="/files/blIbka9r4LorIuq93RHS" alt=""><figcaption></figcaption></figure>

### Step 2

* You will see a pop-up screen where you can enter the required details, such as the master account and the cold wallet address.
* Enter the required details, connect your master account, provide the cold wallet address, and add a wallet name. You can connect your master account using any wallet provider, such as Wallet Connect Id, but it must support Tron because we are deploying the contract on the Tron blockchain. Therefore, it should be a Tron-compatible wallet.

<figure><img src="/files/klO2ngPObLElSsAB7Wwe" alt=""><figcaption></figcaption></figure>

### Step 3

* Once you’ve added all the necessary details click on deploy contract

<figure><img src="/files/5fjFEDIvQWOJrHXuL6yG" alt=""><figcaption></figcaption></figure>

* Wait until the contract get Deployed, Once deployed it will look like this

### Step 4

* Once you’ve successfully deployed the contract and entered all the necessary details, the screen will look like this. It will display information such as the fund sweeper address, the master account address, and confirming that your setup is ready to receive payments.

<figure><img src="/files/rR5T4XP0BLXvaeVktSfW" alt=""><figcaption></figcaption></figure>

* Congratulations, you are now ready to accept payments from your customers on the Tron blockchain and its supported tokens.
  {% endtab %}

{% tab title="Bitcoin" %}
{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: Bitcoin works a little differently from the other chains. For the other chains, we deploy a contract to generate deposit wallets, but for Bitcoin, there is no need to do that. You only need to add a BTC wallet, which will serve as the source for generating deposit wallets, and a cold wallet to receive the funds.</mark>
{% endhint %}

### Step 1

* Click on Bitcoin & Other Networks to expand the section. You will see options to Add wallet

<figure><img src="/files/Z8TL7S2Sr6bPeDtnz65P" alt=""><figcaption></figcaption></figure>

### Step 2

* Now click on Add wallet

<figure><img src="/files/OG6gv0DFKik1qmnQpYpl" alt=""><figcaption></figcaption></figure>

### Step 3&#x20;

* You will see a pop-up screen where you can enter the required details. Enter the 12-word secret phrase of any BTC wallet, which will act as the master account for generating deposit addresses for your customers.
* Make sure to remember this seed phrase, as you will need the exact same phrase when sweeping funds from the PayRam mobile app.

{% hint style="info" %} <mark style="color:$success;">**Note**</mark><mark style="color:$info;">: The seed phrase will never be stored on any server. It is kept only on your PayRam server and protected with encryption.</mark>
{% endhint %}

<figure><img src="/files/Hv3aPz8kp8yKBikmXUkU" alt=""><figcaption></figcaption></figure>

### Step 4&#x20;

* You need to enter the 12-word seed phrase of your BTC wallet.

<figure><img src="/files/z9xm4FxFGY50ivtbBZW4" alt=""><figcaption></figcaption></figure>

* Once you’ve added all the necessary details click on Save & Generate Addresses

<figure><img src="/files/QtDnhawxJGVQ9WHRucEr" alt=""><figcaption></figcaption></figure>

### Step 5

* Once you’ve successfully added the BTC wallet seed phrase, the configuration for generating deposit addresses on Bitcoin is complete. Next, you need to add a cold wallet to receive the funds.

<figure><img src="/files/OFohnSWwTg4xRVAEoG8M" alt=""><figcaption></figcaption></figure>

### Step 6

* Click on Add Cold wallet Button, then you'll be asked to enter the cold wallet

<figure><img src="/files/VG3MiVaUF0YIr8XlhDxZ" alt=""><figcaption></figcaption></figure>

* Once you’ve added the cold wallet, click the Save button. Your cold wallet will then be successfully configured.
* That’s it. You have successfully set up the configuration for BTC wallets, and you can now receive payments from your customers on the BTC network as well.
  {% endtab %}
  {% endtabs %}
  {% endstep %}
  {% endstepper %}

***

You have successfully set up your wallets and can now start receiving payments from your customers. Follow this section to learn how to generate a test payment link or integrate the PayRam server API into your SaaS, dApp, or other applications.


# Testing Payment Links

In this section, you’ll learn how to accept payments from customers using PayRam by creating and sharing a payment link.

***

## Prerequisites

Before generating payment links, ensure the following steps are completed:

* Successfully set up the blockchain node configuration where you will accept payments.
* Complete the wallet management setup so your wallets are ready to receive payments.

***

## Generate payment link&#x20;

{% stepper %}
{% step %}

### Creating payment link

* Go to Payments and expand the section. Select Create Payment Link to generate a new payment link.

<figure><img src="/files/NzU4Vn0tbZ9Q0D1xHWOE" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### How to add a member

* Before you select **Generate Payment Link**, complete these steps:
  1. Add a new member by entering their email, or select an existing member if available.
  2. If this is your first time setting up, the member list is likely empty.
     {% endstep %}

{% step %}

### Add new member

* Select the member email input box. Select Add New Member when the option appears. A pop-up screen opens where you can enter the member’s details.

<figure><img src="/files/K37wlhFNwhf1xoxz2HAJ" alt=""><figcaption></figcaption></figure>

* Enter the customer’s email, select the project, and then select Add Member.

<figure><img src="/files/MST8qNYdPbLxNp7Bv9Q0" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Enter amount

* After you add the member details, enter the amount to charge that user. Select Generate Payment Link. The system generates a link, which you share with your customer.

<figure><img src="/files/jkbDUA4YHQ46v7OP1a81" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### Click on generate payment link

* After you add the member details, enter the amount to charge that user. Select Generate Payment Link. The system generates a link, which you share with your customer.

<figure><img src="/files/gLarNRUhNZjeOSxxztnF" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Payment page

* You'll be redirected to a payment link you can share that to your customer

<figure><img src="/files/8QYQP9Mohzao8oiAvmAk" alt=""><figcaption></figcaption></figure>

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: If you generate a payment link and the deposit address appears blank, it means the blocks are not being processed. To fix this, restart your PayRam server by running the reset command script.</mark>

👉 [View Restart Command Guide](/script/script-usage)
{% endhint %}
{% endstep %}

{% step %}

### Select preferred coin and network

* When making a payment, customers can select their preferred coin and network.

<figure><img src="/files/W0glEFuqLcDEpUdk0UIg" alt=""><figcaption></figcaption></figure>

* Currently, PayRam supports these coins and networks.
  {% endstep %}

{% step %}

### Payment successful

* After the customer pays, the status updates once the minimum number of onchain confirmations are complete. When confirmed, the system shows Payment Successful.

<figure><img src="/files/lkjkd7nZonmGrGAua7LD" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

***

You’ve successfully set up PayRam to accept payments. If you want to integrate the PayRam system into your SaaS, dApp, or any other application, you can do so via the API. Visit the API References section to view the complete integration guide.


# Hot Wallet Setup

In this section, you will learn how to set up a hot wallet on the blockchains where you will be accepting payments.

***

## **Prerequisites**

Before setting up a hot wallet, ensure the following steps are completed:

* Install the PayRam server and complete the setup.
* Successfully configure the blockchain node where you will accept payments.
* Verify that your wallets are set up and ready to receive payments.

***

## Understanding key concepts

Before proceeding with the setup steps, please ensure you are familiar with the following concepts, as they are important for managing your wallets effectively:

### **Hot wallet**&#x20;

A hot wallet is the wallet used to cover transaction fees (gas) when sweeping funds from deposit wallets to the cold wallet. Because blockchain transactions require gas, the hot wallet holds the funds needed to pay these fees and enable transfers during the sweep process. Hot wallets are EOA (Externally Owned Account) wallets.

{% hint style="info" %} <mark style="color:$primary;">**NOTE**</mark>**&#x20;**<mark style="color:$info;">**: It is important to always maintain a minimum balance in the hot wallet, otherwise sweep operations will fail**</mark><mark style="color:$info;">.</mark>
{% endhint %}

### **SmartSweep**

The **Smart-sweep** feature helps you automatically move funds from your customer deposit wallets to your main wallet. This reduces manual transfers and ensures funds are consolidated efficiently. Our objective is to simplify daily operations while keeping security on top. For most blockchains, this is done with a family of smart contracts, such that you don’t have to expose keys to sweep funds while PayRam takes care of all the orchestration.

#### SmartSweep eligibility

To enable smart-sweeps, a customer's deposit wallet must first meet a **one-time minimum balance requirement**.

* When this balance is reached, PayRam deploys a **smart wallet contract** to the blockchain.
* If the balance is not reached, the wallet remains **dormant** and no sweeps will occur.
* Also note, you can configure these default requirements; the default is $5 USD worth of assets.

#### How SmartSweep works

Once a wallet is activated, PayRam can sweep funds automatically based on three configurable settings:

1. **Amount:** Smart-sweep is triggered when either,
   * An individual deposit wallet’s balance reaches the set amount, or,
   * The total balance across multiple wallets in a batch reaches the set amount.
2. **Address count:** The sweep occurs after a set number of deposit addresses have received funds.
3. **Time:** The sweep occurs after a set time period has elapsed.

***

## Hot wallet configuration&#x20;

You only need to add hot wallets for the following blockchains&#x20;

* Tron
* EVM Family

{% tabs fullWidth="false" %}
{% tab title="Tron" %}

### **Step 1**&#x20;

* Select Wallet Management to expand the section, and then select Hot Wallet. From here, you can manage your hot wallets.

<figure><img src="/files/oCr44lAtcYn7v4W4iu61" alt=""><figcaption></figcaption></figure>

### Step 2&#x20;

* Now click on Add button on Tron section

<figure><img src="/files/Lmbqbl7Oi3zYUrGQxneG" alt=""><figcaption></figcaption></figure>

### Step 3&#x20;

* Select the **Add** button. A pop-up screen appears.
* In the pop-up screen, you see two options: **Add an existing wallet** or **Create a new wallet**.
  1. If this is your first time, the **Create a new wallet** option is disabled.
  2. Select **Add an existing wallet**.
  3. Select **Continue to add hot wallet**.

<figure><img src="/files/MMPdoScNG7hOqXRedWe7" alt=""><figcaption></figcaption></figure>

### Step 4

* Enter the private key of one of your Tron wallets. Make sure the wallet has enough funds to cover transaction fees so the sweep mechanism works correctly.

<figure><img src="/files/Z7uZmnqdpNiSG4KlNtDX" alt=""><figcaption></figcaption></figure>

### Step 5

* After you enter the private key, select Add Wallet. This adds the wallet as the hot wallet for the Tron blockchain.

<figure><img src="/files/8CeEhiR4lGEHi4Fpw1Ce" alt=""><figcaption></figcaption></figure>

* You have now set up the hot wallet for Tron. When you receive deposits on the Tron chain to your deposit addresses, this hot wallet pays the gas fees for sweeping funds to your cold wallet address.
  {% endtab %}

{% tab title="EVM Family" %}
{% hint style="info" %} <mark style="color:$primary;">**Note**</mark> <mark style="color:$info;">: In the EVM family, configuring an Ethereum hot wallet covers all networks in the family. In this case, Base, Polygon, and Ethereum.</mark>
{% endhint %}

### **Step 1**&#x20;

* Select Wallet Management to expand the section, and then select Hot Wallet. From here, you can manage your hot wallets.

<figure><img src="/files/oCr44lAtcYn7v4W4iu61" alt=""><figcaption></figcaption></figure>

### Step 2&#x20;

* Now click on Add button on EVM Family section

<figure><img src="/files/Lmbqbl7Oi3zYUrGQxneG" alt=""><figcaption></figcaption></figure>

### Step 3&#x20;

* Select the **Add** button. A pop-up screen appears.
* In the pop-up screen, you see two options: **Add an existing wallet** or **Create a new wallet**.

  1. If this is your first time, the **Create a new wallet** option is disabled.
  2. Select **Add an existing wallet**.
  3. Select **Continue to add hot wallet**.

  <figure><img src="/files/Z4H6oIFH3nA1q9rojEhU" alt=""><figcaption></figcaption></figure>

### Step 4

* Enter the private key of one of your EVM wallets. Make sure the wallet has enough funds to cover transaction fees so the sweep mechanism works correctly.

<figure><img src="/files/Z7uZmnqdpNiSG4KlNtDX" alt=""><figcaption></figcaption></figure>

### Step 5

* After you enter the private key, select Add Wallet. This adds the wallet as the hot wallet for the EVM blockchain.

<figure><img src="/files/8CeEhiR4lGEHi4Fpw1Ce" alt=""><figcaption></figcaption></figure>

* You have now set up the hot wallet for EVM Family. When you receive deposits on the EVM chain to your deposit addresses, this hot wallet pays the gas fees for sweeping funds to your cold wallet address.
  {% endtab %}
  {% endtabs %}

***

You’ve successfully completed the hot wallet setup for both the EVM Family and Tron, which enables smart sweeping. If you are also receiving payments in BTC, note that the sweeping process works slightly differently. You can learn more about it \[here].


# Funds Sweeping

In this section, you will learn how fund sweeping works on each blockchain.

***

## **Prerequisites**

Before proceeding with this section, ensure the following steps are completed:

* The PayRam server is installed and running.
* Done with wallet configuration and able to accept payments.
* Hot wallet configuration has been successfully completed.

***

## **Sweep process by blockchain network**

The way sweeping works depends on the blockchain you are using.

{% tabs %}
{% tab title="EVM Family & Tron :" %}

* In the EVM family (Ethereum, Base, Polygon) and Tron, sweeping is handled through the sweep contract you have already deployed. It automatically collects funds from your deposit wallets and sends them to your cold wallet. No additional setup is needed. It's simply magic.
  {% endtab %}

{% tab title="Bitcoin & other networks :" %}

* Bitcoin does not support on-chain smart contracts like EVM and Tron. Sweeping for Bitcoin is done using the PayRam Bitcoin mobile app, which follows a separate process. You will use the app to move funds from your BTC deposit wallets to your cold wallet.
  {% endtab %}
  {% endtabs %}

Check out the BTC sweep process step-by-step guide to learn how to transfer funds using the PayRam mobile app. If you accept payments in BTC, follow this sweep process guide.

{% content-ref url="/pages/WMcsbo96Aeq8pWsyBucU" %}
[Bitcoin Funds Sweep Guide](/onboarding-guide/funds-sweeping/bitcoin-funds-sweep-guide)
{% endcontent-ref %}


# Bitcoin Funds Sweep Guide

In this section you’ll learn how to sweep BTC funds from your deposit addresses to your cold wallet using the PayRam mobile app.

***

### **Prerequisites** <a href="#prerequisites" id="prerequisites"></a>

Before you proceed with the Bitcoin Sweep, make sure the following steps are completed:

* The PayRam server is installed and running.
* Done with wallet configuration and able to accept payments.
* Hot wallet configuration has been successfully completed.
* Ensure you have the PayRam Merchant mobile app installed on your device.
  * To download the app for **Apple Appstore**, [**click here**](https://apps.apple.com/us/app/payram-business-merchant-app/id6759707719)
  * To download the app for **Google Play Store**, [**click here**](https://play.google.com/store/apps/details?id=com.payram.business)

***

{% stepper %}
{% step %}

### Setup PayRam Merchant mobile app

* Navigate to Settings and click on it. Then, go to the Accounts tab. You will see a QR code labeled Connect to PayRam Mobile App. This QR code is used to sync the app with your PayRam server. Download the PayRam mobile app from the app store separately, then scan this QR code to complete the sync.

<figure><img src="/files/6TiEx87sUHjoKdUErAB5" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/7ONovcsq1uJuwTjnVpTU" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### Login to the PayRam app

* Scan the QR code from your phone. Once scanned, you will be prompted to log in. Use the same root login credentials that you used when setting up the PayRam server web application.

<figure><img src="/files/E1zMXSaBcArKXRbMw2UM" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/Z18s5AHrTKtBX3umbaf6" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### Set a passcode

Once the above step is completed, you will be prompted to set up a passcode. This passcode will be used to secure access to the PayRam mobile app on your device.

<figure><img src="/files/qKtJx9hro4vRdMz0Cyab" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/pLxXtxX1hUdDiGHcX5mm" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/e6QZu9foiuh9pNsfmOvU" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### Link wallet

* Now you will see the wallet that you attached during the BTC wallet configuration. You need to select this exact same account so it can be linked here. Click on the link icon, then click on the Link Wallet button. You will be asked to enter the seed phrase, so make sure you have the exact same seed phrase for the account you attached earlier when configuring the BTC wallet. After entering the seed phrase, click Link Wallet to complete the process.

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: The seed phrase will never be stored on any server. It is kept only on your local device storage and protected with encryption.</mark>
{% endhint %}

<figure><img src="/files/z9TYI8BBdF3ZzlCVgFOD" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/KEuMoaXHBBhMkeoN9eLI" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/i3kZbd1RtcYAgPdj7mBe" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### Signing requests tab

* Once you have successfully linked the BTC wallet, you are ready to sweep funds from your BTC deposit wallets to your cold wallet. Go to the Signing Requests tab, where you will see the funds that are ready to be swept. This section will list the deposit addresses where you have received payments, allowing you to sweep them into your cold wallet.
  {% endstep %}

{% step %}

### Signing request rabs sections

In the Signing Requests tab, you will see two sub-tabs

* Pending&#x20;
* In Progress

{% tabs %}
{% tab title="Pending" %}

### **Pending**

* Shows the list of deposit addresses that have received funds and are ready to be swept into your cold wallet.
* These addresses are grouped together in batches for sweeping.
* Clicking on a batch allows you to sweep all funds from the deposit addresses in that batch to your cold wallet.
* For example, if a batch contains 1,400 deposit addresses, all of them have funds ready to sweep.
* If you see two batches, that means there are 2,800 deposit addresses ready to be swept.
* Simply approve and verify these sweeps to move the funds.

<figure><img src="/files/vm5jJhbus5tS5q0QOjhV" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/mruxHM28qvS8RK0GMM4J" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/l2TeEN4yl9mutep1f6i0" alt=""><figcaption></figcaption></figure>

{% endtab %}

{% tab title="In progress" %}

### **In progress**

* Shows batches of deposit addresses where sweeping has already started.
* Displays the status of each sweep, including whether all funds have been successfully transferred to your cold wallet.

<figure><img src="/files/MmhAaid5FCPRsVynfc1g" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

{% endstep %}

{% step %}

### Sweeps completed

* Once the sweeps are fully completed, you can check the transaction status by moving from the In Progress tab to the History tab.

<figure><img src="/files/1yVcvYSvDFFQT5bYtcbx" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/d1efI8ZQ2cVyGi7OVjwd" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}


# Operator Mode

Operator Mode lets you manage multiple merchants under a single PayRam account. By the end of this setup, your operator account will be ready to onboard merchants, collect fees, and manage chain-level

***

### Prerequisites

Before you proceed with the Operator Mode configuration, make sure the following steps are completed:

* Install [PayRam](https://www.notion.so/2782637ada87802ba500e9d01a595075) and complete the [onboarding configuration](https://docs.payram.com/onboarding-guide/root-account-setup).

***

### Operator mode setup

{% stepper %}
{% step %}

### Select operator mode

<figure><img src="/files/qqjOdumCVnAZ9FWEH3hm" alt=""><figcaption></figcaption></figure>

* On the **"How will you use PayRam?"** screen, select the **Operator** option.
* Click **Continue**.
  {% endstep %}

{% step %}

### Set up fee collection wallet

<figure><img src="/files/bnNdRWPyCUdl0ZXGy0E9" alt=""><figcaption></figcaption></figure>

* Set up wallets for each chain you want to support. Supported chains include **EVM Family** (Ethereum, Polygon, Base), **Tron**, and **Bitcoin**.
* Enter the **Fee Collector Address** which is an external cold wallet address where your fee earnings will be deposited.
* Connect Master Account Wallet, this is required for deploying fees commission on the smart contract

> 💡 Note: The Fee Collector Address wallet receives all operator fee earnings. Make sure you have full control of this address before proceeding.
> {% endstep %}

{% step %}

### Configure custom fees

<figure><img src="/files/0e2JnTFZ82YpCbLiv4he" alt=""><figcaption></figcaption></figure>

* Set the fee markup you want to charge merchants.
* The markup can be set between **0% and 15%** per chain.
* Each chain supports an independent fee configuration.

> 💡 **Note**: Fee settings can be updated at any time from the dashboard.
> {% endstep %}

{% step %}

### Add merchant details

<figure><img src="/files/X4Q6GvOP0FOj14Ih23kS" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/cScFl7vF7XjxgfTv2s2t" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/YkxHxl74rJhB9aCgC0wj" alt=""><figcaption></figcaption></figure>

* Fill in the following details to onboard your first merchant:
  * **Merchant Name**
  * **User Access: A**ssign as Project Admin or Project Lead
  * **Merchant Login** credentials
* Click **Save and Finish** to complete the setup.

> 💡 **Note**: If you don't have a merchant to onboard yet, select **Skip to Dashboard** and complete this step later.
> {% endstep %}

{% step %}

### Share merchant account credentials

<figure><img src="/files/yptS9Aad5F5pOSZbtbE7" alt=""><figcaption></figcaption></figure>

* The merchant account and login credentials are generated. You can share them with the merchant and they can begin integrating PayRam to their platform.

> 💡 **Note**: If you don't have a merchant to onboard yet, select **Skip to Dashboard** and complete this step later.
> {% endstep %}
> {% endstepper %}

You have successfully completed the Operator Mode setup. Proceed to your dashboard to manage merchants, monitor fee earnings, and configure chain-level settings.

***

### Next steps for you or your merchants

* To configure nodes for merchant account, [visit here](https://docs.payram.com/onboarding-guide/node-details-configuration).
* To configure wallets for merchant account, [visit here](https://docs.payram.com/onboarding-guide/wallet-integration).
* To generate and test manual payment links, [visit here](https://docs.payram.com/onboarding-guide/testing-payment-links).
* To setup hot wallet for merchant account, [visit here](https://docs.payram.com/onboarding-guide/hot-wallet-setup).


# Script Usage

In this section, you will find the script commands to install and update PayRam — use the Mainnet command for production, Testnet for development, and Update to upgrade to the latest version.

## Commands

### **Mainnet installation**

* **Install PayRam on the mainnet (production environment):**

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

***

### **Testnet installation**

* **Install PayRam on the testnet (Development environment):**

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

***

### Update

* To update the PayRam container to the latest version, run the following command:

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

***

### Reset

* To completely reset the PayRam server configuration and perform a clean uninstallation, including the removal of all Docker images, run the following command:

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

***

### Restart

* To restart the PayRam server and refresh all active services without removing any data or configurations, run the following command.This will safely restart PayRam, helping to resolve issues such as unprocessed blocks or inactive services

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


# Introduction

Integrate PayRam’s APIs to seamlessly accept crypto payments and automate on-chain payouts from your own platform.

<figure><img src="/files/Vtn1KWJjPt5GQrrSvCx9" alt=""><figcaption></figcaption></figure>

## Integrating with PayRam API

* This section contains all available API integrations that help you interact with the PayRam ecosystem programmatically.
* You can use these APIs to connect your application, automate financial operations, and build custom flows on top of PayRam’s infrastructure.


# Payments API

***

<figure><img src="/files/zG1kwPtK5ZHFSeIpuILe" alt=""><figcaption></figcaption></figure>

## Prerequisites

Before using the User Payout APIs, make sure you have the following:

* A PayRam server that is properly hosted and running.
* A valid API Key generated from the PayRam dashboard for authentication.

{% hint style="info" %} <mark style="color:$warning;">**Note**</mark>**&#x20;**<mark style="color:$success;">**: You can generate a unique API key for each project directly from the PayRam dashboard. This helps you manage and track payouts separately for every project.**</mark>
{% endhint %}

***

## API Endpoints

These are the current endpoints required for the User Pay,ments API integration, listed below.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>Create Payment</strong></td><td>Create a payment link for customers using the PayRam API.</td><td><a href="/files/QyYn65RkzpewgdHqjX21">/files/QyYn65RkzpewgdHqjX21</a></td></tr><tr><td><strong>Fetch Tickers</strong></td><td>Fetch supported tickers and token options using the PayRam API.</td><td><a href="/files/3esEMRs7Sps8AIZfgd1A">/files/3esEMRs7Sps8AIZfgd1A</a></td></tr><tr><td><strong>Get Blockchain Currencies</strong></td><td>Fetch blockchain deposit options using a payment’s reference ID.</td><td><a href="/files/Mbez951dkHEpGkkf5gZY">/files/Mbez951dkHEpGkkf5gZY</a></td></tr><tr><td><strong>Assign Deposit Address</strong></td><td>Assign a static deposit address to a user for a specific blockchain.</td><td><a href="/files/lxjvwHH6Bmf8TsifQ2Le">/files/lxjvwHH6Bmf8TsifQ2Le</a></td></tr><tr><td><strong>Payment Status</strong></td><td>Fetch the current payment status using a payment’s reference ID.</td><td><a href="/files/nIgN9SFp2cuA8CncwM3g">/files/nIgN9SFp2cuA8CncwM3g</a></td></tr></tbody></table>


# Create Payment

In this section, you’ll learn how to create a payment link using the PayRam API for customers to make payments easily.

<figure><img src="/files/QyYn65RkzpewgdHqjX21" alt=""><figcaption></figcaption></figure>

***

## URL Details

<table><thead><tr><th width="157.99609375">Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>BASE_URL</td><td>Your PayRam server URL </td><td><a href="https://yourdomain.com:8443
">https://yourdomain.com:8443<br></a></td></tr><tr><td>API Endpoint</td><td>Endpoint to create a new payment link.</td><td>/api/v1/payment</td></tr></tbody></table>

{% hint style="info" %} <mark style="color:$warning;">**Note**</mark>**&#x20;**<mark style="color:$success;">**: You can generate a unique API key for each project directly from the PayRam dashboard. This helps you manage and track payouts separately for every project.**</mark>
{% endhint %}

## Headers

<table><thead><tr><th width="129.0859375">Header</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>API-Key</td><td>Your unique PayRam API key generated from your dashboard.</td><td>811b12035f0dfa8ffd62296df3c98b27</td></tr><tr><td>Content-Type</td><td>Format of the request data.</td><td>application/json</td></tr></tbody></table>

## &#x20;Request Body

<table><thead><tr><th width="169.67578125">Field</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>customerEmail</td><td>Customer’s email address where the payment link will be associated.</td><td>test@payram.com</td></tr><tr><td>customerID</td><td>Unique identifier for the customer.</td><td>1</td></tr><tr><td>amountInUSD</td><td>The payment amount in USD.</td><td>10</td></tr></tbody></table>

## curl request

Before running the command, replace the placeholders with your actual details:

* ${BASE\_URL} → Your PayRam server URL
* \<your\_api\_key> → Your PayRam API key
* Replace the request body fields with real customer data

```bash
curl --location '${BASE_URL}/api/v1/payment' \
--header 'API-Key: <your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "customerEmail": "<customer_email>",
  "customerID": "<customer_id>",
  "amountInUSD": <amount_in_usd>
}'
```

## curl response

```
{
  "host": "https://yourdomain.com:8443",
  "reference_id": "c80f5363-0397-4761-aa1a-3155c3a21470",
  "url": "https://yourdomain.com/payments?reference_id=c80f5363-0397-4761-aa1a-3155c3a21470&host=https://yourdomain.com:8443"
}
```

{% hint style="info" %} <mark style="color:$warning;">**Note**</mark>**&#x20;**<mark style="color:$success;">**: The url field provides a ready-to-use PayRam payment page. You can share this link directly with your customers, or build a custom UI using other API endpoints.**</mark>
{% endhint %}


# Fetch Tickers

In this section, you’ll learn how to fetch all supported tickers using the PayRam API, allowing you to display real-time token and blockchain options available for user payments.

<figure><img src="/files/3esEMRs7Sps8AIZfgd1A" alt=""><figcaption></figcaption></figure>

***

## URL Details

<table><thead><tr><th width="157.99609375">Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>BASE_URL</td><td>Your PayRam server URL </td><td><a href="https://yourdomain.com:8443
">https://yourdomain.com:8443<br></a></td></tr><tr><td>API Endpoint</td><td>Endpoint to create a new payment link.</td><td>/api/v1/ticker</td></tr></tbody></table>

{% hint style="info" %} <mark style="color:$warning;">**Note**</mark>**&#x20;**<mark style="color:$success;">**: You can generate a unique API key for each project directly from the PayRam dashboard. This helps you manage and track payouts separately for every project.**</mark>
{% endhint %}

## Headers

<table><thead><tr><th width="129.0859375">Header</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>API-Key</td><td>Your unique PayRam API key generated from your dashboard.</td><td>811b12035f0dfa8ffd62296df3c98b27</td></tr><tr><td>Content-Type</td><td>Format of the request data.</td><td>application/json</td></tr></tbody></table>

## curl request

Before running the command, replace the placeholders with your actual details:

* ${BASE\_URL} → Your PayRam server URL
* \<your\_api\_key> → Your PayRam API key
* Replace the request body fields with real customer data

```bash
curl --location '${BASE_URL}/api/v1/ticker' \
--data ''
```

## curl response

You’ll receive a list of supported blockchain assets, each containing:

* Blockchain info – e.g., ETH, BTC, TRX, BASE
* Token details – contract address, precision, and standard
* Live pricing – current USD value for each token

```
[
  {
    "blockchainCode": "TRX",
    "currencyCode": "TRX",
    "tokenAddress": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
    "standard": "TRX",
    "walletPrecision": 6,
    "family": "TRX_Family",
    "price": "0.2796"
  },
  ...
]
```

{% hint style="info" %} <mark style="color:$warning;">**Note :**</mark>  <mark style="color:$success;">**Each object represents a supported token on PayRam with its blockchain code, token standard, and real-time price.**</mark>
{% endhint %}


# Get Blockchain Currencies

In this section, you’ll learn how to fetch all available blockchain deposit options for a specific payment using its reference\_id.

<figure><img src="/files/Mbez951dkHEpGkkf5gZY" alt=""><figcaption></figcaption></figure>

***

## URL Details

<table><thead><tr><th width="157.99609375">Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>BASE_URL</td><td>Your PayRam server URL </td><td><a href="https://yourdomain.com:8443
">https://yourdomain.com:8443<br></a></td></tr><tr><td>API Endpoint</td><td>Endpoint to create a new payment link.</td><td>/api/v1/payment</td></tr></tbody></table>

## Headers

<table><thead><tr><th width="129.0859375">Header</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>API-Key</td><td>Your unique PayRam API key generated from your dashboard.</td><td>811b12035f0dfa8ffd62296df3c98b27</td></tr><tr><td>Content-Type</td><td>Format of the request data.</td><td>application/json</td></tr></tbody></table>

{% hint style="info" %} <mark style="color:$warning;">**Note**</mark>**&#x20;**<mark style="color:$success;">**: You can generate a unique API key for each project directly from the PayRam dashboard. This helps you manage and track payouts separately for every project.**</mark>
{% endhint %}

## curl request

Before running the command, replace the placeholders with your actual details:

* ${BASE\_URL} → Your PayRam server URL
* reference\_id → Use the value returned from the Create Payment API

```bash
curl --location '${BASE_URL}/api/v1/blockchain-currency/reference/{reference_id}' \
--data ''
```

## curl response

You’ll receive an array of blockchain currencies for that payment:

* Available networks & coins – e.g., ETH/USDC on Ethereum, BTC on Bitcoin, USDT on Tron, etc.
* Deposit info per option – including token contract address, precision, and family.
* Customer address state – customerAddress is empty for first-time users (no deposit address assigned yet).

```
[
  {
    "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
  },
  ...
]
```

#### Response breakdown

* blockchainCode – Blockchain symbol (e.g., ETH, BTC, TRX, BASE).
* network – Network name (e.g., Ethereum, Base, Polygon, Tron).
* currencyCode / currency – Token or coin name (e.g., USDC, ETH).
* customerAddress – Deposit address for the user (empty if not yet assigned).
* tokenAddress – Token’s contract or native address.
* standard – Token type (ERC20, TRC20, BTC, etc.).
* walletPrecision – Decimal precision supported.
* family – Blockchain family group (e.g., ETH\_Family).
* recommended / mostUsed – Suggested or frequently used options for display.

{% hint style="info" %} <mark style="color:$warning;">**NOTE**</mark>**&#x20;**<mark style="color:$success;">**:**</mark> <mark style="color:$success;">**If customerAddress is empty for a given family, you can call the**</mark>**&#x20;**<mark style="color:$warning;">**Assign Deposit Address API**</mark>**&#x20;**<mark style="color:$success;">**to assign a static deposit address for that user on that blockchain family.**</mark>
{% endhint %}


# Assign Deposit Address

In this section, you’ll learn how to assign a static deposit address to a user for a given blockchain family.

<figure><img src="/files/lxjvwHH6Bmf8TsifQ2Le" alt=""><figcaption></figcaption></figure>

***

## URL Details

<table><thead><tr><th width="157.99609375">Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>BASE_URL</td><td>Your PayRam server URL </td><td><a href="https://yourdomain.com:8443
">https://yourdomain.com:8443<br></a></td></tr><tr><td>API Endpoint</td><td>Endpoint to create a new payment link.</td><td>/api/v1/payment</td></tr></tbody></table>

## Headers

<table><thead><tr><th width="129.0859375">Header</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>API-Key</td><td>Your unique PayRam API key generated from your dashboard.</td><td>811b12035f0dfa8ffd62296df3c98b27</td></tr><tr><td>Content-Type</td><td>Format of the request data.</td><td>application/json</td></tr></tbody></table>

{% hint style="info" %} <mark style="color:$warning;">**Note**</mark>**&#x20;**<mark style="color:$success;">**: You can generate a unique API key for each project directly from the PayRam dashboard. This helps you manage and track payouts separately for every project.**</mark>
{% endhint %}

## &#x20;Request Body

<table><thead><tr><th width="169.67578125">Field</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>blockchain_code</td><td>Blockchain code to assign address for (BTC, ETH, TRX, BASE, POLYGON)</td><td>ETH</td></tr></tbody></table>

## curl request

Before running the command, replace the placeholders with your actual details:

* ${BASE\_URL} → Your PayRam server URL
* \<your\_api\_key> → Your PayRam API key
* reference\_id → Use the value returned from the Create Payment API

```bash
curl --location '${BASE_URL}/api/v1/deposit-address/reference/{reference_id}' \
--header 'Content-Type: application/json' \
--data '{
  "blockchain_code": "ETH"
}'
```

## curl response

* Address – The user’s assigned deposit address for this blockchain family. This address will be reused for all future payments in the same family.
* Family – The blockchain family (e.g., ETH\_Family, BTC\_Family, TRX\_Family). Each family can include multiple chains — for example, Base, Polygon, and Ethereum share the same ETH\_Family.
* Status – Indicates the current state of the assigned address (e.g., active, inactive).

```
{
  "id": 324,
  "createdAt": "2025-11-05T06:53:42.419556Z",
  "Address": "0xCb12499d865271D1FfFf16308E523e0BB624a779",
  "Family": "ETH_Family",
  "Status": "active",
  "MemberID": 271,
  "xpub_id": 18,
  "BlockchainFamilyID": 1,
  "Member": { ... },
  "BlockchainFamily": { ... },
  "wallet": { ... }
}
```

{% hint style="info" %} <mark style="color:$warning;">**Note**</mark>**&#x20;**<mark style="color:$success;">**: Once a deposit address is assigned, it becomes permanent for that user within the same blockchain family. PayRam automatically reuses this address for subsequent transactions.**</mark>
{% endhint %}


# Payment Status

In this section, you’ll learn how to fetch the current payment status for a specific transaction using its reference\_id.

<figure><img src="/files/nIgN9SFp2cuA8CncwM3g" alt=""><figcaption></figcaption></figure>

***

## URL Details

<table><thead><tr><th width="157.99609375">Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>BASE_URL</td><td>Your PayRam server URL </td><td><a href="https://yourdomain.com:8443
">https://yourdomain.com:8443<br></a></td></tr><tr><td>API Endpoint</td><td>Endpoint to create a new payment link.</td><td>/api/v1/ticker</td></tr></tbody></table>

## Headers

<table><thead><tr><th width="129.0859375">Header</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>API-Key</td><td>Your unique PayRam API key generated from your dashboard.</td><td>811b12035f0dfa8ffd62296df3c98b27</td></tr><tr><td>Content-Type</td><td>Format of the request data.</td><td>application/json</td></tr></tbody></table>

{% hint style="info" %} <mark style="color:$warning;">**Note**</mark>**&#x20;**<mark style="color:$success;">**: You can generate a unique API key for each project directly from the PayRam dashboard. This helps you manage and track payouts separately for every project.**</mark>
{% endhint %}

## curl request

Before running the command, replace the placeholders with your actual details:

* ${BASE\_URL} → Your PayRam server URL
* \<your\_api\_key> → Your PayRam API key

```bash
curl --location '<BASE_URL>/api/v1/payment/reference/<reference_id>' \
--header 'API-Key: <API_KEY>' \
--data ''
```

## curl response

You’ll receive a list of supported blockchain assets, each containing:

* Blockchain info – e.g., ETH, BTC, TRX, BASE
* Token details – contract address, precision, and standard
* Live pricing – current USD value for each token

```
{
  "invoiceID": "0dec6a8c-9cbc-4086-8680-10d45319a8d1",
  "customerID": "0",
  "amountInUSD": "1",
  "paymentState": "OPEN",
  "merchantName": "Payout",
  "referenceID": "0dec6a8c-9cbc-4086-8680-10d45319a8d1",
  "createdAt": "2025-11-07T11:37:59.012304Z",
  ...
}
```

{% hint style="info" %} <mark style="color:$warning;">**Note :**</mark>**&#x20;**<mark style="color:$success;">**Check the paymentState field in the response to track the payment status.**</mark>
{% endhint %}

| STATUS            | DESCRIPTION                                       |
| ----------------- | ------------------------------------------------- |
| OPEN              | The payment has not been processed yet.           |
| CANCELLED         | The payment link has expired.                     |
| FILLED            | The user has paid the full requested amount.      |
| PARTIALLY\_FILLED | The user has paid less than the requested amount. |
| OVER\_FILLED      | The user has paid more than the requested amount. |


# Webhook

When a payment (deposit) is detected and progresses on-chain, PayRam POSTs a webhook to your registered URL so you can track it without polling. Your server must accept the request, parse the body, and respond with a <mark style="color:$warning;">`2xx`</mark> status to acknowledge receipt.

> This is the payment / deposit webhook (incoming funds against a payment session). For outgoing payouts, see the Payout Webhooks section of the Payouts API doc.

### How to set up a Webhook?

You register webhook endpoints from the PayRam dashboard:

1. Open the PayRam dashboard.
2. Go to **Settings → Webhook**.
3. Click **Add Endpoint**.
4. Enter your **Endpoint URL** (a publicly reachable **HTTPS** URL) and a short description, then save.

Mark the endpoint **active**. PayRam delivers events to every active endpoint registered for the project.

> Webhooks are on by default. They can be disabled server-side with the <mark style="color:$warning;">`SEND_WEBHOOK_TO_MERCHANT=false`</mark> environment variable.

### Delivery and Retries

* Method: <mark style="color:$warning;">**`POST`**</mark>, <mark style="color:$warning;">`Content-Type: application/json`</mark>. (It is a POST with a JSON body — not a GET.)
* **Verify authenticity** of every delivery using either header:
  * <mark style="color:$warning;">**`X-Payram-Signature`**</mark> (recommended) — HMAC-SHA256 of the **raw request body**, keyed with your project API key, formatted <mark style="color:$warning;">`sha256=<hex>`</mark>. Recompute and constant-time compare.
  * <mark style="color:$warning;">**`API-KEY`**</mark> — your project API key sent verbatim (legacy; kept for backward compatibility).
* **Confirmation-progress** deliveries (while a deposit is still confirming) are retried up to 3 times per cycle (immediately, then after 2s and 4s) and re-sent on the next poll until the payment is filled.
* **Final** deliveries (payment <mark style="color:$warning;">`closed`</mark> / <mark style="color:$warning;">`cancelled`</mark>) are retried quickly (0s, 2s, 4s), then scheduled for **long-term retry** (30m, 1h, 2h, …) until your endpoint returns a <mark style="color:$warning;">`2xx`</mark>.
* Any response <mark style="color:$warning;">`≥ 400`</mark> (or a timeout — the client waits up to 60s) counts as a failure and triggers a retry.
* Treat events as **idempotent** — you may receive the same status more than once. Key off <mark style="color:$warning;">`reference_id`</mark> (or <mark style="color:$warning;">`invoice_id`</mark>) + <mark style="color:$warning;">`status`</mark>.

### Verifying the Signature

Compute the HMAC over the **exact raw bytes** of the request body (do not re-serialize the parsed JSON) and compare against the <mark style="color:$warning;">`X-Payram-Signature`</mark> header:

```javascript
const crypto = require('crypto');

function verifyPayramSignature(rawBody, signatureHeader, apiKey) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', apiKey).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}
```

### Payment Status

The status field reflects how much of the payment has been filled:

| <mark style="color:$warning;">`status`</mark>           | Meaning                                                                         |
| ------------------------------------------------------- | ------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`OPEN`</mark>             | Payment created; no deposit detected yet (or filled amount is zero).            |
| <mark style="color:$warning;">`PARTIALLY_FILLED`</mark> | A deposit was detected but the filled amount is less than the requested amount. |
| <mark style="color:$warning;">`FILLED`</mark>           | The filled amount equals the requested amount.                                  |
| <mark style="color:$warning;">`OVER_FILLED`</mark>      | The filled amount exceeds the requested amount.                                 |
| <mark style="color:$warning;">`CANCELLED`</mark>        | The payment was cancelled.                                                      |

### Confirmation Progress

While a deposit is confirming on-chain, PayRam sends progress webhooks carrying <mark style="color:$warning;">`confirmation_current`</mark> / <mark style="color:$warning;">`confirmation_required`</mark> (e.g. <mark style="color:$warning;">`3 / 12`</mark>, <mark style="color:$warning;">`5 / 12`</mark>) so you can show progress until the payment is filled. On the final closed/cancelled webhook these are <mark style="color:$warning;">`0`</mark>.

The typical flow:

```
OPEN  →  (deposit detected → confirming: 1/N, 2/N … N/N)  →  FILLED   (or PARTIALLY_FILLED / OVER_FILLED)
OPEN  →  CANCELLED
```

### Payload

All monetary amounts are JSON strings; <mark style="color:$warning;">`timestamp`</mark>, <mark style="color:$warning;">`confirmation_*`</mark>, and <mark style="color:$warning;">`block_number`</mark> are numbers. <mark style="color:$warning;">`filled_amount`</mark> / <mark style="color:$warning;">`filled_amount_in_usd`</mark> may be <mark style="color:$warning;">`null`</mark> before a deposit is detected, and `payment_info` is empty until there’s an on-chain deposit.

```json
{
  "customer_id": "1234",
  "invoice_id": "INV-0090",
  "reference_id": "a1b2c3d4e5",
  "status": "FILLED",
  "amount": "323.53",
  "currency": "USDT",
  "filled_amount": "323.53",
  "filled_amount_in_usd": "323.53",
  "sponsored_amount": "0",
  "sponsored_amount_in_usd": "0",
  "timestamp": 1750340282,
  "payment_info": [
    {
      "source_address": "0x7a2C…9bF1",
      "transaction_hash": "0xabc123…def456",
      "destination_address": "0x21d4cF2E…EA8d45",
      "block_number": 21897412
    }
  ],
  "confirmation_current": 12,
  "confirmation_required": 12
}
```

| Field                                                                     | Type           | Meaning                                                                                                                                                   |
| ------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`customer_id`</mark>                        | string         | Your identifier for the paying customer.                                                                                                                  |
| <mark style="color:$warning;">`invoice_id`</mark>                         | string         | The invoice this payment belongs to.                                                                                                                      |
| <mark style="color:$warning;">`reference_id`</mark>                       | string         | PayRam’s unique reference for the payment (use as the idempotency key).                                                                                   |
| <mark style="color:$warning;">`status`</mark>                             | string         | Fill state — see the table above.                                                                                                                         |
| <mark style="color:$warning;">`amount`</mark>                             | string         | Requested payment amount in <mark style="color:$warning;">`currency`</mark>.                                                                              |
| <mark style="color:$warning;">`currency`</mark>                           | string         | Currency code (e.g. <mark style="color:$warning;">`BTC`</mark>, <mark style="color:$warning;">`USDT`</mark>, <mark style="color:$warning;">`ETH`</mark>). |
| <mark style="color:$warning;">`filled_amount`</mark>                      | string \| null | Amount received so far (null before any deposit).                                                                                                         |
| <mark style="color:$warning;">`filled_amount_in_usd`</mark>               | string \| null | USD value of the filled amount.                                                                                                                           |
| <mark style="color:$warning;">`sponsored_amount`</mark>                   | string         | Gas/fee amount sponsored by PayRam (<mark style="color:$warning;">`"0"`</mark> if none).                                                                  |
| <mark style="color:$warning;">`sponsored_amount_in_usd`</mark>            | string         | USD value of the sponsored amount.                                                                                                                        |
| <mark style="color:$warning;">`timestamp`</mark>                          | number         | Last-update time, Unix epoch **seconds**.                                                                                                                 |
| <mark style="color:$warning;">`payment_info`</mark>                       | array          | On-chain deposit details (empty until a deposit is detected).                                                                                             |
| <mark style="color:$warning;">`payment_info[].source_address`</mark>      | string         | Address the funds came from.                                                                                                                              |
| <mark style="color:$warning;">`payment_info[].transaction_hash`</mark>    | string         | On-chain transaction hash of the deposit.                                                                                                                 |
| <mark style="color:$warning;">`payment_info[].destination_address`</mark> | string         | PayRam deposit address that received the funds.                                                                                                           |
| <mark style="color:$warning;">`payment_info[].block_number`</mark>        | number         | Block the deposit was included in.                                                                                                                        |
| <mark style="color:$warning;">`confirmation_current`</mark>               | number         | Confirmations seen so far (<mark style="color:$warning;">`0`</mark> on the final webhook).                                                                |
| <mark style="color:$warning;">`confirmation_required`</mark>              | number         | Confirmations required before the payment is considered settled.                                                                                          |

### Acknowledging

Return <mark style="color:$warning;">`2xx`</mark> to acknowledge. If your endpoint is unreachable, errors, or times out, PayRam retries (quick retries, then long-term backoff for final events). Respond quickly and process asynchronously.


# Payouts APIs

## Prerequisites

Before using the User Payout APIs, make sure you have the following:

* A PayRam server that is properly hosted and running.
* A valid API Key generated from the PayRam dashboard for authentication.

{% hint style="info" %} <mark style="color:$warning;">**Note**</mark>**&#x20;**<mark style="color:$success;">**: You can generate a unique API key for each project directly from the PayRam dashboard. This helps you manage and track payouts separately for every project.**</mark>
{% endhint %}

***

## API Endpoints

These are the current endpoints required for the User Payout API integration, listed below.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Create Payouts</td><td>Create a payout to send funds to a recipient’s wallet on the chosen blockchain.</td><td><a href="/files/MQq54uAjmsMwG3Ym96fc">/files/MQq54uAjmsMwG3Ym96fc</a></td><td><a href="https://docs.payram.com/api-integration/payouts-apis/create-payouts">https://docs.payram.com/api-integration/payouts-apis/create-payouts</a></td></tr><tr><td>GET Single Payout</td><td>Retrieve a single payout record with their details and statuses from your PayRam server.</td><td><a href="/files/PSCXKJuTU68vlkRnnQud">/files/PSCXKJuTU68vlkRnnQud</a></td><td><a href="https://docs.payram.com/api-integration/payouts-apis/payouts-status/get-single-payout">https://docs.payram.com/api-integration/payouts-apis/payouts-status/get-single-payout</a></td></tr><tr><td>GET All Payouts</td><td>Retrieve all payout records with their details and statuses from your PayRam server.</td><td><a href="/files/BZHmM6IlHqlBUYGHxviw">/files/BZHmM6IlHqlBUYGHxviw</a></td><td><a href="https://docs.payram.com/api-integration/payouts-apis/payouts-status/get-all-payouts">https://docs.payram.com/api-integration/payouts-apis/payouts-status/get-all-payouts</a></td></tr></tbody></table>


# Overview

<figure><img src="/files/TLBSspe7aZwzb0fmyC8b" alt=""><figcaption></figcaption></figure>

Send funds from your project to a recipient’s wallet, and track each payout to completion. This reference covers creating payouts, checking status, approving/rejecting payouts that are held for review, listing them, and receiving status updates via webhooks.

***

### Base URL

Use your PayRam server’s HTTPS domain:

```
<https://yourdomain.com>
```

### Authentication

Every request authenticates with a **project API key** sent in the `API-Key` header. Generate one per project from the dashboard (**Project → API Keys**). All reads and creates are automatically **scoped to that key’s project** — you only ever see or act on your own project’s payouts.

| Header                                              | Required | Value                                                                                              |
| --------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`API-Key`</mark>      | Yes      | Your project API key, e.g. <mark style="color:$warning;">`be703fa47ebe07121102ee260fb3d5c0`</mark> |
| <mark style="color:$warning;">`Content-Type`</mark> | Yes      | <mark style="color:$warning;">`application/json`</mark>                                            |

> **Approve / Reject** are done from the dashboard.

### Version requirement

The merchant payout endpoints (<mark style="color:$warning;">`/withdrawal/merchant`</mark>, <mark style="color:$warning;">`/withdrawal/{id}/merchant`</mark>) require **PayRam v3.1.1 or later**. On older versions they return `404`.

### Endpoints at a glance

| Method                                      | Path                                                                    | Purpose                                       |
| ------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------- |
| <mark style="color:$warning;">`POST`</mark> | <mark style="color:$warning;">`/api/v1/withdrawal/merchant`</mark>      | Create a payout                               |
| <mark style="color:$warning;">`GET`</mark>  | <mark style="color:$warning;">`/api/v1/withdrawal/{id}/merchant`</mark> | Get one payout / check its status             |
| <mark style="color:$warning;">`GET`</mark>  | <mark style="color:$warning;">`/api/v1/ticker`</mark>                   | Live USD prices (for USD → crypto conversion) |
| <mark style="color:$warning;">`GET`</mark>  | <mark style="color:$warning;">`/api/v1/withdrawal/merchant`</mark>      | List your project’s payouts                   |

### Amounts are in crypto

The payout <mark style="color:$warning;">`amount`</mark> is the **crypto amount** in the currency’s own units (e.g. <mark style="color:$warning;">`"100"`</mark> USDC = 100 USDC; <mark style="color:$warning;">`"0.05"`</mark> ETH = 0.05 ETH) — **not USD**. If your system works in fiat, convert USD → crypto first using the ticker (see **Convert USD → Crypto**).

### Supported networks & currencies

* **Networks:** <mark style="color:$warning;">`ETH`</mark>, <mark style="color:$warning;">`BASE`</mark>, <mark style="color:$warning;">`POLYGON`</mark> (EVM), and <mark style="color:$warning;">`TRX`</mark>.
* **Currencies:** tokens (e.g. <mark style="color:$warning;">`USDC`</mark>, <mark style="color:$warning;">`USDT`</mark>) and native coins (<mark style="color:$warning;">`ETH`</mark>, <mark style="color:$warning;">`POL`</mark>, <mark style="color:$warning;">`TRX`</mark>), as enabled for your project on each chain.
* **BTC is not supported for payouts.**

### Status lifecycle

Every payout reports a <mark style="color:$warning;">`status`</mark>:

| Status                                                          | Meaning                                                                                                                                                             |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`pending-otp-verification`</mark> | Waiting for OTP verification before processing.                                                                                                                     |
| <mark style="color:$warning;">`pending-approval`</mark>         | Held for manual approval — exceeded the auto-approve amount or an hourly/daily limit (<mark style="color:$warning;">`attributes.approvalReason`</mark> says which). |
| <mark style="color:$warning;">`pending`</mark>                  | Approved (or auto-approved) and queued for on-chain processing.                                                                                                     |
| <mark style="color:$warning;">`initiated`</mark>                | Broadcast to the blockchain (<mark style="color:$warning;">`txHash`</mark> set); awaiting confirmation.                                                             |
| <mark style="color:$warning;">`sent`</mark>                     | Transaction confirmed on-chain.                                                                                                                                     |
| <mark style="color:$warning;">`processed`</mark>                | Confirmed and recorded in accounting — fully complete.                                                                                                              |
| <mark style="color:$warning;">`failed`</mark>                   | Processing failed — see <mark style="color:$warning;">`failureReason`</mark>.                                                                                       |
| <mark style="color:$warning;">`rejected`</mark>                 | Declined by an admin (or the system).                                                                                                                               |
| <mark style="color:$warning;">`cancelled`</mark>                | Intentionally stopped before being sent/processed.                                                                                                                  |

**Terminal states:** <mark style="color:$warning;">`processed`</mark>, <mark style="color:$warning;">`failed`</mark>, <mark style="color:$warning;">`rejected`</mark>, <mark style="color:$warning;">`cancelled`</mark>.

### Tracking payouts

Two ways to track a payout to completion:

* **Webhooks (recommended)** — PayRam POSTs a <mark style="color:$warning;">`payout.<status>`</mark> event to your registered webhook URL on every status change. See **Payout Webhooks** at the end of this doc.
* **Polling** — <mark style="color:$warning;">`GET /api/v1/withdrawal/{id}/merchant`</mark> (or the list endpoint) until the payout reaches a terminal state.


# Create Payouts

In this section, you’ll learn how to create a payout in PayRam to send funds directly to a recipient’s wallet on the selected blockchain.

<figure><img src="/files/MQq54uAjmsMwG3Ym96fc" alt=""><figcaption></figcaption></figure>

Create a payout to send funds directly to a recipient’s wallet on the selected blockchain. PayRam validates the request, applies your project’s payout limits, and either queues the payout for sending or holds it for manual approval.

***

### Authentication

This endpoint is **project-API-key only**. Use the API key generated for the project you’re paying out from (Project → API Keys). The payout is created under that key’s project.

### Endpoint

| Item                                            | Value                                                 |
| ----------------------------------------------- | ----------------------------------------------------- |
| <mark style="color:$warning;">`BASE_URL`</mark> | Your PayRam server URL, e.g. `https://yourdomain.com` |
| Method                                          | <mark style="color:$warning;">`POST`</mark>           |

> BASE\_URL: use your plain HTTPS domain (<mark style="color:$warning;">`https://yourdomain.com`</mark>).

### Headers

| Header                                              | Required | Example                                                                               |
| --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`API-Key`</mark>      | Yes      | <mark style="color:$warning;">`be703fa47ebe07121102ee260fb3d5c0`</mark> (project key) |
| <mark style="color:$warning;">`Content-Type`</mark> | Yes      | <mark style="color:$warning;">`application/json`</mark>                               |

### Request Body

| Field                                                     | Type             | Required   | Description                                                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`email`</mark>              | string           | ✅ Yes      | Recipient’s email address (must be a valid email).                                                                                                                                                                                                                                                                    |
| <mark style="color:$warning;">`blockchainCode`</mark>     | string           | ✅ Yes      | Blockchain network. One of <mark style="color:$warning;">`ETH`</mark>, <mark style="color:$warning;">`BASE`</mark>, <mark style="color:$warning;">`POLYGON`</mark>, <mark style="color:$warning;">`TRX`</mark>.                                                                                                       |
| <mark style="color:$warning;">`currencyCode`</mark>       | string           | ✅ Yes      | Token or native coin to send, e.g. <mark style="color:$warning;">`USDC`</mark>, <mark style="color:$warning;">`USDT`</mark>, <mark style="color:$warning;">`ETH`</mark>, <mark style="color:$warning;">`POL`</mark>, <mark style="color:$warning;">`TRX`</mark>. Must be enabled for the project on the chosen chain. |
| <mark style="color:$warning;">`amount`</mark>             | string (decimal) | ✅ Yes      | **Crypto amount** to send, in the currency’s own units — **not USD**. E.g. <mark style="color:$warning;">`"100"`</mark> = 100 USDC. See “Amounts are in crypto” below.                                                                                                                                                |
| <mark style="color:$warning;">`toAddress`</mark>          | string           | ✅ Yes      | Recipient wallet address; must be valid for <mark style="color:$warning;">`blockchainCode`</mark>.                                                                                                                                                                                                                    |
| <mark style="color:$warning;">`customerID`</mark>         | string           | ✅ Yes\*    | Your unique identifier for the recipient in your system. \*Technically optional in the schema, but a payout **cannot be created without it** — omitting it returns an error. Always send it.                                                                                                                          |
| <mark style="color:$warning;">`mobileNumber`</mark>       | string           | ❌ Optional | Recipient’s mobile number.                                                                                                                                                                                                                                                                                            |
| <mark style="color:$warning;">`residentialAddress`</mark> | string           | ❌ Optional | Recipient’s address.                                                                                                                                                                                                                                                                                                  |

### Amounts are in Crypto (not USD)

<mark style="color:$warning;">`amount`</mark> is the exact on-chain amount in the currency’s units (e.g. <mark style="color:$warning;">`"100"`</mark> USDC sends 100 USDC; <mark style="color:$warning;">`"0.05"`</mark> ETH sends 0.05 ETH). PayRam computes the USD value internally for limit checks.

If your system works in fiat, convert USD → crypto **before** creating the payout using the public ticker endpoint, then send the resulting crypto amount:

1. <mark style="color:$warning;">`GET {BASE_URL}/api/v1/ticker`</mark> returns each currency’s live USD <mark style="color:$warning;">`price`</mark> and <mark style="color:$warning;">`walletPrecision`</mark>.
2. <mark style="color:$warning;">`cryptoAmount = usdAmount / price`</mark>, rounded to that currency’s <mark style="color:$warning;">`walletPrecision`</mark>. (Stablecoins have <mark style="color:$warning;">`price = "1.0"`</mark>, so the crypto amount equals the USD amount.)
3. Create the payout with that <mark style="color:$warning;">`amount`</mark>.

> **Native coins are supported.** You can pay out native <mark style="color:$warning;">`ETH`</mark>, <mark style="color:$warning;">`POL`</mark>, and <mark style="color:$warning;">`TRX`</mark> (not only tokens). **BTC is not supported for payouts.**

### Payout Limits and Approval

At creation, PayRam evaluates the payout (in USD) against your project’s limits, **per recipient member within the project**:

* **Auto-approve amount** — payouts at or under this are auto-approved and queued for sending (<mark style="color:$warning;">`status: "pending"`</mark>). Payouts above it require manual approval (<mark style="color:$warning;">`status: "pending-approval"`</mark>).
* **Hourly limit** / **Daily limit** — if the member’s cumulative payouts in this project for the current hour/day would exceed these, the payout is held for approval.
* **Minimum payout** — payouts below this are rejected outright.

When a payout is held, the response <mark style="color:$warning;">`status`</mark> is <mark style="color:$warning;">`pending-approval`</mark> and <mark style="color:$warning;">`attributes.approvalReason`</mark> explains why (<mark style="color:$warning;">`above_auto_approve`</mark>, <mark style="color:$warning;">`daily_limit_exceeded`</mark>, <mark style="color:$warning;">`hourly_limit_exceeded`</mark>, etc.). An admin then approves/rejects it from the dashboard.

> These thresholds are configured per installation and can be overridden per project in the dashboard (**Project → Payout Limits**; the global minimum lives under **Settings → Withdrawal Limits**). Contact PayRam support to change global defaults. Don’t hard-code specific limit values in your integration — read them from your dashboard.

### Example Request

```bash
curl --location '${BASE_URL}/api/v1/withdrawal/merchant' \
--header 'API-Key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "test@test.com",
  "blockchainCode": "ETH",
  "currencyCode": "USDC",
  "amount": "100",
  "toAddress": "0x291b68732f14F47Fd21bE81ec5Cf1bcfC0DB14Ea",
  "customerID": "414817384",
  "mobileNumber": "123456789",
  "residentialAddress": "No 22 OC Street"
}'
```

### Example Response

<mark style="color:$warning;">`201 Created`</mark> — the created payout object:

```json
{
  "id": 120,
  "createdAt": "2026-06-19T13:14:41.806Z",
  "blockchainCode": "ETH",
  "currencyCode": "USDC",
  "currencyType": "token",
  "amount": "100",
  "priceInUSD": "1",
  "amountInUSD": "100.000000",
  "toAddress": "0x9F8E7D6C5B4A39281706F5E4D3C2B1A098765432",
  "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "recipientEmail": "test@test.com",
  "txHash": null,
  "status": "pending-approval",
  "type": "payout_merchant",
  "attributes": "{\"approvalReason\":\"above_auto_approve\"}",
  "externalPlatformID": 1,
  "createdBy": "user"
}
```

<mark style="color:$warning;">`status`</mark> will be:

* <mark style="color:$warning;">**`pending`**</mark> — auto-approved (within limits); queued for sending.
* <mark style="color:$warning;">**`pending-approval`**</mark> — held for manual admin approval (see <mark style="color:$warning;">`attributes.approvalReason`</mark>).

> **The&#x20;**<mark style="color:$warning;">**`id`**</mark>**&#x20;field is important** — it uniquely identifies the payout. Store it; you’ll use it to track status via <mark style="color:$warning;">`GET /api/v1/withdrawal/{id}/merchant`</mark> (or find it in the list endpoint).

### Tracking Status

Track status either way:

* **Webhooks (recommended)** — get a <mark style="color:$warning;">`payout.<status>`</mark> event pushed to you on every change (see **Payout Webhooks**).
* **Polling** — <mark style="color:$warning;">`GET /api/v1/withdrawal/{id}/merchant`</mark> (single) or <mark style="color:$warning;">`GET /api/v1/withdrawal/merchant`</mark> (list).

The payout moves through: <mark style="color:$warning;">`pending-approval → pending → initiated → sent → processed`</mark> (<mark style="color:$warning;">`failed`</mark> / <mark style="color:$warning;">`rejected`</mark> are terminal). See the **Status lifecycle** in the Overview.

### Errors

| HTTP | When                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | Missing/invalid required field (<mark style="color:$warning;">`email`</mark> not a valid email, missing <mark style="color:$warning;">`blockchainCode`</mark> / <mark style="color:$warning;">`currencyCode`</mark> / <mark style="color:$warning;">`amount`</mark> / <mark style="color:$warning;">`toAddress`</mark>, invalid wallet address for the chain, or invalid blockchain/currency combination). |
| 400  | <mark style="color:$warning;">`PAYOUT_AMOUNT_BELOW_MINIMUM`</mark> (amount below the project minimum), or <mark style="color:$warning;">`PAYOUT_CURRENCY_DISABLED`</mark> (currency not enabled for payouts).                                                                                                                                                                                              |
| 401  | Missing/invalid <mark style="color:$warning;">`API-Key`</mark>, or a non-project key.                                                                                                                                                                                                                                                                                                                      |
| 500  | <mark style="color:$warning;">`customerID`</mark> omitted (“failed to create customer”), <mark style="color:$warning;">`BTC`</mark> selected (not supported for payouts), or an unexpected server error.                                                                                                                                                                                                   |
| 503  | <mark style="color:$warning;">`EXCHANGE_RATE_UNAVAILABLE`</mark> — a live exchange rate couldn’t be fetched for a non-stablecoin (retryable; try again shortly).                                                                                                                                                                                                                                           |

### Convert USD → Crypto (Ticker)

The Create Payout API takes a **crypto** `amount`, but many systems work in **fiat (USD)**. Use the ticker endpoint to fetch live USD prices, convert your USD amount to the crypto amount, then create the payout. This keeps your conversion aligned with the same pricing PayRam uses internally for its limit checks.

### Endpoint

```
GET {BASE_URL}/api/v1/ticker
```

**Public** — no <mark style="color:$warning;">`API-Key`</mark> required. Returns every currency configured on your server with its current USD price.

### Example Request

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

### Example Response

<mark style="color:$warning;">`200 OK`</mark> — an array, one entry per blockchain + currency:

```json
[
  {
    "blockchainCode": "ETH",
    "currencyCode": "ETH",
    "tokenAddress": "0x0000000000000000000000000000000000000000",
    "standard": "native",
    "walletPrecision": 18,
    "family": "ETH_Family",
    "price": "1659.57"
  },
  {
    "blockchainCode": "BASE",
    "currencyCode": "USDC",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "standard": "ERC20",
    "walletPrecision": 6,
    "family": "ETH_Family",
    "price": "1.0"
  }
]
```

| Field                                                                                                       | Meaning                                                                                                                                         |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`blockchainCode`</mark> / <mark style="color:$warning;">`currencyCode`</mark> | The chain + currency this price applies to.                                                                                                     |
| <mark style="color:$warning;">`price`</mark>                                                                | Current price of **1 unit of the currency in USD** (stablecoins are <mark style="color:$warning;">`"1.0"`</mark>).                              |
| <mark style="color:$warning;">`walletPrecision`</mark>                                                      | Decimal places to round the converted crypto amount to.                                                                                         |
| <mark style="color:$warning;">`tokenAddress`</mark>                                                         | Token contract (<mark style="color:$warning;">`0x000…000`</mark> for native coins).                                                             |
| <mark style="color:$warning;">`standard`</mark>                                                             | <mark style="color:$warning;">`native`</mark>, <mark style="color:$warning;">`ERC20`</mark>, <mark style="color:$warning;">`TRC20`</mark>, etc. |

### How to Convert

For the currency you’re paying out, find the matching row (by `blockchainCode` + `currencyCode`), then:

```
cryptoAmount = usdAmount / price          # rounded to walletPrecision
```

* **Stablecoins** (<mark style="color:$warning;">`price = "1.0"`</mark>) → <mark style="color:$warning;">`cryptoAmount = usdAmount`</mark>.
* **Other currencies** → divide by <mark style="color:$warning;">`price`</mark> and round to <mark style="color:$warning;">`walletPrecision`</mark>.

**Example:** pay out **$50 in ETH** when <mark style="color:$warning;">`price = "1659.57"`</mark>:\ <mark style="color:$warning;">`50 / 1659.57 = 0.030128…`</mark> → rounded to 18 dp → <mark style="color:$warning;">`amount: "0.030128..."`</mark>.

#### Recommended flow

1. Your back office validates the **USD** amount (your own rules).
2. <mark style="color:$warning;">`GET /api/v1/ticker`</mark> → look up the target currency’s <mark style="color:$warning;">`price`</mark> and <mark style="color:$warning;">`walletPrecision`</mark>.
3. Convert USD → crypto and round to <mark style="color:$warning;">`walletPrecision`</mark>.
4. <mark style="color:$warning;">`POST /api/v1/withdrawal/merchant`</mark> with the resulting crypto <mark style="color:$warning;">`amount`</mark>.

> Fetch the ticker **right before** creating the payout so the rate is current. Rounding to <mark style="color:$warning;">`walletPrecision`</mark> avoids “fractional base unit” rejections on create.


# GET Single Payout

In this section, you’ll learn how to retrieve a singl payout records from your PayRam server, including their details and current statuses.

<figure><img src="/files/PSCXKJuTU68vlkRnnQud" alt=""><figcaption></figcaption></figure>

Check the current status of a payout by its id (the id returned by Create Payout). This is the endpoint to poll after creating a payout.

***

### Authentication

**Project-API-key only**. Results are scoped to the API key’s own project: a payout id that belongs to a different project returns **404** (not another project’s data). Type-restricted to merchant payouts (<mark style="color:$warning;">`payout_merchant`</mark>).

> **Requires PayRam v3.1.1 or later.** On earlier versions this endpoint returns 404.

### Endpoint

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

| Path parameter                            | Description                              | Example                                    |
| ----------------------------------------- | ---------------------------------------- | ------------------------------------------ |
| <mark style="color:$warning;">`id`</mark> | The payout id returned by Create Payout. | <mark style="color:$warning;">`120`</mark> |

### Headers

| Header                                              | Required | Example                                                                               |
| --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`API-Key`</mark>      | Yes      | <mark style="color:$warning;">`be703fa47ebe07121102ee260fb3d5c0`</mark> (project key) |
| <mark style="color:$warning;">`Content-Type`</mark> | Yes      | <mark style="color:$warning;">`application/json`</mark>                               |

### Example Request

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

### Example Response

<mark style="color:$warning;">`200 OK`</mark> — a single payout object (same shape as the items in *Get All Payouts*):

```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"
}
```

See **Key Response Fields** in *Get All Payouts* for the meaning of every field.

### Payout statuses

Check the <mark style="color:$warning;">`status`</mark> field to know where the payout is in its lifecycle:

| Status                                                          | Meaning                                                                                                                                                                         |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`pending-otp-verification`</mark> | Waiting for OTP verification before processing.                                                                                                                                 |
| <mark style="color:$warning;">`pending-approval`</mark>         | Held for manual approval — the payout exceeded the auto-approve amount or an hourly/daily limit. <mark style="color:$warning;">`attributes.approvalReason`</mark> explains why. |
| <mark style="color:$warning;">`pending`</mark>                  | Approved (or auto-approved) and queued for on-chain processing.                                                                                                                 |
| <mark style="color:$warning;">`initiated`</mark>                | Broadcast to the blockchain (<mark style="color:$warning;">`txHash`</mark> is set); awaiting confirmation.                                                                      |
| <mark style="color:$warning;">`sent`</mark>                     | Transaction confirmed on-chain.                                                                                                                                                 |
| <mark style="color:$warning;">`processed`</mark>                | Confirmed and recorded in PayRam’s accounting — fully complete.                                                                                                                 |
| <mark style="color:$warning;">`failed`</mark>                   | Processing failed — see <mark style="color:$warning;">`failureReason`</mark> for the specific cause.                                                                            |
| <mark style="color:$warning;">`rejected`</mark>                 | Declined by an admin (or the system).                                                                                                                                           |
| <mark style="color:$warning;">`cancelled`</mark>                | Intentionally stopped before being sent/processed.                                                                                                                              |

**Terminal states:** <mark style="color:$warning;">`processed`</mark>, <mark style="color:$warning;">`failed`</mark>, <mark style="color:$warning;">`rejected`</mark>, <mark style="color:$warning;">`cancelled`</mark> — stop polling once a payout reaches one of these.

### Polling guidance

If you aren’t using **Payout Webhooks** (recommended — see the last section), poll this endpoint until the payout reaches a terminal state. A sensible cadence is every few seconds right after creation, backing off to longer intervals; a payout typically reaches <mark style="color:$warning;">`sent/processed`</mark> within a few minutes once it’s on-chain. For a <mark style="color:$warning;">`pending-approval`</mark> payout, poll until an admin approves it (then it continues to <mark style="color:$warning;">`sent/processed`</mark>) or rejects it.

| HTTP                                       | When                                                                                                                                                                    |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`401`</mark> | Missing/invalid <mark style="color:$warning;">`API-Key`</mark>, or a non-project key.                                                                                   |
| <mark style="color:$warning;">`404`</mark> | No payout with that id in your project (or the endpoint isn’t present on PayRam < v3.1.1). Response: <mark style="color:$warning;">`{ "message": "not found" }`</mark>. |


# GET All Payouts

<figure><img src="/files/QwWj578lu4ZFZXtXKuJq" alt=""><figcaption></figcaption></figure>

Retrieve payout (merchant withdrawal) records for your project — with filtering, sorting, and pagination.

### Authentication

This endpoint is **project-API-key only**. Generate a key per project from the PayRam dashboard (Project → API Keys). Results are automatically scoped to that key’s project — you only ever see your own project’s payouts.

> **Requires PayRam v3.1.1 or later.** On earlier versions this endpoint returns 404.

### Endpoint

```
GET {BASE_URL}/api/v1/withdrawal/merchant
```

| Item                                            | Value                                                                                      |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
| <mark style="color:$warning;">`BASE_URL`</mark> | Your PayRam server URL, e.g. <mark style="color:$warning;">`https://yourdomain.com`</mark> |
| Method                                          | <mark style="color:$warning;">`GET`</mark>                                                 |

BASE\_URL: use your plain HTTPS domain (<mark style="color:$warning;">`https://yourdomain.com`</mark>).

### Headers

| Header                                              | Required | Example                                                                               |
| --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`API-Key`</mark>      | Yes      | <mark style="color:$warning;">`be703fa47ebe07121102ee260fb3d5c0`</mark> (project key) |
| <mark style="color:$warning;">`Content-Type`</mark> | Yes      | <mark style="color:$warning;">`application/json`</mark>                               |

> You can generate a unique API key for each project from the PayRam dashboard, so you can manage and track payouts separately per project.

### Query Parameters

All optional. Parameters marked <mark style="color:$warning;">`[]`</mark> may be repeated (e.g. <mark style="color:$warning;">`?status=sent&status=processed`</mark>).

### Pagination and Sorting

| Parameter                                                                                                  | Description                                                                                                                                                                                                                                                                                            | Example                                                     |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| <mark style="color:$warning;">`limit`</mark>                                                               | Records per page. **Defaults to 100 and is capped at 100** (larger values are clamped).                                                                                                                                                                                                                | <mark style="color:$warning;">`20`</mark>                   |
| <mark style="color:$warning;">`offset`</mark>                                                              | Starting offset for paging.                                                                                                                                                                                                                                                                            | <mark style="color:$warning;">`40`</mark>                   |
| <mark style="color:$warning;">`order`</mark>                                                               | <mark style="color:$warning;">`ASC`</mark> or <mark style="color:$warning;">`DESC`</mark>. Default <mark style="color:$warning;">`DESC`</mark>.                                                                                                                                                        | <mark style="color:$warning;">`DESC`</mark>                 |
| <mark style="color:$warning;">`sortBy`</mark>                                                              | Column to sort by — **use the snake\_case DB column** (<mark style="color:$warning;">`created_at`</mark>, <mark style="color:$warning;">`amount`</mark>, <mark style="color:$warning;">`id`</mark>, <mark style="color:$warning;">`status`</mark>). Default <mark style="color:$warning;">`id`</mark>. | <mark style="color:$warning;">`created_at`</mark>           |
| <mark style="color:$warning;">`greaterThanID`</mark> / <mark style="color:$warning;">`lessThanID`</mark>   | Keyset pagination by id (alternative to <mark style="color:$warning;">`offset`</mark>).                                                                                                                                                                                                                | <mark style="color:$warning;">`200`</mark>                  |
| <mark style="color:$warning;">`createdAfter`</mark> / <mark style="color:$warning;">`createdBefore`</mark> | Creation-time range (RFC3339).                                                                                                                                                                                                                                                                         | <mark style="color:$warning;">`2026-06-01T00:00:00Z`</mark> |
| <mark style="color:$warning;">`updatedAfter`</mark> / <mark style="color:$warning;">`updatedBefore`</mark> | Last-update range (RFC3339).                                                                                                                                                                                                                                                                           |                                                             |
| <mark style="color:$warning;">`startDate`</mark> / <mark style="color:$warning;">`endDate`</mark>          | Creation-date range (RFC3339).                                                                                                                                                                                                                                                                         |                                                             |

> ⚠️ <mark style="color:$warning;">`sortBy`</mark> must be a real snake\_case column (<mark style="color:$warning;">`created_at`</mark>, **not** <mark style="color:$warning;">`createdAt`</mark>) — a camelCase value returns **500**.
>
> ⚠️ There is **no “return everything”**: omitting <mark style="color:$warning;">`limit`</mark> returns at most 100. Page with <mark style="color:$warning;">`offset`</mark> (or <mark style="color:$warning;">`greaterThanID`</mark>) until a page returns fewer than <mark style="color:$warning;">`limit`</mark> rows.

### Filters

| Parameter                                                                                        | Description                                                                                          | Example                                                              |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| <mark style="color:$warning;">`status`</mark> <mark style="color:$warning;">`[]`</mark>          | Payout status (see lifecycle in the Overview).                                                       | <mark style="color:$warning;">`status=sent`</mark>                   |
| <mark style="color:$warning;">`types`</mark> <mark style="color:$warning;">`[]`</mark>           | Payout type — for merchant payouts use <mark style="color:$warning;">`payout_merchant`</mark>.       | <mark style="color:$warning;">`types=payout_merchant`</mark>         |
| <mark style="color:$warning;">`blockchainCode`</mark> <mark style="color:$warning;">`[]`</mark>  | Chain code.                                                                                          | <mark style="color:$warning;">`blockchainCode=ETH`</mark>            |
| <mark style="color:$warning;">`toAddress`</mark> <mark style="color:$warning;">`[]`</mark>       | Recipient address(es).                                                                               |                                                                      |
| <mark style="color:$warning;">`fromAddress`</mark> <mark style="color:$warning;">`[]`</mark>     | Sending hot-wallet address(es).                                                                      |                                                                      |
| <mark style="color:$warning;">`recipientEmails`</mark> <mark style="color:$warning;">`[]`</mark> | Recipient email(s).                                                                                  | <mark style="color:$warning;">`recipientEmails=test@test.com`</mark> |
| <mark style="color:$warning;">`recipientIDs`</mark> <mark style="color:$warning;">`[]`</mark>    | Recipient member IDs.                                                                                |                                                                      |
| <mark style="color:$warning;">`search`</mark>                                                    | Free-text, case-insensitive substring across **recipient email, from address, to address, tx hash**. | <mark style="color:$warning;">`search=0xabc`</mark>                  |

### Example Request

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

<mark style="color:$warning;">`200 OK`</mark> — a JSON **array** of payout objects:

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

### Key Response Fields

| Field                                                           | Meaning                                                                                                                                                                                       |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`id`</mark>                       | Payout ID (use with <mark style="color:$warning;">`GET /withdrawal/{id}/merchant`</mark>).                                                                                                    |
| <mark style="color:$warning;">`status`</mark>                   | Lifecycle state (see the Overview).                                                                                                                                                           |
| <mark style="color:$warning;">`currencyType`</mark>             | <mark style="color:$warning;">`token`</mark> (ERC20/TRC20, e.g. USDC/USDT) or <mark style="color:$warning;">`coin`</mark> (native ETH/POL/TRX).                                               |
| <mark style="color:$warning;">`amount / amountInUSD`</mark>     | Token amount / USD value at creation.                                                                                                                                                         |
| <mark style="color:$warning;">`priceInUSD`</mark>               | Unit price used at creation (stablecoins = <mark style="color:$warning;">`1`</mark>).                                                                                                         |
| <mark style="color:$warning;">`fee`</mark>                      | On-chain network fee (set once sent).                                                                                                                                                         |
| <mark style="color:$warning;">`fromAddress`</mark>              | Project hot wallet paying out.                                                                                                                                                                |
| <mark style="color:$warning;">`toAddress / tokenAddress`</mark> | Recipient; token contract (<mark style="color:$warning;">`0x000…000`</mark> for native coins).                                                                                                |
| <mark style="color:$warning;">`txHash`</mark>                   | On-chain hash (set from <mark style="color:$warning;">`initiated`</mark> onward).                                                                                                             |
| <mark style="color:$warning;">`attributes`</mark>               | JSON; for <mark style="color:$warning;">`pending-approval`</mark> contains <mark style="color:$warning;">`approvalReason`</mark> (why approval is required).                                  |
| <mark style="color:$warning;">`failureReason`</mark>            | Specific cause on failed/stuck payouts.                                                                                                                                                       |
| <mark style="color:$warning;">`webhookStatus`</mark>            | Payout webhook delivery state — <mark style="color:$warning;">`received`</mark> (your endpoint accepted it) or <mark style="color:$warning;">`failed`</mark> (delivery failed after retries). |
| <mark style="color:$warning;">`createdBy`</mark>                | Origin of the payout.                                                                                                                                                                         |

### Pagination Pattern

```
GET …/withdrawal/merchant?limit=100&offset=0&sortBy=created_at&order=DESC
GET …/withdrawal/merchant?limit=100&offset=100&sortBy=created_at&order=DESC
# stop when a page returns < limit rows
```

### Errors

| HTTP | <mark style="color:$warning;">`code`</mark>                  | When                                                                                                        |
| ---- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| 401  | <mark style="color:$warning;">`UNAUTHORIZED`</mark>          | Missing/invalid <mark style="color:$warning;">`API-Key`</mark>, or a non-project key (JWT / member-linked). |
| 400  | <mark style="color:$warning;">`BAD_REQUEST`</mark>           | Malformed query parameters.                                                                                 |
| 404  | —                                                            | Endpoint not present (PayRam < v3.1.1).                                                                     |
| 500  | <mark style="color:$warning;">`INTERNAL_SERVER_ERROR`</mark> | Invalid <mark style="color:$warning;">`sortBy`</mark> (camelCase instead of snake\_case), or server error.  |


# Payout Webhooks

<figure><img src="/files/zwm9C3WmMen7bhNyxDfb" alt=""><figcaption></figcaption></figure>

Instead of polling, let PayRam push status changes to you. Whenever a payout transitions, PayRam **POSTs** a JSON event to your registered webhook URL — so you learn about `sent`, `processed`, `failed`, etc. as they happen.

> **Requires PayRam v3.1.1 or later.**

### Setup

1. Register your webhook URL in the dashboard for the project (**Project → Webhooks**) and set it to **active**.
2. The endpoint must be a publicly reachable **HTTPS** URL that responds with a <mark style="color:$warning;">`2xx`</mark> status.

Webhooks are **on by default**. (They can be disabled server-side with the <mark style="color:$warning;">`SEND_WEBHOOK_TO_MERCHANT=false`</mark> environment variable.)

### Delivery & retries

* Method: <mark style="color:$warning;">**`POST`**</mark>, <mark style="color:$warning;">`Content-Type: application/json`</mark>.
* **Verify authenticity** of every delivery using either header:
  * <mark style="color:$warning;">**`X-Payram-Signature`**</mark> (recommended) — an HMAC-SHA256 of the **raw request body**, keyed with your project API key, formatted <mark style="color:$warning;">`sha256=<hex>`</mark>. Recompute it on your side and constant-time compare.
  * <mark style="color:$warning;">**`API-KEY`**</mark> — your project API key sent verbatim (legacy; kept for backward compatibility).
* Each delivery is retried up to **3 times** (immediately, then after 2s and 4s) until your endpoint returns a <mark style="color:$warning;">`2xx`</mark>. Any response <mark style="color:$warning;">`≥ 400`</mark> (or a timeout — the client waits up to 60s) counts as a failure.
* The payout’s <mark style="color:$warning;">`webhookStatus`</mark> becomes <mark style="color:$warning;">`received`</mark> once your endpoint accepts a delivery, or <mark style="color:$warning;">`failed`</mark> if all attempts fail.
* Return <mark style="color:$warning;">`2xx`</mark> quickly and process asynchronously; treat events as **idempotent** (you may receive the same status more than once) and key off <mark style="color:$warning;">`payout_id`</mark> + <mark style="color:$warning;">`status`</mark>.

#### Verifying the signature

Compute the HMAC over the **exact raw bytes** of the request body (do not re-serialize the parsed JSON) and compare against the `X-Payram-Signature` header:

```jsx
const crypto = require('crypto');

function verifyPayramSignature(rawBody, signatureHeader, apiKey) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', apiKey).update(rawBody).digest('hex');
  // constant-time compare
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}
```

### Event types

The <mark style="color:$warning;">`event_type`</mark> is <mark style="color:$warning;">`payout.<status>`</mark> (lowercase). Note the status is the **webhook status label**, which maps from the payout’s lifecycle state:

| Payout <mark style="color:$warning;">`status`</mark> (API)                         | Webhook <mark style="color:$warning;">`status`</mark>   | <mark style="color:$warning;">`event_type`</mark>              |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------- |
| <mark style="color:$warning;">`pending-approval / pending-otp-verification`</mark> | <mark style="color:$warning;">`PENDING-APPROVAL`</mark> | <mark style="color:$warning;">`payout.pending-approval`</mark> |
| <mark style="color:$warning;">`pending`</mark>                                     | <mark style="color:$warning;">`APPROVED`</mark>         | <mark style="color:$warning;">`payout.approved`</mark>         |
| <mark style="color:$warning;">`initiated`</mark>                                   | <mark style="color:$warning;">`INITIATED`</mark>        | <mark style="color:$warning;">`payout.initiated`</mark>        |
| <mark style="color:$warning;">`sent`</mark>                                        | <mark style="color:$warning;">`SENT`</mark>             | <mark style="color:$warning;">`payout.sent`</mark>             |
| <mark style="color:$warning;">`processed`</mark>                                   | <mark style="color:$warning;">`PROCESSED`</mark>        | <mark style="color:$warning;">`payout.processed`</mark>        |
| <mark style="color:$warning;">`failed`</mark>                                      | <mark style="color:$warning;">`FAILED`</mark>           | <mark style="color:$warning;">`payout.failed`</mark>           |
| <mark style="color:$warning;">`rejected`</mark>                                    | <mark style="color:$warning;">`REJECTED`</mark>         | <mark style="color:$warning;">`payout.rejected`</mark>         |
| <mark style="color:$warning;">`cancelled`</mark>                                   | <mark style="color:$warning;">`CANCELLED`</mark>        | <mark style="color:$warning;">`payout.cancelled`</mark>        |

### Payload

```json
{
  "event_type": "payout.sent",
  "payout_id": 120,
  "network": "ETH",
  "token": "USDC",
  "amount": "100",
  "amount_usd": "100.000000",
  "email": "test@test.com",
  "address": "0x9F8E7D6C5B4A39281706F5E4D3C2B1A098765432",
  "from_address": "0x21d4cF2E…EA8d45",
  "tx_hash": "0xabc123…def456",
  "status": "SENT",
  "withdrawal_type": "payout_merchant",
  "currency_type": "token",
  "created_at": 1750340081,
  "updated_at": 1750340282,
  "timestamp": 1750340282,
  "failure_reason": ""
}
```

| Field                                                                      | Meaning                                                                                                                                |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`event_type`</mark>                          | <mark style="color:$warning;">`payout.<status>`</mark> — the event that fired.                                                         |
| <mark style="color:$warning;">`payout_id`</mark>                           | The payout <mark style="color:$warning;">`id`</mark> (matches the <mark style="color:$warning;">`id`</mark> from Create / Get Payout). |
| <mark style="color:$warning;">`network / token`</mark>                     | Blockchain code and currency.                                                                                                          |
| <mark style="color:$warning;">`amount / amount_usd`</mark>                 | Crypto amount sent and its USD value.                                                                                                  |
| <mark style="color:$warning;">`email / address`</mark>                     | Recipient email and destination wallet address.                                                                                        |
| <mark style="color:$warning;">`from_address`</mark>                        | Project hot wallet that paid out (empty until assigned).                                                                               |
| <mark style="color:$warning;">`tx_hash`</mark>                             | On-chain hash (empty until <mark style="color:$warning;">`initiated`</mark>).                                                          |
| <mark style="color:$warning;">`status`</mark>                              | Uppercase webhook status (see the mapping table).                                                                                      |
| <mark style="color:$warning;">`withdrawal_type`</mark>                     | <mark style="color:$warning;">`payout_merchant`</mark> for payouts created via this API.                                               |
| <mark style="color:$warning;">`currency_type`</mark>                       | <mark style="color:$warning;">`token`</mark> (ERC20/TRC20) or <mark style="color:$warning;">`coin`</mark> (native ETH/POL/TRX).        |
| <mark style="color:$warning;">`created_at / updated_at / timestamp`</mark> | Unix epoch seconds.                                                                                                                    |
| <mark style="color:$warning;">`failure_reason`</mark>                      | Reason string on <mark style="color:$warning;">`payout.failed`</mark> (empty otherwise).                                               |

> Always respond <mark style="color:$warning;">`2xx`</mark> to acknowledge. If your endpoint is unreachable or errors, PayRam marks the delivery <mark style="color:$warning;">`failed`</mark> after retries — you can still reconcile via **Get All Payouts** / **Payout Status**.


# Approving Held Payouts

<figure><img src="/files/PhgXm9EIWVrZbCmRX1rn" alt=""><figcaption></figcaption></figure>

A payout in <mark style="color:$warning;">`pending-approval`</mark> (it exceeded the auto-approve amount or an hourly/daily limit) needs to be approved or rejected from the **PayRam dashboard** by an authorized team member.

Open **Withdraw → Payouts** and use the approve / reject action on the payout’s row:

```
<https://yourdomain.com/project/all/withdraw/user-payouts>
```

Once approved, the payout continues automatically (<mark style="color:$warning;">`pending → initiated → sent → processed`</mark>); keep checking its state via **Payout Status**. If rejected, it becomes <mark style="color:$warning;">`rejected`</mark> (terminal).


# Editing Payout Limits

<figure><img src="/files/Jnk6SWn6ClFYwOb2yE9H" alt=""><figcaption></figcaption></figure>

***

Payout limits decide when a payout is auto-approved, held for approval, or rejected (see **Payout limits & approval** under Create Payout). They are **edited per project from the PayRam dashboard** — not via the API.

Open the project’s **Payout Limits** tab:

```
<https://yourdomain.com/settings/projects/{projectId}?tab=payoutConfig>
```

There you can set, per project:

| Setting                                | Effect                                                                                                                                                                               |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Auto-approve** (on/off) + **amount** | Payouts at or under the amount are auto-approved (<mark style="color:$warning;">`pending`</mark>); above it they are held (<mark style="color:$warning;">`pending-approval`</mark>). |
| **Daily limit**                        | Once a recipient’s payouts in this project for the day would exceed it, further payouts are held for approval.                                                                       |
| **Hourly limit**                       | Same as the daily limit, applied per hour.                                                                                                                                           |
| **Minimum amount**                     | Payouts below this are rejected outright.                                                                                                                                            |

Leaving a field blank makes the project **inherit the installation default**. The global minimum lives under **Settings → Withdrawal Limits**.

> Changes apply to payouts created **after** the update; don’t hard-code limit values in your integration — manage them here.


# Typescript/Javascript SDK

A lightweight TypeScript SDK for connecting your backend to your self-hosted PayRam server.

## Introduction

The PayRam TypeScript SDK helps your backend communicate smoothly with your self-hosted PayRam server. It provides a clean, type-safe interface so you don’t have to manually handle raw API calls, making integration simpler and more reliable. The SDK also includes built-in support for safe request retries and offers framework-friendly helpers for handling webhooks with minimal setup.

### Prerequisites

Before you begin, make sure you have:

* Your PayRam API Key, which is required for authenticating all requests sent through the SDK.
* The Base URL of your PayRam server, which tells the SDK where your self-hosted PayRam instance is running.

## Installation

Install the SDK using your package manager of choice

{% tabs %}
{% tab title="npm" %}

```typescript
npm install payram
```

{% endtab %}

{% tab title="yarn" %}

```javascript
yarn add payram
```

{% endtab %}

{% tab title="pnpm" %}

```javascript
pnpm add payram
```

{% endtab %}
{% endtabs %}

## QuickStart

* Create a new PayRam client instance by passing your API key and server URL.
* You can also provide optional configuration values such as timeouts and retry settings.

```typescript
import { Payram } from 'payram';

const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,      //required
  baseUrl: process.env.PAYRAM_BASE_URL!,    //required
  config: {
    timeoutMs: 10_000,                      // Optional
    maxRetries: 2,                          // Optional
    retryPolicy: 'safe',                    // Optional
    // allowInsecureHttp: true,             // Optional
  },
});
```

<table><thead><tr><th width="173.91796875">Option</th><th width="211.83984375">Type</th><th>Description</th></tr></thead><tbody><tr><td>apiKey</td><td>string</td><td>Your PayRam API key used to authenticate all SDK requests.</td></tr><tr><td>baseUrl</td><td>string</td><td>The base URL of your self-hosted PayRam server.</td></tr><tr><td>timeoutMs</td><td>number</td><td>Request timeout in milliseconds.</td></tr><tr><td>maxRetries</td><td>number</td><td>Maximum number of retry attempts for a request.</td></tr><tr><td>retryPolicy</td><td>'none' | 'safe' | 'aggressive'</td><td>Controls retry behavior — none disables retries, safe retries idempotent calls, and aggressive retries all requests.</td></tr><tr><td>allowInsecureHttp</td><td>boolean</td><td>Set to false only if your PayRam server is running on an http:// URL (without SSL). Keep it true for https:// </td></tr></tbody></table>

## Payments

In this section you'll get all the methods which are related to the payments

### Create Payments

* Creates a new payment session by sending customer details and the amount to PayRam, and returns both a unique reference\_id for tracking and a redirect URL that your customer can visit to complete the payment.
* These are the required fields you must include when creating a payment request using the PayRam SDK.

<table><thead><tr><th width="169.19921875">Field</th><th width="447.9765625">Description</th><th>Required</th></tr></thead><tbody><tr><td>customerEmail</td><td>Customer’s email address where the payment link will be sent/associated.</td><td>✅ Yes</td></tr><tr><td>customerId</td><td>Unique identifier for the customer.</td><td>✅ Yes</td></tr><tr><td>amountInUSD</td><td>The payment amount in USD.</td><td>✅ Yes</td></tr></tbody></table>

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

{% hint style="info" %}
**Note : The url field provides a ready-to-use PayRam payment page. You can share this link directly with your customers, or build a custom UI using other API endpoints.**
{% endhint %}

### Payment Status

* Fetches the latest payment details using the reference\_id and returns the current paymentState so you can track whether the payment is pending, completed, or failed.

```javascript
const payment = await payram.payments.getPaymentRequest(checkout.reference_id);
console.log(payment.paymentState);
```

* Shows all payment states and what each one means.

<table><thead><tr><th width="258.23046875">Status</th><th>Description</th></tr></thead><tbody><tr><td>OPEN</td><td>The payment has not been processed yet.</td></tr><tr><td>CANCELLED</td><td>The payment link has expired or was cancelled.</td></tr><tr><td>FILLED</td><td>The user has paid the full requested amount.</td></tr><tr><td>PARTIALLY_FILLED</td><td>The user has paid less than the requested amount.</td></tr><tr><td>OVER_FILLED</td><td>The user has paid more than the requested amount.</td></tr></tbody></table>

## Payout

In this section you'll get all the methods which are related to the payments

### Create Payout

* Creates a new payout request by sending the merchant details, token information, amount, and destination wallet address to the PayRam server.
* These are the required fields you must send when creating a payout through the PayRam SDK.

<table><thead><tr><th width="197.42578125">Field</th><th width="424.18359375">Description</th><th>Required</th></tr></thead><tbody><tr><td>email</td><td>Recipient’s email address.</td><td>✅ Yes</td></tr><tr><td>blockchainCode</td><td>Blockchain network used for the payout (e.g., ETH, TRX, BASE).</td><td>✅ Yes</td></tr><tr><td>currencyCode</td><td>Token symbol used for the payout (e.g., USDC, USDT).</td><td>✅ Yes</td></tr><tr><td>amount</td><td>Amount to transfer.</td><td>✅ Yes</td></tr><tr><td>toAddress</td><td>Recipient’s wallet address on the selected blockchain.</td><td>✅ Yes</td></tr><tr><td>customerID</td><td>Unique identifier for the customer.</td><td>✅ Yes</td></tr></tbody></table>

{% hint style="info" %}
**Note: PayRam currently supports payouts in USDT (ETH, TRX) and USDC (ETH, BASE). Make sure the selected currency matches a supported network when creating a payout.**
{% endhint %}

```typescript
await payram.payouts.createPayout({
  email: 'merchant@example.com',
  blockchainCode: 'ETH',
  currencyCode: 'USDT',
  amount: '125.50',
  toAddress: '0xfeedfacecafebeefdeadbeefdeadbeefdeadbeef',
  customerID: 414817384
});
```

### Payout Status

* Retrieves the latest payout details using its ID so you can check whether the payout is still pending, awaiting approval, processing on-chain, completed, or failed.

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

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

* Shows all payment states and what each one means.

| Status                   | Description                                                                   |
| ------------------------ | ----------------------------------------------------------------------------- |
| pending-otp-verification | Waiting for OTP verification before processing.                               |
| pending-approval         | Awaiting admin or system approval.                                            |
| pending                  | Approved and ready for blockchain processing.                                 |
| initiated                | The payout has been broadcast to the blockchain and is awaiting confirmation. |
| sent                     | The payout has been successfully sent to the recipient.                       |
| failed                   | The transaction failed due to a processing error.                             |
| rejected                 | The payout request was declined by the admin or system.                       |
| processed                | The payout is confirmed on-chain and recorded in the accounting.              |
| cancelled                | The transaction was stopped before being sent or processed.                   |

## Webhook

PayRam sends webhook events to your server whenever something important happens, such as a payment updates.

The SDK provides ready-to-use handlers for Express, Fastify, and Next.js (both App Router and Pages Router). These handlers help you process webhooks safely and correctly. They do the following:

* Check the API-Key header to confirm the request really came from your PayRam server
* Read and validate the webhook payload
* Send back the correct response so PayRam knows your server received the event

{% tabs %}
{% tab title="Express Example" %}

```typescript
import express from 'express';
import { Payram } from 'payram';

const app = express();
const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,
  baseUrl: process.env.PAYRAM_BASE_URL!,
});

app.post(
  '/payram/webhook',
  payram.webhooks.expressWebhook(async (payload, req) => {
    console.log('Received Payram event:', payload.event, payload.reference_id);
    // handle payment / referral events here
  }),
);

app.listen(3000);
```

{% endtab %}

{% tab title="Fastify Example" %}

```typescript
import Fastify from 'fastify';
import { Payram } from 'payram';

const fastify = Fastify();
const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,
  baseUrl: process.env.PAYRAM_BASE_URL!,
});

fastify.post(
  '/payram/webhook',
  payram.webhooks.fastifyWebhook(async (payload, request) => {
    console.log('Payram webhook event:', payload.event, payload.reference_id);
    // handle payment / referral events here
  }),
);

await fastify.listen({ port: 3000 });
```

{% endtab %}

{% tab title="Next.js Example (App Router)" %}

```typescript
// app/api/payram/webhook/route.ts
import { NextRequest } from 'next/server';
import { Payram } from 'payram';

const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,
  baseUrl: process.env.PAYRAM_BASE_URL!,
});

export const POST = payram.webhooks.nextAppRouterWebhook(
  async (payload, req: NextRequest) => {
    console.log('Payram webhook event:', payload.event, payload.reference_id);
    // handle payment / referral events here
  },
);
```

{% hint style="info" %}
**Note: The adapter handles verification and sends the reply automatically. No manual res.status(200) is required.**
{% endhint %}
{% endtab %}
{% endtabs %}

## Validate Api Key

The verifyApiKey function lets you manually check the API key inside your request handler. Use it when you are handling webhooks with a custom framework and need to confirm the request is really from your PayRam server.

```typescript
import { verifyApiKey } from 'payram';

if (!verifyApiKey(req.headers, process.env.PAYRAM_API_KEY!)) {
  return res.status(401).json({ error: 'invalid-key' });
}

const payload = req.body;
handleEvent(payload);
```


# PayRam Shopify Plugin

This guide walks you through connecting PayRam as a payment method on your Shopify store. It has three parts: setting up the plugin server, configuring it in Shopify, and testing your first payment.

## Part A: Server Setup (Terminal)

#### 1. Get the installation script

<figure><img src="/files/vGMfPJCfGjhT27XgtwP4" alt=""><figcaption></figcaption></figure>

Go to the PayRam GitHub repository and open the Shopify repo. Copy the bash installation link provided there.

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

#### 2. Run the script in terminal

> This can be run on any server. It does not need to be the same server where your main PayRam instance is installed.

<figure><img src="/files/Pp9Z5zKkPwvd6k0IpC3p" alt=""><figcaption></figcaption></figure>

The script will walk you through setup. You can accept all default values unless you have specific configuration needs.

#### 3. Configure HTTPS on port 2798

<figure><img src="/files/A8RwZW15X5vNpn385PK9" alt=""><figcaption></figcaption></figure>

Once installed, you need to expose port `2798` via HTTPS. Use either:

* An **nginx reverse proxy**, or
* A direct **HTTPS configuration** on your server

#### 4. Log in and create your app

<figure><img src="/files/Q2WM2ZGh2B8kpn55vGHT" alt=""><figcaption></figcaption></figure>

Open the login page URL shown at the end of the script.

<figure><img src="/files/q3gWi26xZf90CuyF86Se" alt=""><figcaption></figcaption></figure>

Sign in and authenticate with your Shopify credentials.

<figure><img src="/files/r9NUlc45orlkebAGtLCr" alt=""><figcaption></figcaption></figure>

Then run the app creation step in the terminal when prompted.

#### 5. Add your Shopify store URL

<figure><img src="/files/Msy21c1CvBo5xDBXpbzw" alt=""><figcaption></figcaption></figure>

When asked, enter your Shopify store's URL.

#### 6. Choose a database

<figure><img src="/files/Qqty9YOBa0QeBoLhTD3m" alt=""><figcaption></figcaption></figure>

You can either connect an external database or use the default SQLite option, which works fine for most setups.

#### 7. Install the app to your Shopify dashboard

<figure><img src="/files/nt5vqcgZjdsYkUM3wcF7" alt=""><figcaption></figcaption></figure>

In the terminal, follow the URL to install the PayRam app onto your Shopify store.

<figure><img src="/files/JJNVeZS5SQFdgzszxnXr" alt=""><figcaption></figcaption></figure>

It will open up in your browser, select Install to continue.

<figure><img src="/files/THm80d5ZUk3xX9gy0522" alt=""><figcaption></figcaption></figure>

Inside the app settings, enter the following:

* **Base URL** - the URL of your PayRam plugin server (from Part A) along with the port number
  * For eg. <https://payram.yourdomain.com:8443>
* **Project API Key** - found in your PayRam dashboard ([access here](https://docs.payram.com/features/payment-apis#managing-api-keys))
* **Payment Method Name** - enter a custom name for the label to be displayed to customers

Once done, click Save Settings.

#### 8. Test the connection

<figure><img src="/files/53fDuoVEM1cPOwW8Q5Xb" alt=""><figcaption></figcaption></figure>

Click Test PayRam Connection to test the connection. A successful response returns an HTTP 200 status, which confirms the connection is working correctly.

***

### Part B: Shopify Dashboard Configuration

#### 1. Add PayRam as a manual payment method

<figure><img src="/files/VgYQL7ncCPA1ynAlipHS" alt=""><figcaption></figcaption></figure>

Go to: Settings > Payments

<figure><img src="/files/yLXMmWf4kS0HaVPH7RKR" alt=""><figcaption></figcaption></figure>

Select Manual Payment Methods and from the dropdown, select Create custom payment method and set it up as PayRam.

#### 2. Customize your checkout page

<figure><img src="/files/ddLSrrf9yYOPoU2Zp6gq" alt=""><figcaption></figcaption></figure>

From the Shopify sidebar, select **Checkout > Customize**. This is where customers will see the PayRam payment option.

The customer flow works like this:

<figure><img src="/files/dqxw7kGdrNmGnj8h8a3U" alt=""><figcaption></figcaption></figure>

Customer selects Pay via PayRam at checkout.

<figure><img src="/files/NgFQ1MblqVQqnACj7X60" alt=""><figcaption></figcaption></figure>

They complete the payment on the **Thank You page** after placing the order

> Approve the app and add it to the **Thank You page** so the payment widget appears there.

***

### Part C: Test Payment

Once everything is configured, run a test to confirm the full flow works end to end.

1. Visit your Shopify store
2. Add any item to your cart
3. Proceed to checkout
4. Select **Pay via PayRam**
5. Click **Pay Now**
6. On the Thank You page, enter your email address
7. A PayRam payment link will be generated
8. Complete the payment using the link

If the payment goes through successfully, your integration is live and ready to use.


# PayRam MCP

This section explains how to use the PayRam MCP server to integrate payments, payouts, webhooks, and referral workflows into your application efficiently.

## Introduction

The PayRam MCP Server allows AI assistants to connect with the PayRam platform and help businesses set up and manage crypto payments with ease.

It supports key payment-related workflows such as payment creation, payouts, webhook handling, and referral management. In addition, it provides an overview of core PayRam concepts, standard payment flows, and practical integration guidance, along with example snippets to simplify implementation.

### Key capabilities

* **Payment Operations**: Create payment intents, track payment status, and manage end-to-end payment flows.
* **Payout Management**: Initiate and monitor payouts across multiple blockchains and supported currencies.
* **Webhook Handling**: Receive and process webhook events, including signature verification and status updates.
* **Referral System**: Configure referral campaigns, track referral activity, and manage reward distribution.
* **Integration Assistance**: Access guided setup instructions, recommended best practices, and implementation examples.
* **Multi-Framework Support**: Generate integration snippets for commonly used backend frameworks to accelerate development.

### Prerequisites

* An MCP-compatible client (examples provided below).
* The ability to configure a custom MCP server using an HTTP endpoint.
  * No authentication headers are required when using the hosted PayRam MCP endpoint.

### Client Configuration

{% tabs %}
{% tab title="VSCode" %}

1. **Install GitHub Copilot**
   * Ensure you are using a version of the GitHub Copilot extension that supports the Model Context Protocol (MCP).
2. **Open Copilot MCP Settings**
   * In VS Code, open **Settings**, then search for **Copilot: Model Context Protocol** and select **Add Server**.
3. **Configure the MCP Server**
   * Choose **HTTP Server** and enter the following details:
     * **Name:** `payram`
     * **URL:** `https://mcp.payram.com/mcp`
     * **SSE URL (optional, recommended):** `https://mcp.payram.com/mcp/sse`
     * **Headers:** Leave empty
4. **Save the Configuration**
   * After saving, GitHub Copilot will automatically detect and list the available PayRam tools.
5. **Start Using PayRam Tools**
   * You can now trigger PayRam workflows by asking Copilot prompts such as:
     * “test payram”
     * “assess my project”
   * Copilot will route the request to the appropriate PayRam MCP flow.
     {% endtab %}

{% tab title="Cursor" %}

1. **Open MCP Settings**
   * In Cursor, open **Settings** and navigate to **MCP Servers**.
2. **Add a New MCP Server**
   * Click **Add** and select **HTTP** as the server type.
3. **Configure the Server**
   * Enter the following details:
     * **Name:** `payram`
     * **URL:** `https://mcp.payram.com/mcp`
     * **SSE URL:** `https://mcp.payram.com/mcp/sse`
4. **Save and Restart**
   * Save the configuration. If required, restart the chat pane to ensure the server is loaded correctly.
5. **Start Using PayRam MCP**
   * You can now use the same prompts, such as:
     * “test payram”
     * “integrate payram into this repo”
   * Cursor will route these requests to the appropriate PayRam MCP tools.
     {% endtab %}

{% tab title="Claude Desktop" %}

1. **Open MCP Settings**
   * In Claude Desktop, go to **Settings** and navigate to **MCP Servers**.
2. **Add a New MCP Server**
   * Add a new server and select **HTTP** as the server type.
3. **Configure the Server Details**
   * Enter the following information:

     * **Name:** `payram`
     * **URL:** `https://mcp.payram.com/mcp`
     * **SSE URL:** `https://mcp.payram.com/mcp/sse`

     *(If the client supports Server-Sent Events. Otherwise, leave this field blank.)*
4. **Confirm and Restart the Chat**
   * Save the configuration and reopen a chat session to ensure the MCP server is loaded.
5. **Verify the Integration**
   * Ask Claude to perform a PayRam-specific action to confirm that the PayRam tool list is available.
     {% endtab %}

{% tab title="Generic MCP Clients" %}
If your MCP-compatible client allows manual registration of an HTTP MCP endpoint, configure it with the following details:

* **URL:** `https://mcp.payram.com/mcp`
* **SSE URL (optional):** `https://mcp.payram.com/mcp/sse`
* **Headers:** None

Save the configuration and reload the client or reopen the chat session if required. Once configured, you can verify the setup by asking the client to perform a PayRam-specific action.
{% endtab %}
{% endtabs %}

### Sample Prompts to Get Started

You can use the following example prompts with GitHub Copilot to explore and test PayRam MCP capabilities:

* **“Test the PayRam MCP connection.”**
* **“How does PayRam work? Explain the payment flow.”**
* **“Help me integrate PayRam payments into my project.”**
* **“Create a simple application to test PayRam payments.”**
* **“Create a payment and show how to check its status.”**

### Security Considerations

* Do not share **PayRam API keys**, **webhook secrets**, or any other sensitive credentials in client-side code or AI prompts.
* Ensure that only **trusted AI clients and applications** are allowed to connect to the PayRam MCP server.
* Validate and review all actions triggered via MCP, especially those related to **payment creation** and **payout execution**.
* Use **separate PayRam credentials** for development and production environments to reduce operational risk.


# Analytics MCP

This section walks through the process of integrating the PayRam Analytics server with Telegram to receive real-time updates on payments, users, payouts, and system analytics in Telegram chats.

### Introduction

The PayRam Telegram Analytics Bot provides direct access to PayRam analytics from Telegram. Once configured, authorized users can query payments, users, payouts, and activity without accessing the PayRam dashboard.

The bot connects securely to the PayRam Analytics server and responds only in allowlisted chats, enabling teams to monitor metrics, generate summaries, and obtain insights directly within Telegram.

***

### Prerequisites

Before setting up the PayRam Telegram Analytics Bot, ensure the following requirements are met:

* A server (VPS or dedicated machine) where the bot will be deployed and run
* A running PayRam server with analytics enabled
* PayRam dashboard **admin credentials** (email and password)
* A Telegram bot token created using **@BotFather**
  * Refer to this guide for setup instructions: <https://blog.devgenius.io/how-to-set-up-your-telegram-bot-using-botfather-fd1896d68c02>
* An OpenAI API key for generating analytics responses
* Docker installed on the server

***

### Installation

{% stepper %}
{% step %}

#### Run the setup script

```
./setup_payram_agent.sh
```

{% endstep %}

{% step %}

#### Provide required configuration details

* During the setup process, you will be prompted to enter the following information:

  * **Publicly accessible PayRam Server URL**
    * This URL must be reachable by the analytics bot.

  <figure><img src="/files/1ucGWmeILVRDa9ygVbqq" alt=""><figcaption></figcaption></figure>

  * **PayRam dashboard admin credentials**
    * The admin email and password used to authenticate the analytics bot with your PayRam server.

<figure><img src="/files/hj16AZ0LgfO06KL2T9ze" alt=""><figcaption></figcaption></figure>

* **OpenAI API Key**
  * Required to enable AI-powered analytics responses.
* **Telegram Bot Token**
  * The token generated via **@BotFather** for your Telegram bot.
* **Allowed Telegram Users**

  * A comma-separated list of Telegram usernames that are permitted to interact with the bot.

  <figure><img src="/files/26Gsp0j54brzTUuMdGjz" alt=""><figcaption></figcaption></figure>
* **Auto-Updates (Optional)**

  * Choose whether the analytics bot should automatically update itself when new versions of the Analytics MCP server are released.

  <figure><img src="/files/zvrge6EHAYCpQRct5UQ9" alt=""><figcaption></figcaption></figure>
* **Start Container After Setup (Optional)**

  * Choose whether to start the analytics agent Docker container immediately after the setup completes.

  <figure><img src="/files/nBQCAuzyFDA4rdrQl0rC" alt=""><figcaption></figcaption></figure>

If you choose to start the container during setup, the Analytics MCP server will be installed and running once the process completes. You can then open Telegram and begin using the bot.
{% endstep %}

{% step %}

#### Using the Telegram Analytics Bot

Once the setup is complete, open Telegram and send a message to the bot from an allowlisted chat. The bot will respond with PayRam analytics in the same chat.

**Example Queries:**

* **“Show me today’s payments summary.”**
* **“Create a payment link for 3 USD on the main project with email <example@gmail.com> and customerId cust-123.”**
* **“Top paying users this week.”**
* **“Deposit distribution by chain for the last 7 days.”**
* **“Payouts by currency for December.”**
* **“User growth compared to the previous period.”**
  {% endstep %}
  {% endstepper %}

> <mark style="color:$warning;">**Access Control Note**</mark>
>
> <mark style="color:$warning;">If you message the bot from a chat that is not allowlisted, it will respond with an</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">**“Access denied”**</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">message along with the</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">`chat_id`</mark><mark style="color:$warning;">. Add this</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">`chat_id`</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">using the allowlist update command, then retry your request.</mark>

### Managing Bot Access

You can grant access to additional users or groups without rerunning the full setup by using the commands below.

#### Add Telegram Usernames (Recommended)

Use this option to allow individual Telegram users to interact with the analytics bot:

```bash
./setup_payram_agent.sh --add-telegram-usernames "alice,@bob,t.me/carol"
```

> <mark style="color:$warning;">**Notes:**</mark>
>
> * <mark style="color:$warning;">Usernames can be provided with or without the</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">`@`</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">prefix or</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">`t.me/`</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">format.</mark>
> * <mark style="color:$warning;">Multiple usernames must be comma-separated.</mark>

#### Add Telegram Chat IDs (For Groups)

Use this to allow Telegram groups or chats:

```bash
./setup_payram_agent.sh --add-telegram-chat-ids "12345,67890"
```


# Payment Links

Get paid instantly, anywhere.

<figure><img src="/files/Ee3k4yXBV0gXiYme5xsW" alt=""><figcaption></figcaption></figure>

Payment Links are shareable URLs that let customers pay you in seconds.&#x20;

No checkout page or integration required.&#x20;

Simply Create ➡️ Share Link ➡️ Collect Payments.&#x20;

Close sales directly in chats, DMs, or emails. Perfect for one-off sales, custom invoices, or quick payments. Less friction. More conversions.

***

### **Why it matters**

* **Faster checkout:** Customers pay in one click, no redirects or logins.
* **Flexible use:** Great for one-time transactions, services, or quick settlements.
* **Seamless sharing:** Works across WhatsApp, Telegram, email, or any platform.
* **Higher conversions:** Remove barriers and capture intent instantly.
* **Universal access:** Works on all devices and browsers, with built-in security.

***

### How to create a payment link

{% stepper %}
{% step %}

### Creating payment link

Go to Payments and expand the section. Select Create Payment Link to generate a new payment link.

<figure><img src="/files/NzU4Vn0tbZ9Q0D1xHWOE" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### How to add a member

Before you select **Generate Payment Link**, complete these steps:

1. Add a new member by entering their email, or select an existing member if available.
2. If this is your first time setting up, the member list is likely empty.
   {% endstep %}

{% step %}

### Add new member

Select the member email input box. Select Add New Member when the option appears. A pop-up screen opens where you can enter the member’s details.

<figure><img src="/files/K37wlhFNwhf1xoxz2HAJ" alt=""><figcaption></figcaption></figure>

Enter the customer’s email, select the project, and then select Add Member.

<figure><img src="/files/MST8qNYdPbLxNp7Bv9Q0" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Enter amount

After you add the member details, enter the amount to charge that user. Select Generate Payment Link. The system generates a link, which you share with your customer.

<figure><img src="/files/5y7NHZLuuY6X43wRDtbr" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Click on generate payment link

After you add the member details, enter the amount to charge that user. Select Generate Payment Link. The system generates a link, which you share with your customer.

<figure><img src="/files/BEhTPbzkQEadKzYUIlZv" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Payment page

You'll be redirected to a payment link you can share that to your customer.

<figure><img src="/files/HltmLK2pDNqJFnI7G87d" alt=""><figcaption></figcaption></figure>

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: If you generate a payment link and the deposit address appears blank, it means the blocks are not being processed. To fix this, restart your PayRam server by running the reset command script.</mark>

👉 [View Restart Command Guide](/script/script-usage)
{% endhint %}
{% endstep %}

{% step %}

### Select preferred coin and network

When making a payment, customers can select their preferred coin and network.

<figure><img src="/files/0ujW9JLTQJ7Q2rf0yRvj" alt=""><figcaption></figcaption></figure>

Currently, PayRam supports these coins and networks.
{% endstep %}

{% step %}

### Payment successful

After the customer pays, the status updates once the minimum number of onchain confirmations are complete. When confirmed, the system shows Payment Successful.

<figure><img src="/files/LtpN8ThYdyiCH5Ld8Odk" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

***

### **Sharing links**

Share links wherever your customers are.

You can:

* Copy and paste directly into chats or emails.
* Use the **Share via** menu to send through WhatsApp, Telegram, or SMS.
* Embed inside invoices, receipts, or marketing campaigns.

> Pro tip: Combine with QR codes for offline payments: Scan, Pay, Done.

***

### **Tracking payments**

Every link comes with built-in analytics:

* Payment status (Pending, Successful, Cancelled)
* Customer details
* Amount received, network details, and time of payment

View all active and completed links under **Payments → All Payments**.

***

### **Common use cases**

* **Freelancers:** Get paid for projects or hourly services.
* **Businesses:** Send quick pay links for invoices or order confirmations.
* **Support teams:** Collect payments inside chat tickets.
* **Events:** Share payment links for registrations or donations.
* **Influencers & creators:** Sell digital goods directly via DMs.


# Payment APIs

Seamless, programmable payments.

<figure><img src="/files/ZVBTexBVyMwusx8Tmimn" alt=""><figcaption></figcaption></figure>

Integrate PayRam’s Payment APIs to drive transactions from your app or backend, handle payments, webhooks, and more, all under your control.

***

### **Why it matters**

* **Full automations:** Let your backend create and manage payments, no manual intervention.
* **Custom workflows:** Tailor logic before triggering a payment.
* **Real-time feedback:** Use webhooks to react to payments as they arrive or settle.
* **Scalability & control:** Integrate with your architecture and scale usage programmatically.

***

### **Managing API keys**

API keys are required to authenticate all PayRam API requests. Each key is tied to a specific **project**, allowing for environment-level control and security.

**Creating or managing API keys:**

1. Go to **Settings → Accounts** in your PayRam dashboard.
2. Select the **Project** you want to integrate.
3. Navigate to **API Keys**.
4. Copy your **Key**.
5. You can also create new API Keys by clicking on **Add New**.
6. You can also deactivate existing keys by toggling them to inactive.


# Multi-currency & Multi-chain Support

Accept payments your way, anywhere.

<figure><img src="/files/pTtDl81MQKU3Q9LBsJEW" alt=""><figcaption></figcaption></figure>

PayRam enables seamless payments across multiple cryptocurrencies and blockchain networks empowering merchants and customers with flexibility, global reach, and interoperability.

***

### **Why it matters**

* **Global reach:** Accept payments from anywhere, in the user’s preferred currency or chain.
* **Higher conversion rates:** Reduce drop-offs by supporting the most popular tokens and networks.
* **Hedging flexibility:** Settle in stablecoins (USDC, USDT) or crypto assets (BTC, ETH) as needed.
* **Seamless integration:** One API handles all currencies and chains, no separate setup required.
* **Future-proof:** PayRam continues expanding support as new chains gain traction.

***

| Cryptocurrency           | Symbol | Supported Networks      |
| ------------------------ | ------ | ----------------------- |
| Bitcoin                  | BTC    | Bitcoin                 |
| Ethereum                 | ETH    | Ethereum, Base          |
| Tether                   | USDT   | Ethereum, Tron, Polygon |
| USD Coin                 | USDC   | Ethereum, Base, Polygon |
| Tron                     | TRX    | Tron                    |
| Coinbase Wrapped Bitcoin | cbBTC  | Base                    |
| Polygon                  | POL    | Polygon                 |
| PayPal USD               | PYUSD  | Ethereum                |

> Coming soon:
> \
> Solana (SOL, USDC): high-speed, low-fee payments for mainstream use.
> \
> TON (Toncoin): frictionless, chat-native crypto payments for mass adoption.

***

### **Use cases**

* **Global merchants:** Accept multi-chain payments from customers around the world.
* **Crypto-native businesses:** Integrate stablecoins like USDT and USDC across Ethereum and Tron.
* **dApps and SaaS platforms:** Enable cross-chain payments for digital subscriptions or on-chain products.
* **Enterprises:** Centralize payments from multiple tokens and networks in one dashboard.
* **Retail commerce:** Use Tron and Base for high-volume, low-fee transactions.

***

### **Upcoming integrations**

PayRam continuously expands its blockchain ecosystem support:

* **Solana (SOL / USDC):** for high-speed, low-cost stablecoin payments.
* **TON (Toncoin):** for chat-native payment experiences.

> Future roadmap: Integrations with Arbitrum, Polygon, and Optimism are under review.


# SmartSweep

Automate your fund management.

<figure><img src="/files/oWrVeC7JfVoUZRFB0WJK" alt=""><figcaption></figcaption></figure>

SmartSweep automatically transfers funds from Customer Deposit Wallets to your designated Cold Wallet, helping you consolidate balances securely and efficiently, without manual intervention or exposed keys.

***

### **Why it matters**

* **Save time:** No more manual consolidation of deposits.
* **Improve efficiency:** Maintain optimal wallet balances for payouts and settlements.
* **Enhance security:** Sweep operations use smart contracts, not private keys.
* **Stay audit-ready:** Every sweep transaction is logged and traceable.
* **Lower costs:** Fewer transactions mean reduced operational and network fees.

***

### **SmartSweep workflow**

1. **Customer Deposit Wallets** receive funds from individual users.
2. **SmartSweep** automatically detects available balances that meet the pre-configured threshold.
3. The system initiates an onchain transaction.
4. Funds are moved from deposit wallets to your designated **Cold Wallet**.
5. Each sweep is confirmed, logged, and visible in your **SmartSweep Dashboard**.

***

### **How it works**

Once a wallet is activated, PayRam can sweep funds automatically based on three configurable settings:

1. **Amount:** SmartSweep is triggered when either,
   * An individual deposit wallet’s balance reaches the set amount, or,
   * The total balance across multiple wallets in a batch reaches the set amount.
2. **Address count:** The sweep occurs after a set number of deposit addresses have received funds.
3. **Time:** The sweep occurs after a set time period has elapsed.


# Customer Deposit Wallets

Unique wallets per customer.

<figure><img src="/files/iCv9yhYku7fWf7PlMsog" alt=""><figcaption></figcaption></figure>

Give each customer their own deposit address or wallet within PayRam, so they can top up, settle balances, or make repeat payments without needing to supply a new address each time.

***

### **Why it matters**

* **Frictionless deposits:** Customers can deposit anytime without needing you to issue a new address or link each time.
* **Consistency & reuse:** The same deposit address works repeatedly (i.e. “permanent deposit address”).
* **Easier accounting & attribution:** Funds go directly to a customer’s wallet, simplifying ledger entries and reconciliation.
* **Better UX:** Your customers don’t have to request a fresh address each time, speeds up repeat payments.
* **Support for multiple assets:** You can support wallets per token or network, depending on your architecture.

***

### **How it works**

1. When a new customer is onboarded, PayRam creates a unique deposit address mapped to that customer (and possibly per token / network).
2. When the customer sends funds to that address, PayRam monitors the chain (or network), identifies and attributes the incoming transaction to the correct customer wallet.
3. The deposited amount is credited to the customer’s internal balance (or account ledger) in PayRam.
4. Internally, PayRam may consolidate or sweep funds from multiple customer wallets into its master wallet(s) to manage liquidity and gas efficiency (if blockchain).
5. On withdrawals, spends, or transfers, PayRam can debit from the customer’s wallet balance.

This is analogous to “permanent deposit address” setups used by crypto gateways, where each user has a persistent address for deposits.

***

### **Using deposit wallets**

* **Customer deposit:** The customer sends funds to the given address (on the appropriate network).
* **Monitoring & attribution:** PayRam listens for incoming transactions, matches them to known deposit wallets, and credits the customer’s balance.
* **Balance display:** Show real-time wallet balance in merchant dashboard.

***

### **Balances, transfers, and consolidation**

* **Internal balance model:** Maintain a ledger of balances per customer wallet.
* **Consolidation / sweeping:** Periodically sweep small deposits into a master wallet to reduce on-chain overhead.

***

### **Security & reconciliation**

* **Address uniqueness:** Ensure deposit addresses are unique and collision-resistant.
* **Monitoring / alerting:** Watch for suspicious deposits, double spends, or network reorgs.
* **Confirmations:** Only credit after required blockchain confirmations (configurable).
* **Error handling:** Rejections or refunds if wrong token / network.
* **Audit trails:** Record every deposit, sweep, internal transfer, and withdrawal.


# Multi-brand Setup

Expand without limits.

<figure><img src="/files/kfyV50og2qtUet1FUbD6" alt=""><figcaption></figcaption></figure>

Merchants can now create and manage multiple projects or stores under a single PayRam account.

Each project can have its own logo, website URL, and API keys, while your payout account and wallets stay unified.

Ideal for scaling brands, localizing sites, or testing new verticals, all from one clean dashboard.

***

### **Why it matters**

* **Organize better:** Track every Payment Link, Transaction, and Report by store or brand.
* **Move faster:** Launch new ideas and test niches without extra installations.
* **Go global:** Localize your site and accept payments across different markets.
* **Stay efficient:** Manage B2B and B2C operations seamlessly under one roof.
* **Simplify finance:** Unified payouts and wallet balances, regardless of project count.

***

### **How to create a new project**

1. Go to **Settings → Accounts** in your PayRam dashboard.
2. Click **New Project** to create a new one.
3. Enter project details such as:
   * **Project Name**
   * **Website URL**
   * **Redirection URLs**
   * **Branding: Logo, colors, social media links, etc.**
4. Configure project-specific APIs and webhook endpoints.
5. Configure project-specific payment options and wallet.

***

### **Managing projects**

* **Switch between projects:** Use the dropdown in the left menu to toggle active projects.
* **Edit branding:** Update project logos, URLs, and details anytime under *Settings → Account → Projects → Edit*.
* **Assign roles:** Restrict teammate access by project using the **User Management** feature.
* **View data:** Filter analytics, transactions, and Payment Links by project for deeper insights.

***

### **API separation**

Each project is issued its own **API keys** and **webhook endpoints**, giving you full control and traceability.

**Benefits include:**

* Isolation of environments for testing and production.
* Clear audit trails per project.
* Easy integration with multiple websites or apps.
* Enhanced security, revoke or rotate keys project-wise without affecting others.

***

### **Common use cases**

* **Multi-brand businesses:** Manage different brands under one organization.
* **Regional operations:** Localize projects for different countries or currencies.
* **Product experiments:** Test new offerings before full rollout.
* **Enterprise accounts:** Separate internal departments (e.g., Retail, Wholesale, Digital).


# User Management

Collaboration just got easier on PayRam.

<figure><img src="/files/VdwZe9aO8BZZ33nffguy" alt=""><figcaption></figcaption></figure>

Add teammates to your PayRam dashboard and assign roles based on what they need to do.
\
Give full control to your operations team or grant limited permissions to specific projects. Every role stays secure.

***

### **Why it matters**

* **Operate safely** without sharing sensitive credentials.
* **Customize access** based on roles and responsibilities.
* **Maintain compliance** through role-based data segregation.
* **Simplify teamwork** across projects, payments, and referrals.

***

### **How to add your team members**

1. Go to **Settings → User Management** in your PayRam dashboard
2. Click **Invite**
3. Enter the teammate’s email address and username
4. Select a role (Admin, Project Lead, Project Manager, Project Ops, or Platform Referral Admin)
5. Select a project
6. Create and confirm password details
7. Click Confirm to complete

***

### Roles and permissions

| Role                    | Description                                                                                                                         | Permissions                                                                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Admin                   | Overall organisation manager with wide access across PayRam, including projects, payments, and team settings. Cannot modify Owners. | <p></p><ul><li>View & manage all projects and payments</li><li>Invite or remove users (except Owners)</li><li>Access reports and audit logs</li></ul> |
| Project Lead            | Leads individual projects and manages project-related data.                                                                         | <p></p><ul><li>Create and update projects</li><li>View project analytics</li><li>Manage project-specific teams</li></ul>                              |
| Project Manager         | Supervises projects with view-only access to project data.                                                                          | <p></p><ul><li>View project dashboards</li><li>Export project reports</li><li>Track project milestones</li></ul>                                      |
| Project Ops             | Handles operational workflows related to payments and customers.                                                                    | <p></p><ul><li>View payment data</li><li>View customer information</li><li>Monitor settlement statuses</li></ul>                                      |
| Platform Referral Admin | Manages all referral integrations and related APIs.                                                                                 | <p></p><ul><li>Full access to referral APIs</li><li>Configure, edit, and track referral programs</li></ul>                                            |

> **Note:** Only Admins or Owners can assign or modify roles. Owners cannot be removed or downgraded. Each user can hold only one role at a time.


# Analytics & Reporting

Turn your data into decisions.

<figure><img src="/files/MUgKuW8I2qBmvzxgeHmK" alt=""><figcaption></figcaption></figure>

Gain actionable business insights with PayRam’s Analytics & Reporting dashboard.&#x20;

Easily monitor performance, understand customer behavior, and make smarter, data-driven decisions, all from one intuitive interface.

***

### **Why it matters**

* **See what drives growth:** Revenue, customers, and conversions at a glance.
* **Make data-driven decisions** using accurate, real-time dashboards.
* **Understand your customers** through retention and behavioural metrics.
* **Optimise payments** by tracking success rates, networks, and tokens.
* **Export and share reports** seamlessly with your team or accounting tools.

***

### Key dashboards

The Analytics module is organised into three sections for clarity and focus:

#### Revenue Insights

Keep track of your earnings and identify trends that shape your business growth.

**You can view:**

* Total and net revenue
* Growth rate and time-based trends
* Average order value (AOV)
* Top-performing products or stores
* Revenue share by network or payment method

> Tip: Filter by time period (daily, weekly, monthly, quarterly) to monitor performance across campaigns or regions.

#### Customer Analytics

Understand who your customers are and how they interact with your platform.

**Metrics include:**

* **Acquisition:** Number of new customers in a selected period
* **Retention:** Returning customer rates and churn patterns
* **ARPU (Average Revenue per User):** Calculate user profitability
* **Top segments:** Identify high-value or repeat customers

> Use case: Discover if your new payment options improve retention or reduce churn over time.

#### Transaction Health

Track the pulse of your payment operations and ensure frictionless experiences.

**Metrics include:**

* Payment success rate
* Decline and failure reasons
* Popular payment networks and tokens used
* Average processing time
* Settlement lag by region or method

> Insight: If your success rate dips for a particular token or network, you can act fast — either optimize configurations or notify customers.


# Payouts

Send crypto payouts securely. To anyone, anywhere.

<figure><img src="/files/1OA2BWH3Fx7xXvvs6lPd" alt=""><figcaption></figcaption></figure>

Payouts on PayRam let merchants send funds to external wallets across multiple chains in just a few clicks. Whether you’re issuing refunds, employee payroll, or supplier payments, Payouts combine automation, transparency, and control, so you can manage outflows as confidently as you accept inflows.

***

## **Why it matters**

Managing outgoing crypto payments can be complex, especially when you’re dealing with different tokens and chains. PayRam Payouts simplifies this by giving you a unified control panel for all outgoing transactions.

* **Operate with precision:** Define who can create, approve, and execute payouts to avoid unauthorized transfers.
* **Save time and cost**: Use **Payout APIs** to automate payments, reducing manual effort and minimizing network fees.
* **Stay compliant**: Maintain full transaction logs and export-ready records for audits and reconciliation.
* **Expand globally**: Send payouts to partners, users, or wallets across supported chains without needing custom integrations.
* **Reduce risk: B**uilt-in wallet address book ensures you’re sending funds to the right address, every time.

***

## Prerequisites

Before using payouts, make sure your SMTP server is set up. It’s required for sending OTPs as part of the security verification process.

Steps to set up SMTP:

1. Go to your PayRam Dashboard.
2. Navigate to Settings → Integrations → Email Servers.
3. Add your SMTP credentials from your email service provider
4. Save and test the connection to confirm successful configuration.

***

## **How Payram Payout Works**

### Step 1 : Select Payouts

* From the Withdraw menu, select Payouts.

<figure><img src="/files/IcyAF0Nns7k8HVEFg6sV" alt=""><figcaption></figcaption></figure>

### Step 2 : Add Payout Recipient

* Before creating a payout, add the recipient to your **Address Book**. This helps ensure that payouts are sent to the correct wallet address.

<figure><img src="/files/ve7LvEwrLI9FtPerwdcU" alt=""><figcaption></figcaption></figure>

### Step 3 : Address Book

* Click Add New to create a new Address Book.

<figure><img src="/files/VNsKASdeodhm6Nj5r59j" alt=""><figcaption></figcaption></figure>

* A pop-up will appear where you can enter the required details. Once saved, this adds the recipient to your PayRam Address Book.

<figure><img src="/files/M49ajjqEpzdl9wHfQAtg" alt=""><figcaption></figcaption></figure>

* After entering the details, click Continue to Wallet Info. You’ll then be prompted to enter the recipient’s wallet address.

<figure><img src="/files/h53piNgoP4gQytW0XKqg" alt=""><figcaption></figcaption></figure>

* Enter the required details, including the network chain, wallet address, and any optional notes for the recipient.

<figure><img src="/files/SQYTcW140per2m2tYWT3" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**IMPORTANT: Make sure the selected network matches the wallet address. If they belong to different blockchains, the payout will fail and funds may be lost. Always double-check the network before saving the recipient.**
{% endhint %}

* After entering all the details, click Save Recipient. You will be prompted for OTP verification, so make sure your SMTP server is configured in advance.

<figure><img src="/files/PFAHtNPkqBrYZrmMs284" alt=""><figcaption></figcaption></figure>

### Step 4 : Create Payout

* Click the Back arrow to return to the Create Payout page.

<figure><img src="/files/pLDJuSpQUSyRnJEgRBkJ" alt=""><figcaption></figcaption></figure>

* Click Create Payout to start a new payout.
* A pop-up will appear where you can enter the required details, select the recipient, and specify the amount.
* After entering all the details, click Create Payout to proceed.

<figure><img src="/files/Y70COL81ksGcUFHCdqH7" alt=""><figcaption></figcaption></figure>

### Step 5 : Payout Request

* You can view the payout request in your Dashboard.

<figure><img src="/files/5uUPVZj2RbAV74pEFoUs" alt=""><figcaption></figcaption></figure>

* Only Admins can approve payout orders. A payout will not be processed until it has been approved by an Admin.
* To enable OTP delivery for payout approvals, configure your SMTP server in the PayRam dashboard.

{% hint style="info" %} <mark style="color:$warning;">Note</mark> <mark style="color:$success;">**: When a payout is created and sent for approval, the admin receives an OTP for verification. This adds an extra layer of security before the payout is processed.**</mark>
{% endhint %}

* Approvals are required only for payouts created by non-admin roles.

***

## **Common use cases**&#x20;

Payouts are designed to fit real merchant workflows:

* **Vendor & supplier payments:** Pay external wallets in stablecoins or preferred tokens, with automatic confirmation tracking.
* **Employee or contributor compensation:** Handle multi-chain payrolls with approval layers and transparent reporting.
* **Customer refunds:** Issue crypto refunds seamlessly from your dashboard, without manual wallet handling.


# Card-to-Crypto Fiat Onramp

In this section, you’ll understand how Card-to-Crypto Onramp works in PayRam, the supported methods, and what merchants need to enable them.

<figure><img src="/files/6IduSAZJUI53Am4uEn4F" alt=""><figcaption></figcaption></figure>

Card-to-Crypto Onramp or Fiat Onramp allows merchants to accept customer payments in fiat currency while receiving settlements in crypto through PayRam. It removes the need for external exchanges or manual conversions, letting businesses expand their customer base and simplify checkout experiences.

***

### Why it Matters

* Lets merchants reach customers who prefer paying in fiat.
* Enables seamless acceptance of cards, wallets, bank transfer, and local payment methods.
* Automatically settles payments in crypto, keeps all settlements non-custodial.
* Reduces conversion friction and simplifies operations.

***

### PayRam Wallets App

This method allows merchants to accept fiat payments, including card, bank transfer, and more, through PayRam's integrated, self-custody wallet layer, offering a faster setup and a smoother customer experience.&#x20;

Onramp transactions are powered by regulated, third-party fiat-to-crypto providers, with Card-to-Crypto payments now supported via the PayRam Wallet App.

#### How it works for merchants:

* Merchants do not need to complete KYC/KYB to enable this Onramp method.
* Activation is available directly inside the PayRam Dashboard. Activate Card-to-Crypto onramp in seconds!
* Merchants will have the option to sponsor gas fees for customers, reducing friction and improving conversion.

#### How it works for customers:

* A self-custodial PayRam Wallet is automatically generated for the customers, which they can also use for storing, managing, and transferring their digital assets.
* Customers will still be required to complete a basic one-time KYC verification in their first purchase.
* After verification, customers can pay using a card or other supported fiat methods with minimal steps.

#### Commercials and fees:

* PayRam does not apply any additional fees or markups on onramp transactions.
* All onramp related commercials are directly applied by the third-party onramp partners.

#### Checkout experience:

* Onramp transaction funds are deposited directly into the customer's self-custodial PayRam Wallet, after which the customer can use the funds to complete the transaction with the merchant.

#### Supported payment methods:

Customers have access to 175+ payment methods across 190+ countries, with smart routing that matches each user to the best available option based on their region, amount, and payment preference.

Based on their geographic location, customers can complete payments in:&#x20;

* Credit and Debit Card
* Apple Pay
* Google Pay
* Bank Transfer (ACH, SEPA, and local equivalents)
* RevolutPay

***

## How to Enable Card-to-Crypto Onramp via PayRam Wallet

{% hint style="info" %}
**Keep Your Instance Up to Date**

Make sure your PayRam instance is running the latest version before proceeding. You can update it at any time using the update script. See [Script Usage: Update](https://docs.payram.com/script/script-usage#update) for further instructions.
{% endhint %}

{% hint style="info" %}
**Card Payments Require the Base Blockchain**

Card payments and other fiat payment options are currently supported on the Base blockchain only. Before accepting payments via cards, ensure that the Base blockchain is enabled in your PayRam settings.
{% endhint %}

{% stepper %}
{% step %}

### Navigate to Settings

* Log in to your PayRam Dashboard and go to the Settings section.

<figure><img src="/files/xEEuU0GOqrGgqJdVTKUI" alt=""><figcaption></figcaption></figure>

* Now click on the Payment Channels option.

<figure><img src="/files/WsRaYysrw7BAA8aUcU7E" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Activate Cards

* Click on the Activate button beside **Cards** to access the pop-up with more details.

<figure><img src="/files/NSQ2Eb88TYtnuH6unRG9" alt=""><figcaption></figcaption></figure>

* In the pop-up, you'll have to click on Activate to instantly enable the payment method.&#x20;

<figure><img src="/files/YioPobpZJns38b2gqhlH" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Card Payments Require the Base Blockchain**

Card payments and other fiat payment options are currently supported on the Base blockchain only. Before accepting payments via cards, ensure that the Base blockchain is enabled in your PayRam settings.
{% endhint %}
{% endstep %}

{% step %}

### Accept payments

* Go to the Payments menu in the sidebar, click the dropdown, and then select Create Payment Link.
* Create a payment link by entering the customer’s email and the required amount, then click Generate Payment Link.

<figure><img src="/files/UbFKalqqbSl09cTPMwiK" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Pay using PayRam Wallet

* Your customers will now see the Card payment option on the payment page. They just need to click on Cards to use it.

<figure><img src="/files/K7adr1cau4FFjb4mEyr5" alt=""><figcaption></figcaption></figure>

* Customers will have to first setup their self-custody PayRam Wallet. They can use their email address to quickly create one in a few seconds.

<figure><img src="/files/cOWivIYfFyk2obdpuK9J" alt=""><figcaption></figcaption></figure>

* They will be prompted to Add Funds equivalent to the transaction amount.

<figure><img src="/files/q8TqSm1Irqp33UoaNm9Q" alt=""><figcaption></figcaption></figure>

* They can pay using their credit/debit cards or banks or other supported payment methods through the onramp widget, and the crypto will be deposited directly into the customer’s self-custody wallet.

<figure><img src="/files/vHUeibTa6sfvMJTvSfmK" alt=""><figcaption></figcaption></figure>

* They can then use the deposited funds to complete the transaction.

<figure><img src="/files/HQ6rSfwTkFnXQWYCi42x" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/9p36ftacUpM2sfx8QkJC" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/3SgERh3Dz9RwIPmiuC8q" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## Managing Card-to-Crypto Onramp Access for Individual Projects

If you run multiple projects under a single PayRam account, you can control Card-to-Crypto onramp access at the project level. This allows you to enable or disable onramp independently for each project after activating the onramp API.

### How Project-Level Card-to-Crypto Onramp Management Works

Once the Onramp API is activated:

* Onramp is **enabled by default for all projects**
* You must manually disable it for any project where you do not want to offer onramp

### Steps to Enable or Disable Onramp for a Project

{% stepper %}
{% step %}

### Navigate To Settings

Go to Settings and select Account

<figure><img src="/files/xst8QDHcUSxVbnBiHkO2" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Choose Project

Choose the Project you want to manage
{% endstep %}

{% step %}

<figure><img src="/files/I4lQTRERSwLZnlLZCvFO" alt=""><figcaption></figcaption></figure>

### Payment Options

Open the Payment Options tab
{% endstep %}

{% step %}

<figure><img src="/files/UXcc1oumWaDlFsiH0iDA" alt=""><figcaption></figcaption></figure>

### Activate or Deactivate Cards

Toggle Cards on or off for that project

<figure><img src="/files/sxnasvRVeLrIEyCw3w1j" alt=""><figcaption></figcaption></figure>

Your changes apply immediately to the selected project.
{% endstep %}
{% endstepper %}


# Operator Mode

Manage merchants. Earn fees. Stay in control.

<figure><img src="/files/4UoZgGIvceG09T2A2Dzo" alt=""><figcaption></figcaption></figure>

Run PayRam as a platform. Operator Mode lets you onboard merchants, configure chain-level fees, and collect earnings to your own wallet, all from a single dashboard.

***

### Why it matters

* **Multi-merchant management:** Onboard and manage multiple merchants under one operator account without switching between environments.
* **Custom fee structures:** Set your own markup per chain, up to 15%, and update anytime without downtime.
* **Direct fee collection:** All earnings go straight to an external cold wallet you control, without any intermediaries in between.
* **Isolated merchant accounts:** Each merchant runs their own wallet and node configuration, keeping operations clean and independent.
* **Multi-chain ready:** Deploy across EVM chains (Ethereum, Polygon, Base), Tron, and Bitcoin from day one.

***

### Who it's for

Operator Mode is built for anybody, right from payment service providers, crypto infrastructure platforms, and businesses to solopreneurs, weekend developers, and development service providers that want to offer payment facilitation and manage merchant networks at scale.

***

### Getting started

To setup Operator Mode on PayRam, [**visit here**](https://docs.payram.com/operator-mode/operator-mode).


# Introduction

<figure><img src="/files/yc39WEuGnsMJp0Y7bcx1" alt=""><figcaption></figcaption></figure>

* [What is PayRam?](#what-is-payram)
* [How do I get started, and how fast can I go live?](#how-do-i-get-started-and-how-fast-can-i-go-live)
* [What are the minimum server requirements to run PayRam?](#what-are-the-minimum-server-requirements-to-run-payram)
* [Which cryptocurrencies and blockchains does PayRam support?](#which-cryptocurrencies-and-blockchains-does-payram-support)
* [Does PayRam handle fiat currencies (USD, EUR, etc.)?](#does-payram-handle-fiat-currencies-usd-eur-etc)
* [What fees does PayRam charge?](#what-fees-does-payram-charge)
* [Are there any transaction limits?](#are-there-any-transaction-limits)
* [How do I integrate PayRam with my platform?](#how-do-i-integrate-payram-with-my-platform)
* [Is there a sandbox or test mode?](#is-there-a-sandbox-or-test-mode)
* [How secure is PayRam?](#how-secure-is-payram)
* [Does PayRam require KYC/AML?](#does-payram-require-kyc-aml)
* [How are refunds and chargebacks handled?](#how-are-refunds-and-chargebacks-handled)
* [What happens if a customer underpays or overpays?](#what-happens-if-a-customer-underpays-or-overpays)
* [Can I set up recurring subscriptions or billing?](#can-i-set-up-recurring-subscriptions-or-billing)
* [Which industries benefit most from PayRam?](#which-industries-benefit-most-from-payram)
* [How do I migrate from testnet to mainnet?](#how-do-i-migrate-from-testnet-to-mainnet)
* [What support options are available?](#what-support-options-are-available)

#### What is PayRam?

PayRam is a **self-hosted** cryptocurrency payment processor that you deploy and run on your own servers—no middlemen, no censorship, or any limitations. You retain **full custody** of your funds and infrastructure, gaining total control over your payments flow and data.

***

#### How do I get started, and how fast can I go live?

Getting started is quick and code-light. After installing PayRam via our install script, you simply embed a few lines of API code into your application. You can be **accepting live crypto payments in under an hour**, with no account activation or KYC delays on PayRam’s side.

***

#### What are the minimum server requirements to run PayRam?

For smooth production performance, we **recommend**:

* **4 CPU cores**
* **4 GB RAM**
* **50 GB SSD**

  For very high-volume use cases, scale CPU, memory, and disk accordingly.

***

#### Which cryptocurrencies and blockchains does PayRam support?

PayRam natively supports major cryptos and blockchains, including Bitcoin (BTC), Ethereum (ETH), Tron (TRX), Tether (USDT), USD Coin (USDC) and other EVM-compatible tokens. PayRam is actively adding support for new cryptos and networks.

***

#### Does PayRam handle fiat currencies (USD, EUR, etc.)?

*Not yet.* PayRam currently processes **crypto-only** transactions. Automated crypto-to-fiat on-ramp and direct fiat off-ramp settlement are part of the roadmap.

***

#### What fees does PayRam charge?

PayRam charges a flat 1%-5% fee on settlement, when funds are withdrawn to the cold wallet. PayRam does NOT charge any other fees or subscriptions or has any reserve fund requirements.

***

#### Are there any transaction limits?

No, PayRam does not have any transaction limits. The platform supports **unlimited** transactions and scales with your business. Whether you process 10 transactions or 10,000+ per day, PayRam handles it seamlessly.

***

#### How do I integrate PayRam with my platform?

After installation, you have access to a **RESTful API**, plus SDKs and pre-built connectors. You can integrate via:

* **Payment form embeddables**
* **Payment links & invoices**
* **Webhook callbacks**

  Our docs include sample code for **Shopify**, **WooCommerce**, or any custom web/mobile app.

***

#### Is there a sandbox or test mode?

Yes,a complete **testnet environment for PayRam** is available. Configure PayRam to point at testnet RPC URLs and use our test wallets/faucets to validate your integration before going live.

***

#### How secure is PayRam?

* Self‑custodial control: You maintain exclusive ownership of your private keys at all times.
* On‑premises deployment: All data and funds reside on your infrastructure—never with a third party—dramatically lowering breach risk.
* Automated, trustless consolidation: Intelligent on‑chain sweeps, powered by smart contracts, replace manual fund transfers and slash operational risk.
* Reduced human error: Fully automated workflows streamline processes and eliminate manual intervention.
* Granular access management: Role‑based permissions let you define precisely who can execute sensitive operations.
* Minimized attack surface: A purpose‑built design limits external dependencies and potential vulnerabilities.
* Enterprise‑grade security: From key custody to access controls, PayRam delivers a hardened platform for crypto payment management.

***

#### Does PayRam require KYC/AML?

As a self-hosted solution, PayRam does not impose mandatory KYC requirements by default. However, users have the flexibility to implement their own KYC/AML workflows in accordance with their jurisdictional regulations or customer due diligence policies.

***

#### How are refunds and chargebacks handled?

As there is no automatic on-chain chargeback mechanism, refunds on PayRam must be processed manually through the dashboard or API. The specified crypto amount is returned directly to the customer’s wallet address by the merchant.

***

#### What happens if a customer underpays or overpays?

If a customer underpays, the payment status remains marked as “pending” until the full amount is received. In the case of an overpayment, the excess amount is clearly displayed in the PayRam dashboard, allowing the merchant to either issue a refund or apply the surplus to future invoices, depending on the preferred workflow.

***

#### Can I set up recurring subscriptions or billing?

PayRam natively supports one-off payments and invoices. Subscription functionality is not included by default and would need to be implemented at the application layer or through custom scripting using the available APIs.

***

#### Which industries benefit most from PayRam?

PayRam is suitable for a wide range of industries, with particular relevance for:

* **High-risk** and **censorship-sensitive** sectors such as iGaming, adult services, and gambling
* **Marketplaces** and **e-commerce platforms** aiming for global reach and crypto acceptance
* **Charities** and **NGOs** seeking transparent, on-chain donation tracking
* **Fintech companies** or **payment service providers (PSPs)** looking to offer crypto payments as a white-label solution

***

#### How do I migrate from testnet to mainnet?

1. Update your `config.yaml` from `DEVELOPMENT` to `PRODUCTION`.
2. Swap all testnet RPC URLs and xpubs for their mainnet counterparts.
3. Increase confirmation thresholds (e.g., BTC → 6, ETH → 12).
4. Test on a staging instance, then restart PayRam with new configs.

***

#### What support options are available?

PayRam offers several support options to assist users. For critical issues, 24/7 support is available via email and chat. Comprehensive documentation and code samples can be found at [docs.payram.com](https://docs.payram.com/), providing guidance for setup and integration. Additionally, users can access community forums and GitHub issue tracking for self-service support and peer assistance.

***


# General FAQ's

* [What is PayRam?](#what-is-payram)
* [How do I get started, and how fast can I go live?](#how-do-i-get-started-and-how-fast-can-i-go-live)
* [What are the minimum server requirements to run PayRam?](#what-are-the-minimum-server-requirements-to-run-payram)
* [Which cryptocurrencies and blockchains does PayRam support?](#which-cryptocurrencies-and-blockchains-does-payram-support)
* [Does PayRam handle fiat currencies (USD, EUR, etc.)?](#does-payram-handle-fiat-currencies-usd-eur-etc)
* [What fees does PayRam charge?](#what-fees-does-payram-charge)
* [Are there any transaction limits?](#are-there-any-transaction-limits)
* [How do I integrate PayRam with my platform?](#how-do-i-integrate-payram-with-my-platform)
* [Is there a sandbox or test mode?](#is-there-a-sandbox-or-test-mode)
* [How secure is PayRam?](#how-secure-is-payram)
* [Does PayRam require KYC/AML?](#does-payram-require-kyc-aml)
* [How are refunds and chargebacks handled?](#how-are-refunds-and-chargebacks-handled)
* [What happens if a customer underpays or overpays?](#what-happens-if-a-customer-underpays-or-overpays)
* [Can I set up recurring subscriptions or billing?](#can-i-set-up-recurring-subscriptions-or-billing)
* [Which industries benefit most from PayRam?](#which-industries-benefit-most-from-payram)
* [How do I migrate from testnet to mainnet?](#how-do-i-migrate-from-testnet-to-mainnet)
* [What support options are available?](#what-support-options-are-available)

#### What is PayRam?

PayRam is a **self-hosted** cryptocurrency payment processor that you deploy and run on your own servers—no middlemen, no censorship, or any limitations. You retain **full custody** of your funds and infrastructure, gaining total control over your payments flow and data.

***

#### How do I get started, and how fast can I go live?

Getting started is quick and code-light. After installing PayRam via our install script, you simply embed a few lines of API code into your application. You can be **accepting live crypto payments in under an hour**, with no account activation or KYC delays on PayRam’s side.

***

#### What are the minimum server requirements to run PayRam?

For smooth production performance, we **recommend**:

* **4 CPU cores**
* **4 GB RAM**
* **50 GB SSD**

  For very high-volume use cases, scale CPU, memory, and disk accordingly.

***

#### Which cryptocurrencies and blockchains does PayRam support?

PayRam natively supports major cryptos, including Bitcoin (BTC), Ethereum (ETH), Tron (TRX), Tether (USDT), USD Coin (USDC), Polygon (POL), Coinbase Wrapped Bitcoin (cbBTC) and other EVM-compatible tokens. PayRam currently supports payments on networks, including Ethereum, Base, Polygon, Tron, and Bitcoin. PayRam is actively adding support for new cryptos and networks.

***

#### Does PayRam handle fiat currencies (USD, EUR, etc.)?

*Not yet.* PayRam currently processes **crypto-only** transactions. Automated crypto-to-fiat on-ramp and direct fiat off-ramp settlement are part of the roadmap.

***

#### What fees does PayRam charge?

PayRam charges a flat 1%-5% fee on settlement, when funds are withdrawn to the cold wallet. PayRam does NOT charge any other fees or subscriptions or has any reserve fund requirements.

***

#### Are there any transaction limits?

No, PayRam does not have any transaction limits. The platform supports **unlimited** transactions and scales with your business. Whether you process 10 transactions or 10,000+ per day, PayRam handles it seamlessly.

***

#### How do I integrate PayRam with my platform?

After installation, you have access to a **RESTful API**, plus SDKs and pre-built connectors. You can integrate via:

* **Payment form embeddables**
* **Payment links & invoices**
* **Webhook callbacks**

  Our docs include sample code for **Shopify**, **WooCommerce**, or any custom web/mobile app.

***

#### Is there a sandbox or test mode?

Yes, a complete **testnet environment for PayRam** is available. Configure PayRam to point at testnet RPC URLs and use our test wallets/faucets to validate your integration before going live.

***

#### How secure is PayRam?

* Self‑custodial control: You maintain exclusive ownership of your private keys at all times.
* On‑premises deployment: All data and funds reside on your infrastructure—never with a third party—dramatically lowering breach risk.
* Automated, trustless consolidation: Intelligent on‑chain sweeps, powered by smart contracts, replace manual fund transfers and slash operational risk.
* Reduced human error: Fully automated workflows streamline processes and eliminate manual intervention.
* Granular access management: Role‑based permissions let you define precisely who can execute sensitive operations.
* Minimized attack surface: A purpose‑built design limits external dependencies and potential vulnerabilities.
* Enterprise‑grade security: From key custody to access controls, PayRam delivers a hardened platform for crypto payment management.

***

#### Does PayRam require KYC/AML?

As a self-hosted solution, PayRam does not impose mandatory KYC requirements by default. However, users have the flexibility to implement their own KYC/AML workflows in accordance with their jurisdictional regulations or customer due diligence policies.

***

#### How are refunds and chargebacks handled?

As there is no automatic on-chain chargeback mechanism, refunds on PayRam must be processed manually through the dashboard or API. The specified crypto amount is returned directly to the customer’s wallet address by the merchant.

***

#### What happens if a customer underpays or overpays?

If a customer underpays, the payment status remains marked as “pending” until the full amount is received. In the case of an overpayment, the excess amount is clearly displayed in the PayRam dashboard, allowing the merchant to either issue a refund or apply the surplus to future invoices, depending on the preferred workflow.

***

#### Can I set up recurring subscriptions or billing?

PayRam natively supports one-off payments and invoices. Subscription functionality is not included by default and would need to be implemented at the application layer or through custom scripting using the available APIs.

***

#### Which industries benefit most from PayRam?

PayRam is suitable for a wide range of industries, with particular relevance for:

* **High-risk** and **censorship-sensitive** sectors such as iGaming, adult services, and gambling
* **Marketplaces** and **e-commerce platforms** aiming for global reach and crypto acceptance
* **Charities** and **NGOs** seeking transparent, on-chain donation tracking
* **Fintech companies** or **payment service providers (PSPs)** looking to offer crypto payments as a white-label solution

***

#### How do I migrate from testnet to mainnet?

1. Update your `config.yaml` from `DEVELOPMENT` to `PRODUCTION`.
2. Swap all testnet RPC URLs and xpubs for their mainnet counterparts.
3. Increase confirmation thresholds (e.g., BTC → 6, ETH → 12).
4. Test on a staging instance, then restart PayRam with new configs.

***

#### What support options are available?

PayRam offers several support options to assist users. For critical issues, 24/7 support is available via email and chat. Comprehensive documentation and code samples can be found at [docs.payram.com](https://docs.payram.com/), providing guidance for setup and integration. Additionally, users can access community forums and GitHub issue tracking for self-service support and peer assistance.

***


# Fund Management FAQ's

### Fund Management

* [What is Smart Consolidation (Fund Sweep)?](#what-is-smart-consolidation-fund-sweep)
* [What is a Gas Station in PayRam?](#what-is-smart-consolidation-fund-sweep)

#### What is Smart Consolidation (Fund Sweep)?

**Smart Consolidation** (a.k.a. fund sweep) is PayRam’s on-chain fund aggregation feature. It uses a smart contract (on EVM networks) to automatically collect funds from all your deposit addresses into a single cold wallet you control. To use it, you deploy a “sweep” contract for each supported EVM network, specifying your cold-wallet address as the collector. Then you run two transactions: first **approve** the sweep contract to spend funds (signed with your wallet seed), then **execute** the sweep contract to transfer the balances. These can be done manually or scheduled periodically. The PayRam docs outline these steps – deploy the sweep contract, provide the collector address, approve the contract, and then execute the sweep. In summary, Smart Consolidation automates gathering all crypto from customer deposit addresses into one wallet for easier management.

#### What is a Gas Station in PayRam?

A **Gas Station** in PayRam is a dedicated wallet funded with native cryptocurrency to pay blockchain transaction fees (gas). For example, an ETH Gas Station holds Ether, a TON Gas Station holds TON, etc. While normal deposit processing doesn’t require a Gas Station, features like smart sweeps **do**. Whenever PayRam needs to deploy contracts, approve the sweep contract, or execute a fund sweep, the Gas Station wallet provides the gas fees. If the Gas Station runs out of funds for a given chain, those transactions will fail. Therefore, you should **top up your Gas Station wallet regularly** with enough native tokens. In practice, deploy one Gas Station per protocol and ensure it has enough balance to cover operations like contract deployment, approval, sweeping, withdrawals, or refunds.


# Referral FAQ's

### Referral Campaigns

* [How do I set up a referral campaign?](#how-do-i-set-up-a-referral-campaign)

#### How do I set up a referral campaign?

PayRam’s dashboard provides a **Referral Campaign** workflow (under *Growth → Campaigns*). To set one up:

* **Create a new campaign**: In the PayRam Dashboard, go to *Growth → Campaigns → Create New Campaign*. Enter the campaign name, description, budget, duration, and select which events will trigger rewards. Campaigns are tied to a specific project and have their own event rules. Save the campaign – PayRam will generate an `event_key` (a unique identifier for your trigger event).
* **Embed referral dashboard**: Use PayRam’s iframe-based referral dashboard on your site. Your backend must call PayRam’s referral-auth API to get an iframe URL, then set an `<iframe>` on your page with that URL. This allows users to log in to the referral dashboard.
* **Link referrers and referees**: When a new user signs up with a referral code (from a referrer), call the PayRam **Referee** API. Send a POST to `/api/v1/referral/referee` with your API key and a JSON body including the referee’s email, the referrer’s code, and a unique referenceID. This links the new user to their referrer in PayRam’s system.
* **Trigger events**: When a configured action happens (e.g. first purchase), call the **Event Log** API. Send a POST to `/api/v1/referral/event-log` with your API key and JSON containing `eventKey` (the key from campaign setup), the referee’s referenceID, and optionally `amount`. This notifies PayRam of the event so it can apply rewards.

By following these steps (create campaign, embed the widget, link users, and log events), you fully integrate PayRam’s referral/affiliate system.


# Customization FAQ's

### Customization & Access Control

* [How do I customize the payment page’s branding?](#how-do-i-customize-the-payment-pages-branding)
* [How do I manage user roles and permissions?](#how-do-i-manage-user-roles-and-permissions)

#### How do I customize the payment page’s branding?

PayRam allows basic branding of the checkout page. In the **project settings** (during setup), you can upload your logo image and set a primary color (hex code) for the theme. These are stored in the project configuration (for example, the JSON `logoPath` and `brandColor` fields). You can also enter custom CSS in the advanced branding section to further tweak styles. In short: specify your logo and colors in the PayRam dashboard (Getting Started → Step 2), and PayRam will use those values on the hosted payment page to match your brand.

#### How do I manage user roles and permissions?

When you first set up PayRam, the initial account you create is the **root (admin)** user. From there, in the Dashboard under *Team*, you can add additional users with designated roles (such as Developer, Finance, Read-Only, etc.) to control access. Each user will have permissions based on their role. Separately, when you generate project API keys, you specify a role name (e.g. `platform_admin`) for that key. In your code, use these API keys (keeping them secret) for backend calls; each key inherits the permissions of its role. In summary, use the Team interface to manage login users and use the project-API-key roles to manage programmatic access.


# Debug FAQ's

### Security & Troubleshooting

* [What security best practices does PayRam recommend?](#what-security-best-practices-does-payram-recommend)
* [How can I debug payment or configuration issues?](#how-can-i-debug-payment-or-configuration-issues)
* [How do I migrate from testnet to mainnet?](#how-do-i-migrate-from-testnet-to-mainnet)

#### What security best practices does PayRam recommend?

Security is paramount. Key practices include: always run PayRam over **HTTPS/TLS** (so API calls and UI are encrypted); keep your PayRam API keys, wallet mnemonics, and xpubs out of source control and never expose them publicly; validate incoming webhooks by checking the `API-Key` header or source IP to ensure they’re really from PayRam; back up your PayRam database (`payram.db`) and mnemonic seed securely (encrypted, offline); and monitor server logs for anomalies. If a key or credential is compromised, rotate it immediately. These measures help keep your self-hosted PayRam instance safe from unauthorized access or data loss.

#### How can I debug payment or configuration issues?

If you encounter problems, PayRam provides several tools:

* **Logs**: Check the console output where you ran the install script and the runtime logs from the PayRam service. They often report errors or warnings about missing config values or failed transactions.
* **Testnets**: Use testnets (Ethereum Sepolia, Bitcoin Testnet, Tron Nile) and faucets to simulate deposits without real crypto. This helps you verify that addresses, confirmations, and webhooks are working.
* **Webhook testing**: Temporarily log incoming requests on your webhook endpoint (e.g. using a tool like RequestBin or local logging) to ensure PayRam is sending them and your server is responding correctly.
* **Configuration**: Double-check `config.yaml` for typos (YAML is sensitive to formatting). Confirm that RPC endpoints work by testing them separately. For address issues, ensure your xpub is correctly pasted. Sometimes simply restarting PayRam after a config change resolves issues. In general, use the above aids to trace where a payment is (in PayRam’s database vs on-chain vs your system).

#### How do I migrate from testnet to mainnet?

(Repeat of “migrate from testnet to mainnet” for visibility.) Update `config.yaml` for **production**: switch `server: "PRODUCTION"`, replace test RPC endpoints with mainnet endpoints (Ethereum mainnet RPC, Bitcoin mainnet node, Tron mainnet), and use mainnet xpubs instead of testnet ones. Also raise confirmation requirements (e.g. Bitcoin ≥6, Ethereum ≥12). Test these settings on a staging instance first. Once confirmed, point your DNS to the new server (or switch environment flag) and restart PayRam. This moves PayRam from test to live mode safely.

**Sources:** PayRam installation and configuration guides.


# Glossary

Understanding key terms

### <mark style="color:$primary;">**Cold wallet**</mark>

A secure blockchain wallet used for storing funds offline or in a highly secure environment. Unlike deposit wallets, which are generated for receiving payments from customers, the cold wallet serves as the merchant’s main storage address where funds are ultimately consolidated. Cold wallets are not directly exposed to customers, reducing the risk of unauthorized access and improving overall fund security.

### <mark style="color:$primary;">**Deposit wallet**</mark>

A blockchain address where customers send their payments. Each customer is assigned a unique deposit wallet address, ensuring that their transactions can be tracked and managed individually. All deposit wallets are derived from the merchant’s master account.

### <mark style="color:$primary;">Hot Wallet</mark>

A wallet used to cover transaction fees (gas) when sweeping funds from deposit wallets to the cold wallet. Because blockchain transactions require gas, the hot wallet holds the funds needed to pay these fees and enable transfers during the sweep process. Hot wallets are EOA (Externally Owned Account) wallets. Always maintain a minimum balance in the hot wallet; otherwise, sweep operations will fail.

### <mark style="color:$primary;">**Master account**</mark>

The merchant’s primary blockchain account for a network family (for example, one master account for all EVM-compatible networks). All customer deposit wallet addresses are generated from this account, ensuring that payment addresses remain linked to a single, consistent source. The master account is also used to deploy the sweep contract and enables accurate tracking, management, and association of payments under the merchant’s account.

### <mark style="color:$primary;">**SmartSweep**</mark>

This feature automatically moves funds from customer deposit wallets to your main wallet. This reduces manual transfers and consolidates funds efficiently. The goal is to simplify daily operations while keeping security a priority. For most blockchains, SmartSweep uses a family of smart contracts. This design ensures you don’t have to expose keys to sweep funds, while PayRam manages the orchestration.

### <mark style="color:$primary;">**Sweep contract**</mark>

A smart contract that the merchant sets up using their master account. When customers make payments, the money first goes into deposit wallets that are created from the master account. Over time, the merchant may have many deposit wallets, one for each customer or payment. Instead of moving the money from each deposit wallet manually, the sweep contract does it automatically. It collects the funds from all deposit wallets and sends them to the merchant’s cold wallet. These setup also eliminates the need to keep private keys on the server which is very unique to PayRam, adding a difficult layer of security.


# Supported Networks and Coins

<table><thead><tr><th>Network</th><th>Coin</th><th data-hidden></th></tr></thead><tbody><tr><td>Ethereum</td><td>ETH, USDT, USDC, PYUSD</td><td></td></tr><tr><td>Base</td><td>ETH, USDC, cbBTC</td><td></td></tr><tr><td>Polygon</td><td>USDC, USDT, POL</td><td></td></tr><tr><td>Tron</td><td>TRX, USDT</td><td></td></tr><tr><td>Bitcoin</td><td>BTC</td><td></td></tr></tbody></table>


# Important Links

* Website: <https://payram.com/>
* X (formerly Twitter): <https://x.com/PayRamApp>
* LinkedIn: <https://www.linkedin.com/company/payram-app>
* YouTube: <https://www.youtube.com/@payramapp>


# Change Log

These release notes document changes and updates to the API and functionalities. Ensure you are using the latest Docker file for optimal performance.

***

### For the latest PayRam Releases, you can also refer to <https://www.payram.com/releases>

***

## PayRam — What's New

> <mark style="color:purple;">**45 Releases**</mark> | <mark style="color:$primary;">**454 Changes Shipped**</mark>

***

### June 19, 2026

#### PayRam Frontend `v1.2.0`

**UI**

* Renamed the Payments "Cards" tab to "PayRam Wallet" for clearer navigation

**Fixed**

* Checkout polish: removed stray horizontal and vertical scrollbars, and the payment-options list no longer flickers while it loads

***

### June 18, 2026

#### PayRam Core `v3.1.4`

**Added**

* Set payout rules per project: minimum amounts, approval policies, and auto-approval now apply per project, including payouts you create from the dashboard
* Per-project sweep settings let each project consolidate balances its own way, and deposit addresses now deploy automatically the moment funds arrive
* API keys are now encrypted at rest and matched by a secure hash, a stronger lock on your gateway credentials

**Changed**

* Creating a payout is now near-instant: notifications send in the background instead of holding up the response by about ten seconds

**Fixed**

* Stuck EVM withdrawals recover automatically, and payout errors now come back clear and specific instead of a generic failure
* Shared deposit wallets can deploy through any of a project's mapped hot wallets, so setup keeps working in mixed configurations

#### PayRam Frontend `v1.1.3`

**Added**

* New per-project controls in the dashboard: a Payout Limits tab and a Sweep Settings tab with inline editing, tune the rules for each project without leaving the page

**Changed**

* Creating payouts is smoother: a loading state on the Create Payout button, inline error messages, and the list refreshes automatically after you create or approve one

**UI**

* Checkout payment options are reordered for faster selection, with a clearer label for local payment methods

**Fixed**

* Reliability polish: accessibility labels, fewer stale-data flickers, and BTC correctly hidden from project sweep settings

#### PayRam Wallet Backend `v1.0.3`

**Changed**

* Card on-ramps now pick the best provider per country, with improved coverage and routing for the US, Canada, and Mexico

***

### June 12, 2026

#### PayRam Core `v3.1.2`

**Added**

* PayRam now accepts PYUSD (PayPal's USD stablecoin) on Ethereum, joining USDT and USDC. New and existing installs pick it up automatically on upgrade, no migration needed
* Merchant webhooks are now signed with HMAC-SHA256, so your store can cryptographically verify every payment notification really came from your gateway. Powers the new WooCommerce plugin and any custom integration
* Payment webhooks now carry the full on-chain deposit details: paying address, transaction hash, deposit address, and block number, so you can reconcile and display payments without a second lookup

**Changed**

* Operators get safer economics: project-to-wallet mappings are now gated on operator-fee compatibility, and incompatible wallets are flagged before they cause a problem
* The checkout now surfaces a merchant's most-used and recently-used coins as a quick-pay shortlist, so repeat customers reach their preferred token faster

**Fixed**

* Merchant payout reads are restored for project API keys, and project names can now contain colons

#### PayRam Frontend `v1.1.1`

**Added**

* PYUSD shows up everywhere it should: its own icon at checkout and full visibility in the dashboard graphs alongside your other currencies
* Card payments are easier to set up: a clear banner and nav nudge now guide you when card is switched on but the wallet it needs isn't ready yet
* Checkout return links now carry the payment reference and invoice id back to your store, so post-payment redirects land on the right order every time

**Changed**

* When picking a wallet for a project, incompatible options are now clearly flagged instead of failing silently later

**UI**

* The customer payment screen has been rebuilt from the ground up: a calmer, clearer checkout with a connected list of payment options, adaptive coin logos, refined bottom-sheets, and a sharper typographic hierarchy

**Fixed**

* Steadier live payment status on the checkout screen, with clearer connection diagnostics when a network blip happens
* The deposit-wallet family dropdown no longer gets clipped inside scrollable tables, and the sweep queue now shows a friendly all-caught-up state when there's nothing to do

#### PayRam MCP Server `v1.2.0`

**Added**

* New self-healing tools: AI agents can now run a staged health check on your PayRam node, get a plain-language verdict, and restart a stuck worker, turning "something's wrong" into "here's what to do" automatically
* A guided diagnosis assistant walks an agent (or you) through pinpointing setup and connection issues, with actionable hints surfaced directly from the API

**Changed**

* A single front-door guide for AI agents makes PayRam discoverable and integrable in one read, with the live tool reference kept in lockstep with the latest Core API

***

### June 4, 2026

#### PayRam Core `v3.0.5`

**Changed**

* PayRam now serves its API from the same origin as your dashboard, with the web-server config bundled in — a simpler, more reliable setup behind reverse proxies and custom domains. Existing HTTPS deployments on port 8443 keep working via backward compatibility
* The connection setting is now a clearer "Site URL," and changes are restricted to the root operator while admins retain view access

**Fixed**

* Tron now handles larger blocks reliably by allowing bigger node responses

#### PayRam Frontend `v1.0.4`

**UI**

* Renamed "Backend URL" to "Site URL" and redesigned the setting with an HTTPS toggle — view-only for admins, editable only by the root operator

**Fixed**

* Payment pages now always resolve to the correct same-origin address, eliminating malformed payment links

***

### June 3, 2026

#### PayRam Core `v3.0.3`

**Added**

* Bitcoin can now connect to remote and public HTTPS RPC nodes, so you can point your deployment at a managed node provider instead of running your own. Connection handling is hardened against IPv6 addresses, partial credentials, and malformed URLs
* Setup progress is now tracked on the server, so the onboarding wizard survives reloads and device switches, can be dismissed, and adapts to your role

**Changed**

* PayRam now waives its protocol fee on Bitcoin in production — 0% on BTC payments
* Bitcoin node selection now prefers healthy public nodes and automatically drops unreachable private ones, with a free public testnet node seeded out of the box

**Fixed**

* Deployment reliability: the web server now starts cleanly even when its logs are mounted to a separate volume

#### PayRam Frontend `v1.0.3`

**Added**

* Customers can now pay with a card at checkout, and every deposit method is organized into clean, consistent bottom-sheets
* The merchant setup wizard is now resumable — pick up exactly where you left off on any device — with a redesigned, clearer role-selection step

**UI**

* Redesigned customer payment page: clearer deposit options, a preferred-currency setting, and the merchant's store logo with an auto-generated fallback when none is set

**Fixed**

* Public payment links now resolve the correct merchant backend reliably, instead of occasionally falling back to the setup screen
* The operator fund-collector view now correctly displays the Bitcoin collector wallet

***

### May 27, 2026

#### PayRam Core `v3.0.0`

**Added**

* Operator Mode — run a payment gateway for other merchants without ever taking custody of their funds. Set a markup fee per chain (with per-project overrides) paid out to your own collector address automatically, on-chain, every time a merchant's funds are swept
* On-chain fee engine: in a single sweep transaction, merchant funds, network fees, and the operator's markup are split and routed separately. The operator's cut is settled directly on-chain at sweep time
* Operator fees work end-to-end across Bitcoin, Ethereum, Base, and Polygon, including BTC sweeps that settle the fee through a dedicated sweep contract
* Fee collectors with encrypted master wallets, per-chain defaults, and per-project overrides
* Operator analytics dashboard endpoint — live earnings and per-project performance served from a single call, with websocket push on every fee settlement
* Setup Mode: every install now identifies as either Operator or Merchant. Existing deployments are auto-migrated to Merchant mode on upgrade
* Deposit-wallet inspector with per-family metrics and per-address sweep error reporting
* Smart-contract deposit-wallet flow with an explicit project picker and on-chain validation; deterministic contract addresses across Ethereum, Base, and Polygon via a CreateX factory deployment

**Changed**

* Explicit project-to-deposit-wallet assignment replaces the old "default wallet" concept — every deposit wallet is now scoped to a specific project
* EVM-family deposit wallets are reused across chains — one address family now serves Ethereum, Base, and Polygon instead of a separate wallet per chain
* Faster cross-chain deposit detection via a universal calldata address scanner, plus an upgrade to Go 1.26.3 with all dependencies refreshed

**Fixed**

* Native-deposit addresses stored with inconsistent letter casing no longer break the deposit pipeline — fixes deposits that could get stuck at pending
* The accounting worker is now panic-proof: nil-guards keep the goroutines alive through unexpected data instead of silently dying, and zero-amount sweep legs no longer create noise rows

#### PayRam Frontend `v1.0.0`

**Added**

* Operator onboarding wizard — pick your role, name your gateway, set per-chain markup fees, assign team members, and land on your operator dashboard in a few guided steps
* Operator dashboard and Analytics wired to live data with websocket hot-refresh — earnings and project activity update in place, no manual reload
* On-chain fee and collector edit dialog — change your markup percentage or payout address and have it written to the contract directly, with clear pending-state feedback while the transaction confirms
* Fee management surfaces: per-blockchain defaults, per-project overrides, and bulk "set fee collector" actions, all driven from URL-addressable tabs
* Deposit-wallet inspector — copy-on-click addresses, explorer links, a collapsible metrics band, and operator fee rows surfaced in sweep history

**Changed**

* ETH is now available on PayRam Wallet for Base merchants

**UI**

* Three-tone sweep error banners that clearly distinguish recoverable, queued, and infrastructure issues — plus a mobile usability pass across all operator and sweep screens

**Fixed**

* Tron WalletConnect popup no longer fires unexpectedly when a deposit wallet loads

#### PayRam Smart Contracts — FundSweeper V2

**Added**

* FundSweeper V2 introduces a second fee tier that pays the operator's markup directly to their collector address at sweep time — in the same transaction that moves merchant funds
* A new factory contract deploys sweepers with the operator fee baked in (fee percentage and collector address) through a single initializer, so no per-merchant redeployment is needed
* EIP-7702 account attachment is used for the global fee collector and sweepers, giving deterministic contract addresses across chains
* Verified on Sepolia and covered by a 42-test suite exercising the full operator-fee lifecycle

#### PayRam Wallet Backend `v1.0.2`

**Added**

* ETH transfers are now supported on Base

**Changed**

* Payment amount math preserves full wei precision end-to-end, eliminating rounding drift on transfers
* The card onramp widget now supports per-flow selectable cryptocurrencies, and notification emails gained normalization plus one-click unsubscribe

#### PayRam Wallet (Web) `v1.0.0`

**Added**

* ETH transfer support on Base

**Changed**

* Transfer totals are now consistent across the send, confirm, success, and history screens
* "Max" send uses wei-precise math to avoid transaction simulation reverts, and ETH quotes apply a slippage haircut at fetch time for more accurate amounts

**Fixed**

* The card onramp no longer loops back to the start on a zero-balance checkout

#### PayRam MCP Server `v1.1.0`

**Added**

* New live-data and operations tools, plus a streamlined 3-step payout flow for AI agents settling funds

**Changed**

* Agent-first documentation and a cleaner discovery surface, with templates and specs realigned to the latest PayRam Core API

***

### May 3, 2026

#### PayRam Core `v2.0.5`

**Fixed**

* Withdrawal lookup for individual merchants is working again — a routing regression introduced during Operator Mode scoping has been corrected

#### PayRam Frontend `v0.5.6`

**Fixed**

* Payout history now reloads correctly when you change the date filter, and no longer jumps back to the first tab when results update

***

### May 2, 2026

#### PayRam Core `v2.0.4`

**Fixed**

* Sweep history and filters now show the correct transactions — a misclassification that was mixing non-sweep actions into sweep results has been corrected

#### PayRam Frontend `v0.5.5`

**Fixed**

* The Funds dashboard no longer shows a spurious "hot wallet missing" warning on wallets that are correctly configured

***

### April 30, 2026

#### PayRam Core `v2.0.3`

**Added**

* Sweep routing now uses a refined 4-action classification with estimated completion times calculated in the database — every balance row gets a more precise status and an accurate ETA

**Fixed**

* Concurrent sweeps on the same wallet and chain are now serialized — nonce collisions that caused transactions to fail silently are prevented
* Eligible wallet addresses are deduplicated and balances re-verified on-chain before each sweep runs — prevents duplicate sweeps and protects against stale balance data
* Wallets with a negative balance are now correctly routed to Below Threshold instead of appearing in sweep queues unexpectedly
* Deposit detection now has a three-layer fallback before concluding a transaction doesn't exist — prevents deposits from being incorrectly dropped when a node is lagging
* Edge-case collection events that previously slipped through reconciliation are now caught, keeping all wallets in sync after unusual funding events

#### PayRam Frontend `v0.5.4`

**Added**

* The Funds tab now refreshes automatically every 15 seconds — balances, sweep statuses, and ETAs stay current without a manual reload
* Every balance row now shows a precise status and an estimated time to sweep, powered by the new 4-action classification from the backend

***

### April 29, 2026

#### PayRam Core `v2.0.2`

**Fixed**

* Sweep reconciler now fires immediately when block processing detects a funding-shortfall signal — recoveries start without waiting for the next scheduled cycle
* Reconciler handles temporary node errors without aborting mid-run and caps its lookback window to 10 days for faster incremental scans
* Removed an accidental minimum-balance filter that was silently preventing eligible wallets from being swept
* First-ever sweep on a new project no longer gets stuck — the eligibility check that blocked it is fixed and sweep timestamps are now tracked per project

#### PayRam Frontend `v0.5.3`

**Fixed**

* Transaction History wallet filter now stays in sync with the Funds section — switching wallets in one updates the other
* Wallet filter options on sweep pages now load from the backend, so the available wallets match what you actually have configured

***

### April 28, 2026

#### PayRam Core `v2.0.1`

**Added**

* Sweep observability overhaul — every queued, in-flight, and failed sweep now surfaces a real reason, a real retry time, and the broadcast transaction hash — operators always know exactly why a sweep is waiting and what unblocks it
* Manual sweep trigger endpoint — operators can force-sweep an eligible balance on demand instead of waiting for the next cycle
* Sweep reconciler automatically backfills missed sweeps when an InsufficientBalance signal fires, and recovers orphaned pending deployments at the start of every deployment phase — no more sweeps stuck in limbo after a transient failure
* BTC sweeps are now fully project-scoped — sweep transactions, balance queries, and confirmation flows all respect tenant boundaries on Operator Mode deployments
* Funds consolidation metrics endpoint with a simplified action model — the dashboard can render the entire sweep pipeline from one call
* `GET /sweeps` gains filters for network, currency, wallet, and type

**Changed**

* Smart contract wallet deployment now emits a typed network-failure event when the broadcast can't reach a node — the dashboard reacts instead of silently retrying

**Fixed**

* Sweep eligibility rules now match exactly between the balance API, the sweep engine, and the dashboard's Eligible-For-Sweep tile — totals add up cleanly, no more confusing off-by-one discrepancies
* Deposit-wallet hot-wallet lookups are now scoped by wallet type, preventing cold and hot wallet records from leaking across each other in multi-wallet projects
* Manual-sweep and in-progress rows are correctly counted in the Eligible-For-Sweep tile, and zero-row queries now return an empty array instead of null

#### PayRam Frontend `v0.5.2`

**Added**

* New card-based Transaction History — mobile-friendly, with sweep / fee / collect legs visually distinguished, a transfer-only default toggle, and per-asset filters
* Manual sweep-trigger button on queued asset cards, with a custom confirmation dialog — operators can force a sweep on demand without leaving the dashboard
* "Activate hot wallet" and "Fund hot wallet" CTAs on the relevant blocker rows — every error tells you what to fix, not just that something is wrong
* Connect-app CTA on rows that require a manual sweep, plus a wallet-inactive section and default-cold-wallet blocker for clear remediation paths
* WalletConnect project ID now sourced per-merchant from the backend — merchants configure once and the right session opens on every checkout

**UI**

* Funds consolidation page redesigned with a sectioned layout, metrics band, filters, anchors, and an in-progress card — every sweep stage is one click away
* Deposit page redesigned for merchant checkouts: accordion payment methods, official provider icons, smart network switching, inline fiat rates, and a two-audience flow that splits crypto and card cleanly
* Prominent next-sweep badge with a focused pulse only when a sweep is within the hour, queued cards collapsed by default, and breathing room added between tabs and content
* Mobile-responsive asset cards across every Funds section, plus dozens of polish items on dropdowns, pagination, asset names, and avatar stacks

**Fixed**

* Explorer URLs are now read from the blockchains config instead of being hardcoded to testnet bases — links resolve correctly on mainnet deployments
* Sweep triggers now use the row's own project ID instead of the URL param, so cross-project triggers from a shared view always hit the right project
* Native-coin sends now route past the zero-address sentinel correctly, and the coin/network dropdown pushes content instead of overlaying the row
* Funds-band chips show real $0 instead of a dash placeholder, and inactive manual-sweep rows are routed to the blocker view rather than the wallet-inactive section

***

### April 20, 2026

#### PayRam Core `v2.0.0`

**Added**

* Introducing Operator Mode — a ground-up rearchitecture that lets one PayRam instance serve many merchants in complete isolation. [Read the Operator playbook](https://www.payram.com/operator)
* Project-scoped access control across the entire API: members, wallets, withdrawals, sweeps, balances, recipients, webhooks, and API keys all belong to projects — a user only sees what they're assigned to
* Single role per member with a clear role ladder — `project_admin`, `project_lead`, `project_manager`, `project_ops` — each with a curated set of read/write rights scoped to their project
* New `GET /project-permissions` bulk endpoint so dashboards can filter pages, tabs, and actions against what the signed-in user is actually allowed to do — without per-action round-trips
* Recipients now require an explicit project assignment on creation — the address book stays cleanly partitioned between tenants from day one
* Withdrawal approvals, referral payouts, cold-wallet edits, and address-pool reads are all gated by per-project role — operators can delegate safely without handing out the keys

**Changed**

* Webhook permissions split cleanly from project-settings permissions — API-only teammates can ship integrations without touching the rest of the dashboard
* Smart contract wallets are automatically promoted to the project default on confirmation when no default exists — no manual re-tagging after first deploy
* Wallet APIs gain an optional `?include=` filter so clients fetch only what they need; Member and ExternalPlatform preloads are slimmed to essentials
* Docker build is significantly faster with a prebuilt runtime base, build cache mounts, and a proper `.dockerignore` — first-byte deploys in seconds rather than minutes

**Fixed**

* Reverse-proxy trust now covers RFC 1918 private ranges — self-hosted deployments behind nginx or a VPC load balancer no longer see spoofable Host headers
* Admin approval of referral payouts can no longer bypass OTP and accounting entries — every approval path now runs the same verification

#### PayRam Frontend `v0.5.1`

**Added**

* Operator-mode dashboard: sidebar, tabs, and every write action gated by per-project permissions — the UI shows exactly what the signed-in user can do, nothing more, nothing less
* Rich role picker when inviting users — pick by persona (admin / lead / manager / ops), preview the access scope, review the permission chips before sending the invite
* Wallet management, deposit wallets, payouts, address book, and withdrawal screens all filter by project-write permission so collaborators see only what they own
* Recipient creation collects the project assignment up-front, keeping the ledger clean across multi-tenant deployments

**UI**

* Inline project picker built into the breadcrumb — switch tenants without leaving the page you're on
* Create Payment Link promoted to a top-level sidebar CTA above the project selector — the fastest path from login to a fresh payment URL
* Single-role invitation UI with a role badge in the sidebar — the person's role is visible everywhere they appear
* Project-name validation, dropdown polish, breadcrumb icons, mobile user-management layout — dozens of small quality-of-life improvements across the dashboard

**Fixed**

* Stablecoin QR codes no longer encode extra trailing zeros — scanning wallets pre-fill the correct amount on the first try
* Payouts list refreshes immediately after a new one is created and resets to the first page so the fresh entry is always visible

#### PayRam Wallet Backend `v1.2.2`

**Added**

* Multi-app Universal Links and Android assetlinks — the web wallet, v1 mobile, and v2 mobile now deep-link into the correct app from a single signed link
* Web Credential App IDs configuration for passkey flows that span related apps — no re-enrolment when moving between wallet surfaces

#### PayRam Wallet (Web) `v0.4.0`

**Added**

* New `/links/send` route converts EIP-681 `ethereum_uri` deep links into a pre-filled transfer — tap a link anywhere, land on the right send screen with the amount and recipient filled in

**UI**

* Home redesigned with an asset list and correct USD balance labelling — the first thing you see is an accurate picture of what you hold
* Floating action bar and a unified scroll architecture across every screen — consistent body-scroll behaviour across iOS and Android, no more inner scroll-well quirks
* Delete-transfer confirm, pending-CTA polish, and a portal-based Modal primitive so dialogs always render above everything else

**Fixed**

* Add-funds hero no longer goes blank during fiat received / initiated / cancelled states — every transition shows meaningful copy
* Transfer signing guards against zero-amount payloads so wallets never sign an empty operation

#### PayRam Wallet (Mobile) `v2.5.0`

**Added**

* Production-ready: mainnet credentials, real EIP-7702 signing, and the new floating tab bar — the path from development to the App Store is one command
* Apple Sign-In end-to-end, plus a passkey unenrolment fix and delete-transfer support
* Universal deep links: `payram.com/links/send` opens the mobile wallet's transfer flow pre-populated from any shared link

**Changed**

* GA4 analytics via the Measurement Protocol directly — no Firebase SDK dependency, smaller app bundle, cleaner App Privacy declarations

**UI**

* Camera permission for the QR scanner now recovers gracefully — if the user denies access, a single tap jumps to iOS or Android Settings
* Redesigned splash screen: full-bleed green app-shell from cold launch all the way to home — no white flash, no layout jump

**Fixed**

* Strict App Transport Security in production builds, and the insecure RNG fallback has been removed entirely
* Android package split: `com.payram` for production, `com.payram.dev` for development — the two builds coexist on the same device

#### PayRam MCP Server `v1.3.0`

**Added**

* Agent discoverability shipped end-to-end: `robots.txt` with AI-crawler rules, `sitemap.xml`, Link response headers (RFC 8288), and a SEP-1649 server card so MCP-capable clients find PayRam automatically
* Agent skills catalog — 16 standalone skills agents can fetch, cache, and cite, covering setup, authentication, analytics, payments, payouts, webhooks, widget integration, OpenClaw, and a full comparison to other gateways
* New OpenClaw integration skill: the functional how-to for registering `mcp.payram.com` in OpenClaw, Claude Desktop, Cursor, Copilot, or n8n — with a testnet walkthrough and debugging checklist
* New widget integration skill: full script-tag embed reference plus webhook signature verification and idempotency patterns in Express, Next.js, FastAPI, Laravel, and Gin
* Markdown content negotiation on the landing page — agents that request `Accept: text/markdown` get a purpose-built summary; browsers keep seeing the full HTML

**Fixed**

* Server-spec copy corrected across skills and docs — the minimum is 2 CPU / 6 GB RAM / 15 GB+ disk, dropping inflated values that had drifted over time

***

### April 10, 2026

#### **PayRam Core `v1.9.7`**

**Added**

* Smart contract wallets (EIP-7702 / EIP-4337) can now be used to update cold wallets

**Fixed**

* Batch address identification restored for TRX — addresses are detected reliably again
* Default wallet handling now correctly scoped to the specific blockchain instead of clearing globally

#### **PayRam Frontend `v0.4.5`**

**Changed**

* Update Manager is back — now includes an installation and troubleshooting guide
* Wallet management now validates connections before showing wallets as ready

**Fixed**

* BTC deposit wallets no longer require a hot wallet to be considered setup-ready

***

### April 7, 2026

#### **PayRam Core `v1.9.5`**

**Added**

* Per-project access control: members, wallets, withdrawals, sweeps, balances, and recipients are now scoped to projects so users only see what they own
* New `project_admin` role with the same permissions as project lead — can assign and revoke roles
* Hot wallets are now bound to projects with first-class project management and ownership rules
* Unified withdrawal endpoint with pagination — single API for all withdrawal listings
* Recipients API now supports pagination
* Webhook delivery logs persisted with backfill — full audit trail of every webhook attempt

**UI**

* Cleaner `All Time` / `forever` option labels in date filters

**Fixed**

* Smart contract wallets can now deploy through wrapper contracts (Safe, account abstraction, EIP-7702)
* Activity log entries scoped by user access — internal members and customers no longer leak across projects
* Nginx SSL termination now supported without requiring an SSL cert path on the PayRam container
* Reverse proxy headers (`X-Forwarded-Host`, `X-Forwarded-*`) are only trusted from known proxy IPs to prevent host header injection
* Analytics count queries now respect the active date filter

#### **PayRam Frontend `v0.4.4`**

**Added**

* User management, payouts, address book, withdrawals, and wallets all now scoped per project — switch projects to filter what you see
* Payouts table shows the project column and payout creation requires picking a project
* Server-side pagination on payouts, address book, and withdrawal lists — handles large datasets without lag

**Changed**

* MFA and password management consolidated into a single Account Security settings page
* Update Manager temporarily marked as `Coming Soon` while we polish it

**UI**

* Hot wallet page redesigned with project management and a first-time onboarding flow
* Wallet detail page redesigned with a new assets section
* Payments page redesigned with a two-column checkout layout

**Fixed**

* Funds tab now shows an empty state instead of a blank screen when there's no data
* Dropdowns now render via portal so they're never clipped by parent containers
* Old-password error message and visibility toggle fixed in the Change Password dialog
* Sweep history no longer logs spurious errors when requests are cancelled mid-flight

#### PayRam Payments App **`v1.2.1`**

**Added**

* Checkout now pre-fills the buyer's local currency based on geolocation

**Changed**

* Card onramp purchases now enforce a $12 minimum to comply with provider rules

**Fixed**

* Fixed nil-pointer crashes when updating transaction hashes for payments without a sender op hash
* Authentication tokens no longer incorrectly appear expired due to a token-parsing bug
* EIP-7702 delegation user operations are correctly skipped during sponsorship parsing
* Token balance locks and unlocks guarded against zero-value sponsorship operations
* Geolocation database now bundled with the Docker image so country detection works out of the box

#### PayRam MCP Server **`v1.2.1`**

**Fixed**

* Switched to a per-request MCP connection pattern to eliminate a memory leak on serverless deployments

***

### April 1, 2026

#### **PayRam Core `v1.9.4`**

**Added**

* Clearer error codes when the blockchain needs a moment to catch up (409 with retry guidance)

**Fixed**

* Deposit wallet deployment now auto-retries when the network is briefly out of sync

#### **PayRam Frontend `v0.4.3`**

**UI**

* Better error messages during wallet registration — explains what's happening and what to do

**Fixed**

* Wallet setup shows progress spinner, countdown timer, and retry button instead of failing silently
* Payment links now work correctly — fixed broken wallet URLs

#### **PayRam Business App `v1.0.0`**

**Added**

* PayRam Business merchant app now available on [Google Play](https://play.google.com/store/apps/details?id=com.payram.business\&hl=en_US) and the [App Store](https://apps.apple.com/us/app/payram-business-merchant-app/id6759707719)

***

### March 25, 2026

#### PayRam Core `v1.9.3`

**Fixed**

* BTC transaction receipt now surfaces real errors (timeout, auth failure, rate limit) instead of silently marking transactions as not found
* Deposit verification correctly distinguishes missing transactions from transient RPC failures — nil receipts are retried on next cycle
* Removed exponential retry backoff from confirming sweeps — now processed every cycle without age-based delays
* Refresh token endpoint returns correct HTTP status codes (401 for invalid JWT, 404 for deleted members) instead of generic 500
* Database errors in token refresh no longer collapse into incorrect 404 — real DB failures propagate as 500

#### PayRam Frontend `v0.4.2`

**Added**

* System Updater page with version management, upgrade planning, and real-time upgrade monitoring
* Debug panel wallet URL override for testing payments page against custom backends

**Fixed**

* Remove authenticated config call from public payments page and add checkout suffix to wallet URLs
* Improve error handling and type safety in updater API functions
* Normalize upgrade failure state check and fix import paths in updater module

#### PayRam MCP Server `v1.2.0`

**Fixed**

* Auto-discover platform ID so agents no longer need to ask for it during setup

***

### March 21, 2026

#### PayRam MCP Server `v1.2.0`

**Added**

* MCP server discovery tool for agents to find and connect to PayRam instances
* Authentication skill for secure agent access to PayRam APIs
* Authenticated data-fetching MCP tools for merchant dashboards

**Changed**

* Rewritten analytics skill with direct API access for real-time data

***

### March 20, 2026

#### PayRam Core `v1.9.2`

**Added**

* Batch BTC DB queries — reduces \~22,000 queries per block down to 2 using two-pass batch pattern for UTXO and sweep detection

**Changed**

* RPC pool composite node identity uses URL + credential hash as key — fixes credential loss for same-URL nodes with different API keys
* Existing RPC nodes re-hashed via migration for consistency with new hashing scheme
* Processor shutdown changed to graceful termination via context cancellation

**Fixed**

* BTC UTXO batch fallback — on DB error, falls back to per-item lookup instead of dropping sweep detections
* `Stop()` now unblocks correctly by listening on both context and stop channel
* BTC unauthenticated RPC nodes filtered out for remote connections
* Empty batch returns consistent empty slice instead of nil for JSON safety

***

### March 19, 2026

#### PayRam Frontend `v0.4.1`

**Fixed**

* Remove authenticated config API call from public payments page to prevent auth errors
* Use plain axios (unauthenticated) for `reportMissedDeposit` on public payments page

#### PayRam Frontend `v0.4.0`

**Added**

* Default configuration integration for dynamic backend and wallet URLs
* Unified page headers with `PageHeader` component across all screens
* Sidebar logo now clickable to navigate home
* RPC pool frontend alignment with updated backend API changes

**UI**

* Fixed alert bar transparency in page headers
* UI polish for payment links, chart legends, alert bar, and sponsorship copy
* Addressed loading flash, overflow, and accessibility issues in RPC pool

**Fixed**

* Guard against null analytics cells crashing dashboard on login
* Fix `defaultValue` sync issue in RPC pool settings
* Update `PAYMENTS_APP_CONFIG` with new backend and web wallet URLs

#### PayRam Core `v1.9.1`

**Fixed**

* BTC batch size reduced to 2 for per-block height updates to improve stability

#### PayRam Core `v1.9.0`

**Added**

* RPC connection pool with health-based routing, priority ranking, and 60 seed nodes across all supported chains
* RPC node management APIs — create, update, delete, and per-node live connection testing
* ARM64 Docker build and publish workflow for multi-platform image support
* Automatic releases and tag builds via CI pipeline
* Computed `webhookStatus` field in payment search results
* Deposit sponsorship retry timeout configuration
* `CONFIRMING` payment status exposed in API; analytics tightened to processed-only deposits
* Computed `priority` field in RPCNode API response
* Hash-based RPC node gatekeeper (`ConnectionHash`) to prevent duplicate node registration
* BTC fallback node support in RPC pool

**Changed**

* Centralized `BLOCKCHAIN_NETWORK_TYPE` environment reads into `models.GetNetworkType()`
* Removed redundant `network_type` column from `rpc_nodes` table
* Chain ID retrieval refactored — TRX JSON-RPC probe separated into a dedicated function
* Seeder now uses `OnConflict{DoNothing}` for idempotency; syncs non-key fields on duplicate key
* Batch address checking for ETH/BASE blocks for improved performance
* Chain ID cached via `sync.Once` for Received events matching

**Fixed**

* TRX chain ID retrieval — enhanced error handling for unsupported endpoints and improved JSON-RPC probe
* TRX multi API key support — per-node API key used for gRPC calls instead of single client-level key
* TRX URL parsing and pool integration
* TRX timestamp handling
* RPC pool poisoning from "not found" errors — errors no longer incorrectly evict healthy nodes
* RPC pool: removed silent `DefaultFreeNodes` fallback to surface configuration issues explicitly
* Tron node mapping fix — nodes slice initialized to empty instead of nil
* BTC missed deposit flow improved
* BTC testnet connectivity fix
* Sweep retry logic — sweeps no longer incorrectly marked as `not_found` on transient errors
* Dashboard confirming deposits filter accuracy
* `FetchTransactionSponsorship` error handling and logging improvements
* Deposit pipeline stability — prevents silent deposit loss and unsafe height advancement
* External platform blockchain currency approval logic corrected
* Chain ID validation skipped on non-connection RPC node updates
* Signed transaction payload stored for safe re-broadcast on withdrawal failure
* Race condition and goroutine leak fixes in RPC pool management
* Worker restart error handling fixed

#### PayRam Payments App `v1.2.0`

**Added**

* Withdraw transactions support
* Sponsorship calculation endpoint and handler
* Fiat currency and country data integration
* Automated CI/CD release pipeline

#### PayRam Wallet `v2.4.0`

**Changed**

* TypeScript migration and ESLint configuration

**Fixed**

* Improved installation check logic and login redirect on token expiry

***

### March 11, 2026

#### PayRam Frontend `v0.3.1`

**Added**

* Activity Log in settings with breadcrumb navigation
* Missed payments reporting feature with UI components, validation, and error handling
* `excludeActionStatusPairs` filter support for activity logs API and hooks
* `UserMultiSelect` component improvements for activity log filtering

**UI**

* Quick filter style updates with high value filter option removed

**Fixed**

* Update `WEB_WALLET_URL` in `PAYMENTS_APP_CONFIG` to new production URL
* Handle 403 Forbidden separately from 401 to prevent unintended logout
* Update activity log API routes for correctness

#### PayRam Core `v1.8.3`

**Added**

* Polygon listener and broadcast processor registered in system service
* Webhook retry mechanism with exponential backoff — failed webhook deliveries are automatically retried at 30m, 1h, 2h, 4h, 8h, 24h, and 48h intervals before being marked as failed; retry intervals are configurable via system configuration

**Fixed**

* BTC missed deposit flow — improved handling in BTC client
* Sweep approval: temporarily disabled fee transfer and signature broadcasting in run method

#### PayRam Payments App `v1.1.0`

**Changed**

* Country selector and default payment method configuration

**Fixed**

* Card onramp parameter handling improvements

***

### March 5, 2026

#### PayRam Core `v1.8.2`

**Fixed**

* Polygon mainnet RPC connectivity

#### PayRam Payments App `v1.0.0`

**Added**

* Address book service with Ethereum address validation and normalization
* Sponsorship calculation logic with user payable amount computation
* Network fee support for payment calculations

***

### March 1, 2026

#### PayRam Core `v1.8.1`

**Fixed**

* Batch DB query for calldata address checking to fix slow block processing
* Nil guard for `IdentifyOurAddresses` to prevent panic
* Error logging in `identifyOurAddresses` for silent DB failures
* Remove `MaxBlocksPerBatch` cap in polling to eliminate inter-batch sleep
* Prevent genuine deposits from being marked stale on transient RPC errors
* Log error from `MarkStaleConfirmingDeposits` instead of discarding

***

### February 28, 2026

#### PayRam Frontend `v0.3.0`

**Added**

* OnRamp Payments: new `OnrampPaymentsScreen` component integrated into OnrampPayments page
* `ErrorBoundary` for `OnrampPaymentsScreen` to handle rendering errors gracefully
* Confirmation state logic with debug mode and animated transitions for payment flows
* Legacy QR toggle with improved dropdown overflow handling and payment UI enhancements
* PayRam logo embedded in QR codes
* Restart Nodes button in integrations settings
* Refresh icon added to icon components
* Configure MCP nav item with icons in sidebar

**Changed**

* Rolled back Next.js 15 to 14 for stability
* Upgraded CSS and UI dependencies to latest compatible versions
* Cleaned up global CSS, removed redundant configs and duplicate imports
* Refactored icon imports and added new OnrampPayments API

**UI**

* Global design unification — slate color palette, stat strip, settings and payments redesign
* Dashboard design audit — slate color scheme, table redesign, mobile filters, chart theming
* Redesigned dashboard metric cards and updated sidebar color theme
* Mobile hamburger menu, neon green theme, and dashboard polish
* Instant sidebar highlight on navigation click
* Fixed dropdown flash by defaulting to desktop positioning
* Restored credit card icon next to Cards payment method label
* Aligned Crypto icon layout to match Cards payment method
* Settings list layout, sweep-in header and info block reorder

**Fixed**

* Update wallet URL to production domain
* Handle 403 Forbidden separately from 401 to prevent unintended logout
* Prevent automatic logout on transient errors during token refresh
* Improve logic to check availability of USDC token and BASE blockchain in ChannelSelector
* Remove duplicate blockchain case showing incorrect card icons
* Add QR code containers to prevent SVG overflow and fix wallet chain detection race condition
* Revert build optimizations and remove deprecated Next.js 15 config

#### PayRam Core `v1.8.0`

**Added**

* Deposit confirming state support — frontend can now track confirmation progress before deposits are fully confirmed
* Blockchain node validation with mainnet detection (`IsMainnet` method)
* Support for missed deposit webhook approval workflow

**Changed**

* Consolidated webhook processing into single method to prevent duplicate webhook sends
* Improved OnramperPayments API with better pagination, date filtering, and sorting validation
* Refactored blockchain client methods for consistency (`ChainIDUint64` renamed to `GetChainID`)
* Standardized error responses with correct HTTP status codes

**Fixed**

* Context deadline/cancellation handling in blockchain processors
* `EnsureTxConfirmed` polling behavior on `NotFound` status
* TRX sweep transaction field population (Token/From/To/Amount/EventType)
* BTC sweep UTXO processing to include "confirming" status
* Analytics graph colors for New/Recurring metrics
* Payment channel seeder to set Payments App status to active

***

### February 17, 2026

#### PayRam MCP Server `v1.1.0`

**Added**

* Headless setup guide retrieval tool with formatted checklist
* Agent onboarding skill for automated deployment
* Analytics references integrated across all existing skills
* Google Analytics integration on MCP landing page

**Changed**

* Renamed headless setup to agent onboarding for clarity

**UI**

* Integration card layout split into 2-column grid

***

### February 14, 2026

#### PayRam Frontend `v0.2.8`

**Added**

* Added Payments App Channel
* Update Payments Page to support Payments App

**Fixed**

* Payments Page UI fixes

#### PayRam Core `v1.7.9`

**Added**

* Integration of Payments App

***

### February 10, 2026

#### PayRam Frontend `v0.2.7`

**Added**

* Payments page Disclaimer

**Fixed**

* QR code styles and UI improvements
* Recommended token fix
* Dashboard UI fixes

#### PayRam Core `v1.7.8`

**Added**

* Tracking of user activity in the dashboard
* Improved polling logic for the blockchain network processors

***

### January 15, 2026

#### PayRam Frontend `v0.2.6`

**Added**

* Added support for Polygon

**Fixed**

* Recommended token fix in payments page

#### PayRam Core `v1.7.7`

**Added**

* Polygon integration

**Fixed**

* Minor bug fixes

***

### January 6, 2026

#### PayRam Frontend `v0.2.5`

**Fixed**

* Add disclaimer text regarding PayRam software usage and liability
* Add disclaimer text regarding software usage and liability in PaymentScreen

#### PayRam Core `v1.7.6`

**Fixed**

* Bug fix for deposits coming through smart contracts
* Improvement in Tron sweep

***

### December 26, 2025

#### PayRam Frontend `v0.2.4`

**Fixed**

* TRON QR scan fix
* Update precision of amount on scanning QR code on Payments Page
* Filter inactive recipient while creating Payout

#### PayRam Core `v1.7.5`

**Fixed**

* Fix for JWT token based authentication
* Minor fix in Ethereum blockchain listener

***

### December 9, 2025

#### PayRam Frontend `v0.2.3`

**Added**

* Payment channels (TransFi)
* Added support for JWT based authentication

#### PayRam Core `v1.7.4`

**Added**

* JWT token based authentication for all the dashboard APIs
* Swagger documentation for all APIs

***

### November 15, 2025

#### PayRam Core `v1.7.0`

**Added**

* Support for smart contract ETH deposits (e.g. deposits from Coinbase)

***

### November 11, 2025

#### PayRam Frontend `v0.2.2`

**Added**

* Merchant payout: merchant can create a payout request

**Fixed**

* Minor bug fixes and performance improvements

#### PayRam Core `v1.6.9`

**Added**

* APIs for merchant payout (withdrawal)

***

### April 18, 2024

#### PayRam Core `v1.2.6`

**Added**

* APIs to add member
* APIs to add roles
* APIs to add permissions
* APIs to assign roles to members
* API for signing authentication
* APIs to add permissions to roles
* USD adjustment factor of 2%

***

### April 10, 2024

#### PayRam Core `v1.2.5`

**Fixed**

* Removed unwanted log
* Added defer function to avoid nil pointer error

#### PayRam Core `v1.2.4`

**Fixed**

* Added defer to handle abrupt termination of webhook job due to error at network layer

#### PayRam Core `v1.2.3`

**Added**

* Support for notifying customer through email upon BTC credits
* Added necessary logs
* Updated event consumer library

**Fixed**

* Fixed few bugs related to transaction which was causing database locking

***

### April 9, 2024

#### PayRam Core `v1.2.2`

**Added**

* Support to add multiple platforms for a merchant
* Migration to add platform table and updates in the database tables
* Code refactored
* Payment request API no-ok response structured

***

### April 5, 2024

#### PayRam Core `v1.2.1`

**Added**

* Support for Tron listening
* Change in routes and handlers for admin APIs to follow REST API guidelines
* Code refactored

***

### March 29, 2024

#### PayRam Core `v1.2.0`

**Added**

* Feature to send email to merchant on payment request
* Added open source event emitter library
* Added open source event consumer library

***

### March 19, 2024

#### PayRam Core `v1.1.6`

**Added**

* Changed USD amount adjustment factor from 0.988 to 0.984
* Refactored the code
* Removed unwanted comments

***

### March 15, 2024

#### PayRam Core `v1.1.5`

**Added**

* Accounting processor for Bitcoin sweep (withdrawal)
* Updated go.mod and go.sum (showing vulnerability in one of the libraries)

***

### March 14, 2024

#### PayRam Core `v1.1.4`

**Added**

* Audit processor for Bitcoin sweep (withdrawal)
* Changed USD amount adjustment factor from 0.995 to 0.988
* Updated go.mod and go.sum

***

### March 12, 2024

#### PayRam Core `v1.1.3`

**Added**

* Modified withdraw API to take withdraw hash in param rather than JSON params

***

### March 9, 2024

#### PayRam Core `v1.1.2`

**Fixed**

* Removed unwanted webhook call for cancelled payments in create payment request API call

#### PayRam Core `v1.1.1`

**Added**

* Restructured and added few test cases along with makefile
* Separate webhook processor for retrying failed webhooks
* APIs for BTC sweeper (withdrawal)
* Removed unwanted logs
* Migration to copy deposits to `withdra_deposits` table for sweeping
* Migration to mark all cancelled payment requests webhook status to received
* Migration to add two more tables

**Fixed**

* Multiple bug fixes in the code while testing

***

### March 3, 2024

#### PayRam Core `v1.1.0`

**Added**

* Support to pay using Bitcoin
* Bitcoin listener can be run as a separate job
* Created README.md file with installation, configuration and usage details

**Fixed**

* Error in Ether and ERC20 subscription stops abruptly

***

### February 24, 2024

#### PayRam Core `v1.0.8`

**Added**

* Welcome message in the home page

#### PayRam Core `v1.0.7`

**Fixed**

* Small bug fix — added missed return statement in payment request API for all users when it is a pre-prod server

***

### February 23, 2024

#### PayRam Core `v1.0.6`

**Added**

* Added code to copy `created_at` and `updated_at` in DB migration

#### PayRam Core `v1.0.3`

**Fixed**

* Bug fix in URL configuration

#### PayRam Core `v1.0.2`

**Fixed**

* Bug fix

#### PayRam Core `v1.0.1`

**Fixed**

* Bug fix

#### PayRam Core `v1.0.0`

**Added**

* First release with new architecture