Provider Setup Guide

​

Step 1: Signup as a Provider

1. Visit https://app.paycrest.io
2. Sign up as a Provider
3. Complete the registration process

​

Step 2: Initiate KYB Process

• Complete the basic in-app Know-Your-Business (KYB) process
• This process can run concurrently with PSP account setup
• KYB approval is required for production access

​

Step 3: Register with Payment Service Providers (PSPs)

​

Obtain Required Credentials

1. Paycrest Aggregator Credentials (from your Paycrest dashboard)
   • Go to Provider Dashboard → Settings → Payout tab → API Keys
   • Copy:
     • API Key -> set as AGGREGATOR_CLIENT_ID
     • API Secret -> set as AGGREGATOR_SECRET_KEY
2. PSP Credentials (from each PSP portal)
   • For each PSP you enable, collect the required fields (for example: API key, client secret, client assertion, account ID, base URL, callback URL, webhook secret)
   • Use the dashboard PSP setup page to see the exact environment variable keys to populate
   • Add these values to your node .env

​

Step 4: Provision Node Setup

​

Option A: Blockops (Recommended for Low Technical Skills)

• Cost: $10/month
• Simplified setup with Paycrest partnership
• Video setup guide available
• Start here: https://blockops.network
• After setup, obtain the Host Identifier URL from Blockops
• In the app: Settings → Payout tab → Configure Provision Node → Host identifier — paste the URL and click Update

​

Option B: Self-Hosted Deployment (Recommended for Developers)

• Docker installed on your server
• Access to Docker Hub
• Server with internet connectivity
• Minimum 512MB RAM, 1 vCPU (tested on DigitalOcean $5 droplet)

1. Pull the Docker Image

docker pull safaria/riverpod:latest

2. Create Environment Configuration Create a .env file with your configuration:

# Server Config
DEBUG=False
ALLOWED_HOSTS=* # optional; used for trusted proxy configuration
SERVER_HOST=0.0.0.0 # optional (default: 0.0.0.0)
SERVER_PORT=8000 # optional (default: 8000)
CURRENCIES=KES # single currency
# CURRENCIES=NGN,KES,UGX # multiple currencies must be comma-separated
ENVIRONMENT=production # local, staging, production
SERVER_URL=https://your-server-domain-or-ip
EVM_PRIVATE_KEY= # required for onramp settlements

# Aggregator Config
AGGREGATOR_CLIENT_ID=your_paycrest_api_key # Provider Dashboard → Settings → Payout → API Keys
AGGREGATOR_SECRET_KEY=your_paycrest_api_secret # Provider Dashboard → Settings → Payout → API Keys
AGGREGATOR_BASE_URL=https://api.paycrest.io/v2/provider

# PSP Config - Only configure for PSPs you are using
# Example env prefix (Payaza — names shown in dashboard; availability varies by corridor/currency)
PAYAZA_API_KEY=
PAYAZA_BASE_URL=
PAYAZA_TRANSACTION_PIN=
PAYAZA_SUPPORTS_PAYIN=false

Credential Mapping

• AGGREGATOR_CLIENT_ID must be your Paycrest API Key (Settings → Payout → API Keys)
• AGGREGATOR_SECRET_KEY must be your Paycrest API Secret (Settings → Payout → API Keys)
• PSP variables (for example PAYAZA_*, NOMBA_*) use values issued by each PSP. Prefixes match PSPs listed in the dashboard; availability depends on your corridor and currency.

​

EVM_PRIVATE_KEY explained

• What it is: The private key for a dedicated EVM wallet (EOA) used by your provision node.
• When you need it: Required for onramp-related wallet/authorization flows. If you’re running offramp-only operations, you can leave it unset.
• How to generate it: Create a new dedicated EVM wallet (do not reuse a personal wallet) and use that wallet’s private key.
• Security: Treat this as a production secret. Never commit it to git, store it in a secure secret manager or protected .env, and rotate it immediately if exposed.

Important Notes:

• One node works for multiple currencies and can support multiple PSPs (for the same currency)
• Only configure the variables for the PSPs you are using
• If there is no comment on a credential key that has a value, DO NOT change that value
• DO NOT change the value of AGGREGATOR_BASE_URL
• The dashboard PSP setup page shows the exact environment variable keys per PSP
• Retrieve the credential values from each PSP and place them in your .env

3. Start the Service

docker run -d -p 8000:8000 --env-file .env safaria/riverpod:latest

4. Verify Deployment Check the info endpoint to confirm your node is running and reporting provider metadata:

curl http://your-server-ip:8000/info

{
  "status": "success",
  "message": "Provider information",
  "data": {
    "serviceInfo": {
      "currencies": ["KES"],
      "totalPSPs": 1,
      "version": "..."
    }
  }
}

5. Configure Host Identifier

• Take the base URL of your server (e.g., http://your-server-ip:8000)
• In the app: Settings → Payout tab → Configure Provision Node → Host identifier — paste the URL and save
• Go live on your dashboard

• Complete control over infrastructure
• Custom security configurations
• No dependency on third-party services
• Potential cost savings at scale

​

Step 5: Configure Trade Settings

​

Set Rates & Limits

• Floating Rate (Recommended): Allows dynamic pricing with a margin
• Fixed Rate: Static pricing, less flexible

• Set your minimum limit: Set the minimum amount (in USD) you can fulfill
• Set your maximum limit: Set an amount (in USD) based on the available fiat balance in your PSP account

​

Set Settlement Addresses

• Add settlement addresses for all supported networks and tokens
• You can add a settlement address on multiple networks for flexibility

​

Step 6: Node Testing & Launch

​

Testing in Private Mode

• After setting your settlement address(es), test your node in Private mode before going public
• With private mode, you can route a transaction to your node using Noblocks
• To go “LIVE” in Private Mode, switch your node to “Private Mode” on your dashboard

​

Go Live on Public Mode

• Once testing is successful, switch to Public Mode
• Ensure your PSP account is funded and active for transaction fulfillment

​

Onboarding Checklist

​

Technical Requirements

​

Infrastructure Requirements

• 512MB RAM, 1 vCPU (tested on DigitalOcean $5 droplet)
• 50GB+ storage
• Stable internet connection
• Docker installed (for self-hosted deployment)

Note: The minimum requirements are based on real-world testing. A DigitalOcean $5 droplet (512MB RAM, 1 vCPU, 50GB bandwidth) is sufficient for running a Provision Node in production.

​

Docker Installation (For Self-Hosted)

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Logout and login again for docker group changes to take effect
# Or run: newgrp docker

​

Security Best Practices

​

Network Security

• Use firewalls to restrict access
• Implement rate limiting
• Enable DDoS protection
• Use VPN for secure access

​

Key Management

• Store API keys securely
• Rotate keys regularly
• Use environment variables
• Implement key encryption

​

Monitoring and Alerting

• Set up log aggregation
• Configure performance alerts
• Monitor transaction volumes
• Track error rates

​

Troubleshooting

​

Common Issues

# Check logs
docker logs <container_name>

# Verify environment variables
docker run --rm --env-file .env safaria/riverpod:latest echo "Environment loaded"

# Restart container
docker restart <container_name>

# Test API connectivity
curl -X GET https://api.paycrest.io/v2/currencies

# Check container status
docker ps

# Verify environment variables
docker exec <container_name> env | grep DATABASE

​

Getting Help

• Documentation: docs.paycrest.io
• Community: Telegram
• Support: [email protected]
• Blockops Support: Available through Blockops platform

​

When to Contact Support

• KYB remains pending beyond expected review time
• A required PSP is unavailable for your corridor
• Node status remains offline after valid hostIdentifier and .env setup
• API keys under Settings → Payout → API Keys are missing or cannot be copied/rotated

​

Next Steps

1. Test Transactions: Process test transactions to verify functionality
2. Monitor Performance: Track your node’s performance and earnings
3. Scale Up: Consider deploying additional nodes for increased capacity
4. Optimize: Fine-tune pricing and configuration based on market conditions