​
Overview

This quickstart guide will help you integrate Receeco into your POS system and process your first digital receipt. We’ll use our POS agent for the fastest setup.
Prerequisites: Node.js 16+ and access to your POS system’s transaction data

​
Step 1: Install POS Agent

Install our lightweight POS agent that handles the integration: 
npm install -g @receeco/pos-agent
The POS agent is a middleware service that runs alongside your POS system and handles all communication with Receeco’s API, including offline queue management.

​
Step 2: Get Your Merchant Credentials

  1. Sign up at receeco.com/for-merchants
  2. Complete verification with your business details
  3. Copy your Merchant ID from the dashboard
  4. Get your API Key (if available) for enhanced security
Keep your Merchant ID and API Key secure - they identify your business in all transactions

​
Step 3: Initialize the Agent

Initialize the agent with your credentials: 
receeco-pos init --merchant-id=YOUR_MERCHANT_ID --api-key=YOUR_API_KEY
This creates both .env and config.json files with your settings: .env file: 
MERCHANT_ID=grocery-store-001
RECEECO_API_KEY=your-api-key-here
RECEECO_API_URL=https://receeco.com/api
RECEECO_WEB_URL=https://receeco.com
PORT=3001
LOG_LEVEL=info
NODE_ENV=production
config.json: 
{
  "merchantId": "grocery-store-001",
  "apiKey": "your-api-key-here",
  "rececoApiUrl": "https://receeco.com/api",
  "rececoWebUrl": "https://receeco.com",
  "enableOfflineMode": true,
  "printQRCodes": true,
  "port": 3001,
  "logLevel": "info"
}

​
Step 4: Start the Agent

receeco-pos start
The agent will start on http://localhost:3001 and display: 
✅ Receeco POS Agent started
🌐 Listening on http://localhost:3001
📱 Ready to process transactions

​
Step 5: Test Your First Transaction

Use the built-in test command for the easiest verification: 
receeco-pos test
This will automatically generate and send a test transaction, displaying: 
🧪 Testing POS integration...
✅ Test successful!
📱 Short Code: ABC123
🔗 Receipt URL: https://receeco.com/app/receipt/rcpt_abc123_def456

💡 Next Steps:
1. Visit: https://receeco.com/app/scan
2. Enter short code: ABC123
3. View your test receipt!
The test command generates unique data each time to avoid conflicts and includes your actual merchant configuration.

​
Manual Testing (Advanced)

You can also send transactions manually to the agent: 
curl -X POST http://localhost:3001/transactions \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "grocery-store-001",
    "merchantName": "Fresh Foods Market",
    "merchantLogo": "https://example.com/logo.png",
    "accentColor": "#22c55e",
    "items": [
      {
        "name": "Premium Rice (5kg)",
        "quantity": 1,
        "unitPrice": 9500,
        "totalPrice": 9500,
        "sku": "RICE001"
      }
    ],
    "totalAmount": 9500,
    "currency": "NGN",
    "paymentMethod": "card",
    "location": "Main Branch",
    "timestamp": "2024-01-15T14:30:00Z",
    "cashierId": "CASHIER001",
    "terminalId": "TERMINAL001"
  }'

​
Step 6: View the Digital Receipt

The response will include: 
{
  "receiptId": "rcpt_abc123_def456",
  "receiptUrl": "https://receeco.com/app/receipt/rcpt_abc123_def456",
  "qrCodeUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "shortCode": "ABC123",
  "status": "success"
}

QR Code Access

Display the QR code on your POS screen or print it on receipts

Short Code Access

Customers can manually enter the 6-digit code at receeco.com/app/scan

​
Step 7: Test Customer Access

  1. Open receeco.com/app/scan
  2. Enter the short code (e.g., ABC123)
  3. View the digital receipt with all transaction details
Success! You’ve successfully processed your first digital receipt with Receeco

​
Additional CLI Commands

The POS agent includes several helpful commands for management:

​
Next Steps

POS Integration

Learn about the transaction API

Customer Access

Understand receipt retrieval

Offline Mode

Handle network interruptions

Production Setup

Deploy to production environment

​
Troubleshooting

Need help? Contact our support team at developers@receeco.com