Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.receeco.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Receeco integrates with existing POS systems through our lightweight agent that intercepts transaction data and generates digital receipts. This guide covers integration with popular POS systems used in Nigerian businesses.

Cloud-Based POS

Webhook and API integrations

Desktop POS

Print interception and file monitoring

Mobile POS

SDK and plugin integrations

Custom Systems

Direct API integration

​
Cloud-Based Systems

​
Loyverse POS

Loyverse is popular among Nigerian SMEs for its cloud-based approach.
1

Enable Webhooks

In Loyverse dashboard, go to Settings → Integrations → Webhooks
2

Configure Receipt Webhook

Add webhook URL: https://your-domain.com/loyverse-webhookSelect events: receipt.created, receipt.updated
3

Install Receeco Middleware

npm install @receeco/loyverse-adapter
4

Configure Adapter

const { LoyverseAdapter } = require('@receeco/loyverse-adapter');

const adapter = new LoyverseAdapter({
  receeco: {
    merchantId: 'your-merchant-id',
    apiKey: process.env.RECEECO_API_KEY
  },
  loyverse: {
    webhookSecret: process.env.LOYVERSE_WEBHOOK_SECRET
  }
});

app.post('/loyverse-webhook', adapter.handleWebhook);

​
Square POS

Integration with Square’s cloud POS system. 
const { SquareAdapter } = require("@receeco/square-adapter");

const adapter = new SquareAdapter({
  square: {
    accessToken: process.env.SQUARE_ACCESS_TOKEN,
    webhookSignatureKey: process.env.SQUARE_WEBHOOK_KEY,
    environment: "production", // or 'sandbox'
  },
  receeco: {
    merchantId: "your-merchant-id",
  },
});

// Handle Square webhooks
app.post("/square-webhook", adapter.handleWebhook);

​
Desktop Systems

​
Quickteller POS

Popular in Nigerian banks and large retailers.
1

Install Print Monitor

receeco-pos install-print-monitor --system=quickteller
2

Configure Print Interception

The agent monitors the Quickteller print spool and extracts transaction data:
{
  "printMonitor": {
    "enabled": true,
    "spoolPath": "C:\\Quickteller\\Spool",
    "patterns": {
      "receipt": "RECEIPT_*.txt",
      "transaction": "TXN_*.log"
    }
  }
}
3

Data Extraction

Configure field mapping for Quickteller receipt format:
const quicktellerParser = {
  merchantName: /MERCHANT:\s*(.+)/,
  totalAmount: /TOTAL:\s*NGN\s*([\d,]+\.?\d*)/,
  items: /ITEM:\s*(.+)\s*QTY:\s*(\d+)\s*PRICE:\s*NGN\s*([\d,]+\.?\d*)/g,
  transactionDate: /DATE:\s*(\d{2}\/\d{2}\/\d{4}\s*\d{2}:\d{2}:\d{2})/
};

​
Phoenix POS

Common in Nigerian supermarkets and retail chains. 
// Phoenix POS integration via COM interface
const { PhoenixAdapter } = require('@receeco/phoenix-adapter');

const adapter = new PhoenixAdapter({
  phoenix: {
    comPort: 'COM1',
    baudRate: 9600,
    timeout: 5000
  },
  receeco: {
    merchantId: 'supermarket-001'
  }
});

// Listen for transaction events
adapter.on('transaction', async (txnData) => {
  const receipt = await adapter.createReceeco Receipt(txnData);
  console.log('Digital receipt created:', receipt.shortCode);
});

​
Mobile Systems

​
Flutter POS Apps

For custom Flutter-based POS applications: 
// pubspec.yaml
dependencies:
  receeco_flutter: ^1.0.0

// main.dart
import 'package:receeco_flutter/receeco_flutter.dart';

class POSService {
  final ReceecoPOS _receeco = ReceecoPOS(
    merchantId: 'your-merchant-id',
    apiKey: 'your-api-key',
  );

  Future<Receipt> processTransaction(TransactionData data) async {
    try {
      final receipt = await _receeco.createReceipt(data);
      return receipt;
    } catch (e) {
      print('Receipt creation failed: $e');
      rethrow;
    }
  }
}

​
React Native POS

import { ReceecoPOS } from "@receeco/react-native";

const receeco = new ReceecoPOS({
  merchantId: "your-merchant-id",
});

export const POSScreen = () => {
  const [receipt, setReceipt] = useState(null);

  const processTransaction = async (transactionData) => {
    try {
      const result = await receeco.createReceipt(transactionData);
      setReceipt(result);

      // Show QR code to customer
      showQRCode(result.qrCodeUrl);
    } catch (error) {
      Alert.alert("Error", "Failed to create receipt");
    }
  };

  return (
    <View>
      {receipt && <QRCodeDisplay value={receipt.receiptUrl} size={200} />}
    </View>
  );
};

​
Custom Integration

​
Direct API Integration

For custom POS systems, integrate directly with our API: 
class CustomPOSIntegration {
  constructor(merchantId) {
    this.merchantId = merchantId;
    this.apiUrl = "https://receeco.com/api/trpc";
  }

  async onTransactionComplete(transactionData) {
    // Generate unique identifiers
    const token = this.generateToken();
    const shortCode = this.generateShortCode();

    // Prepare receipt data
    const receiptData = {
      token,
      short_code: shortCode,
      merchant_string_id: this.merchantId,
      merchant_name: transactionData.merchantName,
      total_amount: transactionData.totalAmount,
      currency: "NGN",
      transaction_date: new Date().toISOString(),
      items: transactionData.items,
      category: this.categorizeTransaction(transactionData),
      payment_method: transactionData.paymentMethod,
      status: "completed",
    };

    try {
      // Create receipt via API
      const response = await fetch(`${this.apiUrl}/createReceiptFromPOS`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(receiptData),
      });

      if (response.ok) {
        // Display QR code and short code to customer
        this.displayReceiptAccess(token, shortCode);
        return { success: true, token, shortCode };
      }
    } catch (error) {
      console.error("Receipt creation failed:", error);
      // Handle offline scenario
      this.queueForLater(receiptData);
    }
  }

  generateToken() {
    const timestamp = Date.now().toString(36);
    const random = Math.random().toString(36).substring(2, 8);
    return `rcpt_${timestamp}_${random}`;
  }

  generateShortCode() {
    return Math.random().toString(36).substring(2, 8).toUpperCase();
  }

  displayReceiptAccess(token, shortCode) {
    // Display QR code and short code on POS screen
    const qrCodeUrl = `https://receeco.com/app/receipt/${token}`;
    console.log("QR Code:", qrCodeUrl);
    console.log("Short Code:", shortCode);
  }
}

​
Integration Patterns

​
Webhook Pattern

Best for cloud-based POS systems: 
// Webhook endpoint
app.post("/pos-webhook", async (req, res) => {
  const { event, data } = req.body;

  if (event === "transaction.completed") {
    try {
      const receipt = await receeco.createReceipt({
        items: data.items,
        totalAmount: data.total,
        paymentMethod: data.payment_method,
      });

      // Respond with receipt access info
      res.json({
        success: true,
        receiptUrl: receipt.receiptUrl,
        shortCode: receipt.shortCode,
      });
    } catch (error) {
      res.status(500).json({ error: error.message });
    }
  }
});
For desktop POS systems that print receipts: 
const fs = require("fs");
const path = require("path");

class PrintMonitor {
  constructor(spoolPath, receeco) {
    this.spoolPath = spoolPath;
    this.receeco = receeco;
    this.watchPrintSpool();
  }

  watchPrintSpool() {
    fs.watch(this.spoolPath, (eventType, filename) => {
      if (eventType === "rename" && filename.endsWith(".txt")) {
        this.processReceiptFile(path.join(this.spoolPath, filename));
      }
    });
  }

  async processReceiptFile(filePath) {
    try {
      const content = fs.readFileSync(filePath, "utf8");
      const transactionData = this.parseReceiptContent(content);

      if (transactionData) {
        const receipt = await this.receeco.createReceipt(transactionData);
        console.log("Digital receipt created:", receipt.shortCode);
      }
    } catch (error) {
      console.error("Failed to process receipt:", error);
    }
  }

  parseReceiptContent(content) {
    // Parse receipt text and extract transaction data
    // Implementation depends on POS receipt format
  }
}

​
Testing Integration

​
POS Emulator

Use our POS emulator to test your integration: 
# Start POS emulator
receeco-pos emulator --port=3002

# Send test transaction
curl -X POST http://localhost:3002/test-transaction \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{"name": "Test Item", "quantity": 1, "price": 1000}],
    "total": 1000,
    "paymentMethod": "card"
  }'

​
Integration Testing

const { ReceecoPOS } = require("@receeco/node-sdk");

describe("POS Integration", () => {
  let receeco;

  beforeEach(() => {
    receeco = new ReceecoPOS({
      merchantId: "test-merchant",
      testMode: true,
    });
  });

  test("should create receipt for valid transaction", async () => {
    const transactionData = {
      items: [
        { name: "Test Item", quantity: 1, unitPrice: 1000, totalPrice: 1000 },
      ],
      totalAmount: 1000,
      currency: "NGN",
    };

    const receipt = await receeco.createReceipt(transactionData);

    expect(receipt.token).toBeDefined();
    expect(receipt.shortCode).toBeDefined();
    expect(receipt.receiptUrl).toContain("receeco.com");
  });
});

​
Troubleshooting

  • Verify POS system is configured to send webhooks/events - Check network connectivity between POS and Receeco agent - Review agent logs for error messages
  • Validate transaction data format - Check merchant ID configuration - Verify API endpoint accessibility
  • Ensure POS screen supports image display - Check QR code generation settings
  • Verify receipt URL accessibility
  • Check internet connectivity - Review offline queue configuration - Verify queue storage permissions

​
Support

Need help with your POS integration?

Technical Support

Email our technical team

Integration Consultation

Schedule a consultation call