ISV POS Firebase Implementation
Overview
This page outlines the integration architecture for Independent Software Vendor (ISV) applications (e.g.,Odoo, Sage, Salesforce, Microsoft Business Central, and Finance & Operations) to connect to Seerbit’s Firebase-basedPOS communication infrastructure
Note: The Firebase-based approach is platform-agnostic and designed to work across different backend languages (Python, Java, JS/TS, Go).
Requirements: Before starting integration, ensure the following (table below) are in place.
Name
Type
Description
Required?
public key
string
public key - this can be copied from the seerbit dashboard
Yes
amount
string
amount to be charged
Yes
fullName
string
customer's full name
Yes
mobileNumber
string
customer's mobile number
Yes
currency
string
currency in which you want to charge
Yes
country
string
country of the business or currency
Yes
email
string
customer's email
Yes
paymentType
string
pament type should be set to CARD
Yes
cardNumber
string
debit or credit card number
Yes
expiryMonth
string
debit or credit card expiry month. E.g 12 means december
Yes
expiryYear
string
debit or credit card exiry year. E.g 23 means 2023
Yes
cvv
string
digits at the back of the card
Yes
pin
string
card pin
Yes
redirectUrl
string
page to be redirected to after successful authentication
Yes
Component
Description
Firebase Admin SDK
Required to listen to Seerbit Firebase collections securely.
Service Account JSON
Secure credentials file provided by Seerbit to authenticate your app.
ISV Listener App
Your ERP/CRM plugin/backend thatsubscribes to transaction updates.
Reconciliation Handler
Logic to reconcile transactions based on id, transactionRef, transactionValue, etc.
Integration Steps
✅ STEP 1: Add Firebase Admin SDK to Your Project
Firebase Admin SDK enables server-side interaction with Firebase, including real-time listeners and secure database writes.
Language Support 👇
Language Support 👇
Name
Type
Description
Required?
public key
string
public key - this can be copied from the seerbit dashboard
Yes
amount
string
amount to be charged
Yes
fullName
string
customer's full name
Yes
mobileNumber
string
customer's mobile number
Yes
currency
string
currency in which you want to charge
Yes
country
string
country of the business or currency
Yes
email
string
customer's email
Yes
paymentType
string
pament type should be set to CARD
Yes
cardNumber
string
debit or credit card number
Yes
expiryMonth
string
debit or credit card expiry month. E.g 12 means december
Yes
expiryYear
string
debit or credit card exiry year. E.g 23 means 2023
Yes
cvv
string
digits at the back of the card
Yes
pin
string
card pin
Yes
redirectUrl
string
page to be redirected to after successful authentication
Yes
Language
Installation Command
Python
pip install firebase-admin
JavaScript
npm install firebase-admin
Java
Use Maven or Gradle
Go
go get firebase.google.com/go
📘 Official Guide: https://firebase.google.com/docs/admin/setup
✅ STEP 2: Setup Firebase Credentials
Seerbit will provide a Service Account JSON file. This file contains credentials to authenticate your application securely with Firebase.
🔒 Security Note: Never commit this file to source control. Use environment variables or secure vaults for production.
The code snippet below shows an example implementation.
1import firebase_admin
2from firebase_admin import credentials
3
4cred = credentials.Certificate("path/to/serviceAccountKey.json")
5firebase_admin.initialize_app(cred)1var admin = require("firebase-admin");
2
3var serviceAccount = require("path/to/serviceAccountKey.json");
4
5admin.initializeApp({
6 credential: admin.credential.cert(serviceAccount)
7});1FileInputStream serviceAccount =
2new FileInputStream("path/to/serviceAccountKey.json");
3
4FirebaseOptions options = new FirebaseOptions.Builder()
5 .setCredentials(GoogleCredentials.fromStream(serviceAccount))
6 .build();
7
8FirebaseApp.initializeApp(options);1import (
2"fmt"
3"context"
4
5firebase "firebase.google.com/go"
6"firebase.google.com/go/auth"
7
8"google.golang.org/api/option"
9)
10
11opt := option.WithCredentialsFile("path/to/serviceAccountKey.json")
12app, err := firebase.NewApp(context.Background(), nil, opt)
13if err != nil {
14 return nil, fmt.Errorf("error initializing app: %v", err)
15}✅ STEP 3a: Initiate Payment
Using the sample payload below as a reference, push the payment information (Generated from ERP) to the transactions collection:
1{
2 "id": "id-1234",
3 "merchantid": "",
4 "metadata": "",
5 "posid": "22147776",
6 "pubkey": "",
7 "receivedDateTime": "30/06/2025 13:45",
8 "sessionId": "",
9 "status": "open",
10 "transactionRef": "",
11 "transactionTime": "",
12 "transactionValue": "1.50"
13 }✅ STEP 3b: Listen to Firebase Collections
The Firebase collections emit transaction events from the collections below :
* Reconciliations
1import firebase_admin
2from firebase_admin import firestore
3
4# Get Firestore client
5db = firestore.client()
6
7 # Define callback for listening to changes
8 def on_snapshot(col_snapshot, changes, read_time):
9 print(f"--- Change detected at {read_time} ---")
10 for change in changes:
11 if change.type.name == 'ADDED':
12 print(f"New document: {change.document.id} =>
13 {change.document.to_dict()}")
14 elif change.type.name == 'MODIFIED':
15 print(f"Modified document: {change.document.id} =>
16 {change.document.to_dict()}")
17 elif change.type.name == 'REMOVED':
18 print(f"Removed document: {change.document.id}")
19
20 # Start listening to a collection
21collection_ref = db.collection(u"myCollection")
22query_watch = collection_ref.on_snapshot(on_snapshot)
23
24 # Keep the program running
25print("Listening to Firestore changes... (Ctrl+C to stop)")
26import time
27while True:
28 time.sleep(60)✅ STEP 4: Process the Incoming Event
Your plugin/backend should implement logic to:
* Match the transaction to internal records using fields like merchant_id , pos_id , id ,
transactionRef , amount.
* Update invoice/payment status inside the ERP/CRM system.
* Match the transaction to internal records using fields like merchant_id , pos_id , id ,
transactionRef , amount.
* Update invoice/payment status inside the ERP/CRM system.
✅ STEP 5: Handle Reconciliation
A reconciliation endpoint or logic is necessary to:
* Validate payment integrity.
* Retry or reject duplicate transactions.
* Confirm matching amounts and payment status ( completed , failed ).
Recommended approach:
1. On POS transaction completion, receive event via Firebase.
2. Fetch internal ERP invoice details using reference ( id , transactionRef ).
3. Call Seerbit’s reconciliation endpoint (or internal match function).
4. Mark ERP invoice as paid/unpaid accordingly.
* Validate payment integrity.
* Retry or reject duplicate transactions.
* Confirm matching amounts and payment status ( completed , failed ).
Recommended approach:
1. On POS transaction completion, receive event via Firebase.
2. Fetch internal ERP invoice details using reference ( id , transactionRef ).
3. Call Seerbit’s reconciliation endpoint (or internal match function).
4. Mark ERP invoice as paid/unpaid accordingly.
1{
2 "id": "id-1234",
3 "merchantid": "",
4 "metadata": "",
5 "posid": "22147776",
6 "pubkey": "",
7 "receivedDateTime": "30/06/2025 13:45",
8 "sessionId": "",
9 "status": "open",
10 "transactionRef": "",
11 "transactionTime": "",
12 "transactionValue": "1.50"
13}Payload Description
Name
Type
Description
Required?
public key
string
public key - this can be copied from the seerbit dashboard
Yes
amount
string
amount to be charged
Yes
fullName
string
customer's full name
Yes
mobileNumber
string
customer's mobile number
Yes
currency
string
currency in which you want to charge
Yes
country
string
country of the business or currency
Yes
email
string
customer's email
Yes
paymentType
string
pament type should be set to CARD
Yes
cardNumber
string
debit or credit card number
Yes
expiryMonth
string
debit or credit card expiry month. E.g 12 means december
Yes
expiryYear
string
debit or credit card exiry year. E.g 23 means 2023
Yes
cvv
string
digits at the back of the card
Yes
pin
string
card pin
Yes
redirectUrl
string
page to be redirected to after successful authentication
Yes
Example/Note
Field
Description
Required?
“ERP-001”
Id
ID from the ERP
system.
system.
✅ Mandatory
..
posid
Payment terminal ID.
✅ Mandatory
..
merchantid
Merchant ERP ID.
✅ Mandatory
“20.50”
transactionValue
Transaction amount.
✅ Mandatory
ERP only sends open
on initiation.
completed/failed from SeerBit.
on initiation.
completed/failed from SeerBit.
status
Status of the transaction.
Possible values:
open, pending, completed, failed.
.
Possible values:
open, pending, completed, failed.
.
✅ Mandatory
...
sessionId
Transaction reference on SeerBit
✅ Mandatory
“WX03032025BC01”
transactionRef
ERP transaction reference.
✅ Mandatory
“03/03/202513:45”
receivedDateTime
payment type should be set to The time the transaction was initiated on the ERP.(mm/dd/yyyyHH:mm)
✅ Mandatory
..
transactionTime
Time transaction completed on SeerBit.
✅ Mandatory
..
metadata
Any additional data from ERP. This can be of any data type but should be stringified. This will be sent back to the reconciliations
collection
collection
✅ Mandatory
..
publicKey
Merchant's SeerBit publickey.
✅ Mandatory
NB:
All fields values should be sent as string format. Send an empty string if value is unavailable. However, id, posid, transactionValue, status, transactionRef, receivedDateTime should have actual values.
All fields values should be sent as string format. Send an empty string if value is unavailable. However, id, posid, transactionValue, status, transactionRef, receivedDateTime should have actual values.
🧩 Platform-Specific Notes
Odoo (v15 - v18)
* Use python-firebase or REST wrapper for real-time interaction.
* Integrate with account.payment and pos.order models.
* Add cron job fallback for missed Firebase events.
Sage X3 / Sage 300
* Use Node.js backend service or scheduled listener.
* Maintain sync between POS and ERP through Firebase events.
Salesforce
* Use Apex with Firebase-compatible middleware (Node.js/GCP Functions).
* Map transaction records to Opportunity/Invoice objects.
Microsoft Business Central & F&O
* Integrate via Azure Function or custom AL module.
* Trigger payment application via incoming transaction JSON payload.
* Use python-firebase or REST wrapper for real-time interaction.
* Integrate with account.payment and pos.order models.
* Add cron job fallback for missed Firebase events.
Sage X3 / Sage 300
* Use Node.js backend service or scheduled listener.
* Maintain sync between POS and ERP through Firebase events.
Salesforce
* Use Apex with Firebase-compatible middleware (Node.js/GCP Functions).
* Map transaction records to Opportunity/Invoice objects.
Microsoft Business Central & F&O
* Integrate via Azure Function or custom AL module.
* Trigger payment application via incoming transaction JSON payload.
🔄 Error Handling & Edge Cases
Scenario
Handling Recommendation
Duplicate Transaction Ref
Store transaction references and discard duplicates.
Firebase message loss or timeout
Implement reconciliation polling fallback every 5–10 mins.
Mismatched amounts
Flag for manual reconciliation or automated exception logging.
User ID not found
Return error and write to failed transaction queue.
✅ Best Practices
* Always validate data received from Firebase against internal references.
* Use structured logs and error tracking (e.g., Sentry, ELK, or Firebase Crashlytics).
* Implement retry mechanisms for failed webhook or Firebase event processing.
* Keep reconciliation logic idempotent (i.e., safe to repeat without duplication).
* Use structured logs and error tracking (e.g., Sentry, ELK, or Firebase Crashlytics).
* Implement retry mechanisms for failed webhook or Firebase event processing.
* Keep reconciliation logic idempotent (i.e., safe to repeat without duplication).
🔐 Security Considerations
* Always use HTTPS endpoints when writing back to Firebase.
* Keep your Firebase Admin credentials secure.
* Rotate service account keys periodically.
* Validate all incoming data formats to avoid injection or logic errors.
* Keep your Firebase Admin credentials secure.
* Rotate service account keys periodically.
* Validate all incoming data formats to avoid injection or logic errors.
🧪 Test Plan
* Simulate payment from POS and verify it is picked up by ISV plugin.
* Trigger Firebase message loss scenario and test reconciliation fallback.
* Validate multiple transactions from same POS device in succession.
* Test data corruption or tampering and confirm handling logic.
* Trigger Firebase message loss scenario and test reconciliation fallback.
* Validate multiple transactions from same POS device in succession.
* Test data corruption or tampering and confirm handling logic.
Need something else?
If you have any questions or need general help, visit our support page
Signup for developer update
You can unsubscribe at any time. Read our privacy policy.