Process Transaction
Request Body
Your merchant identifier from Receeco dashboard
Display name of your business
URL to your business logo
Hex color code for receipt branding (e.g., “#22c55e”)
Array of purchased items
Price per unit in Naira (not kobo)
Total price for this item in Naira (not kobo)
Stock Keeping Unit identifier
Total transaction amount in Naira (not kobo)
ISO currency code (defaults to “NGN”)
Payment method used (e.g., “card”, “cash”, “transfer”)
Store location or branch name
Transaction timestamp in ISO 8601 format (auto-generated if not provided)
Your internal transaction ID (optional)
Cashier identifier (optional)
Terminal/POS identifier (optional)
Example Request
{
"merchantId": "grocery-store-001",
"merchantName": "Fresh Foods Supermarket",
"merchantLogo": "https://example.com/logo.png",
"accentColor": "#22c55e",
"items": [
{
"name": "Premium Rice (5kg)",
"quantity": 1,
"unitPrice": 95.0,
"totalPrice": 95.0,
"sku": "RICE001"
},
{
"name": "Fresh Milk (1L)",
"quantity": 2,
"unitPrice": 15.75,
"totalPrice": 31.5,
"sku": "MILK001"
}
],
"totalAmount": 126.5,
"currency": "NGN",
"paymentMethod": "card",
"location": "Lagos Island Branch",
"timestamp": "2024-01-15T14:30:00Z",
"transactionId": "TXN001",
"cashierId": "CASHIER001",
"terminalId": "TERMINAL001"
}
Response Fields
Unique receipt identifier for tracking
Direct URL to view the digital receipt
Base64 encoded QR code image for display/printing
SVG format QR code for scalable display
6-digit code for manual customer entry
Direct link with embedded short code
Processing status: “success” or “error”
Processing completion timestamp
Error Responses
{
"error": {
"message": "Internal server error",
"code": -32603,
"data": {
"code": "INTERNAL_SERVER_ERROR",
"httpStatus": 500
}
}
}
Additional Endpoints
Health Check
{
"status": "healthy",
"timestamp": "2024-01-15T14:30:05Z",
"version": "1.0.5"
}
Agent Configuration
{
"merchantId": "grocery-store-001",
"apiUrl": "https://receeco.com/api",
"webUrl": "https://receeco.com",
"hasApiKey": true,
"version": "1.0.5"
}
Queue Status
{
"total": 5,
"pending": 2,
"failed": 1,
"processed": 2,
"lastSync": "2024-01-15T14:25:00Z"
}
Transaction Status
{
"transactionId": "TXN001",
"status": "completed",
"receiptId": "rcpt_abc123_def456",
"timestamp": "2024-01-15T14:30:05Z"
}
Integration Examples
Basic POS Integration
const axios = require("axios");
// Send transaction to local POS agent
async function processTransaction(transactionData) {
try {
const response = await axios.post(
"http://localhost:3001/transactions",
transactionData,
{
headers: { "Content-Type": "application/json" },
timeout: 10000, // 10 second timeout
}
);
return response.data;
} catch (error) {
console.error("Transaction processing failed:", error);
throw error;
}
}
// Example usage
const transaction = {
merchantId: "grocery-store-001",
merchantName: "Fresh Foods Market",
merchantLogo: "https://example.com/logo.png",
accentColor: "#22c55e",
items: [
{
name: "Premium Rice (5kg)",
quantity: 1,
unitPrice: 95.0,
totalPrice: 95.0,
sku: "RICE001",
},
],
totalAmount: 95.0,
currency: "NGN",
paymentMethod: "card",
location: "Main Branch",
timestamp: new Date().toISOString(),
transactionId: "TXN001",
cashierId: "CASHIER001",
terminalId: "TERMINAL001",
};
processTransaction(transaction)
.then((result) => {
console.log("Receipt created:", result.receiptUrl);
console.log("Short code:", result.shortCode);
})
.catch((error) => {
console.error("Failed:", error.message);
});
Best Practices
Token Generation
Use timestamp + random string for unique tokens
Error Handling
Implement retry logic for network failures
Offline Support
Queue transactions when API is unavailable
Validation
Validate all data before sending to API
Always generate unique tokens and short codes for each transaction to prevent
conflicts and ensure security.
