Telebirr SuperApp FinTech Payment Bridge Integration

1. Overview & Business Value#

This comprehensive operational guide details the architecture, business workflows, configuration parameters, and execution steps for Telebirr SuperApp FinTech Payment Bridge Integration within SmartERP.

Telebirr is Ethiopia's dominant mobile money platform. The SmartERP Telebirr bridge delivers seamless C2B (Consumer-to-Business) checkout.

Payment Flow Mechanics#

$$\text{Invoice Created} \longrightarrow \text{Generate Telebirr QR} \longrightarrow \text{Customer Scans} \longrightarrow \text{Webhook Callback} \longrightarrow \text{Invoice Paid}$$

1. SmartERP requests dynamic payment URL and QR string from Telebirr gateway.
2. Customer confirms payment on mobile device.
3. Telebirr sends signed cryptographic callback to /payment/telebirr/webhook.
4. SmartERP verifies signature, creates payment transaction (payment.transaction), and reconciles the customer invoice.

{screenshot:telebirr-superapp-payment-gateway-overview-dashboard}

2. Prerequisites & Security Access Groups#

• Required Modules: base, web, smarterp_core, payment
• Security Groups:
  • Integration Specialist (Technical ID: base.group_user)
  • System Administrator / API Director (Technical ID: base.group_system)
• Master Data Dependencies: Established API keys, configured payment providers, and verified external webhook callback endpoints.

3. Step-by-Step Configuration & Execution#

Step 1: Navigating to the Module Interface#

1. Log into your SmartERP instance at https://smarterp.et/odoo.
2. Open the main App Switcher (grid icon in the top-left corner).
3. Select the Settings app icon.
4. From the top navigation bar, open Technical → Integrations → API Keys / Webhooks.

{screenshot:telebirr-superapp-payment-gateway-app-switcher-navigation}

Step 2: Creating and Parameterizing Records#

1. Click the New button in the top-left control panel.
2. Complete the mandatory fields in the integration form:
   • Endpoint Name (Mandatory): Descriptive identifier for the external client application.
   • Allowed API Scopes (Mandatory): Explicit read/write model permissions.
   • Authentication Mode (Mandatory): Bearer Token, API Key, or HMAC-SHA256 signature.
3. Configure optional parameters: rate limit quotas, IP address allowlists, and retry schedules.

{screenshot:telebirr-superapp-payment-gateway-record-creation-form}

Step 3: Validating and Processing Transactions#

• Execution & Validation: Dispatch test payload from external client tool (cURL / Postman).
• Log Verification: Inspect HTTP response status (HTTP 200 OK) in the API access log.

{screenshot:telebirr-superapp-payment-gateway-transaction-processing-state}

4. Advanced Configuration Points#

• Automated Actions & Scheduled Tasks (Crons):
  • Integration: Clean stale webhook queues (base.ir_cron_webhook_cleanup)
  • Integration: Sync currency exchange rates (base.ir_cron_currency_rates)
• Custom Print Templates & Reports:
  • API Usage & Latency Telemetry Audit Report
  • FinTech Reconciliation & Settlement Statement
• Multi-Company Rules: Record-level security isolation under Company 1 (Ashewa Technology Solutions S.C.).

5. Comprehensive Troubleshooting Matrix#