Telebirr for WordPress & WooCommerce

Accept Ethiopian Birr (ETB) payments through Telebirr H5 C2B hosted web checkout. This PHP plugin provides standalone WordPress payment buttons, custom payment forms, donations, and invoice links, with an optional WooCommerce gateway for Classic Checkout and Checkout Blocks.

Status: development / integration validation pending. The source declares version 1.0.0; this repository is the documented development baseline, not evidence of a certified or production-tested release. Local automated checks exercise isolated logic and mocked WordPress/HTTP behavior. Real WordPress, WooCommerce, Telebirr sandbox, and production acceptance remain separate release gates. See progress, review findings, and the test plan.

Independent community integration. This project does not claim endorsement by Ethio Telecom, Telebirr, WordPress, or WooCommerce.

Contents

• What the app does
• Requirements
• Installation and setup
• Usage
• System architecture
• Repository structure
• Security and data
• Development and validation
• Progress and contributions
• Documentation

What the app does

The plugin redirects customers to Telebirr to approve payment. It does not collect a Telebirr PIN. A browser return only indicates navigation; payment completion depends on server-side verification. WooCommerce orders remain in WooCommerce storage; the Telebirr transaction screen currently lists standalone records only.

Current limits: ETB only; no refund API, recurring billing, subscription engine, automatic settlement reconciliation, invoice expiry/revocation UI, or customer receipt/email service. Fixed amounts in shortcode forms are browser-editable and must not be used as authoritative product pricing or automatic paid-content entitlement. Use WooCommerce or server-controlled invoices for priced goods. See the open release blockers.

Requirements

HPOS compatibility is declared in the plugin, and the gateway uses WooCommerce order APIs. This declaration still needs HPOS integration testing. The old readme.txt carried a Tested up to: 6.8 claim without supplied test evidence; that claim has been removed until verified.

Installation and setup

1. Clone the repository:

   git clone https://github.com/dannynewg/telebirr-woocommerce.git
   cd telebirr-woocommerce

2. Copy this directory into wp-content/plugins/telebirr-woocommerce/, or create a clean installable ZIP with:

   pwsh -File scripts/build-release.ps1

   Upload the generated dist/telebirr-woocommerce-1.0.0.zip in Plugins > Add New > Upload Plugin. GitHub's source archive also contains development files; the package script uses an explicit runtime-file allowlist.

3. Activate Payment Gateway for Telebirr – WooCommerce & WordPress.

4. Open Telebirr > Settings and select Sandbox.

5. Enter the merchant credentials below. Store them only in the target WordPress installation, never in Git, issue reports, screenshots, or example files.

6. Register the exact callback URL displayed by the plugin with Telebirr:

   https://your-site.example/wp-json/telebirr/v1/webhook

7. For WooCommerce, set the store currency to ETB, then enable Telebirr under WooCommerce > Settings > Payments. Saving the general Telebirr screen preserves the gateway's enabled flag and display settings; saving the gateway screen synchronizes shared credentials.

8. Complete the sandbox and deployment checklist before switching to production credentials and the production environment.

Blank secret fields preserve saved values. Encryption is tied to WordPress authentication salts: changing salts requires re-entering credentials. Keep secure backups and provision separate sandbox/production credentials. See operations for configuration behavior and troubleshooting.

Usage

Insert a shortcode into a WordPress page/post using a Shortcode block:

[telebirr_button amount="100" title="Voluntary contribution" text="Pay 100 ETB"]

[telebirr_form title="Service payment" description="Enter your details and amount"]

[telebirr_donation title="Support our work" preset_amounts="50,100,250,500"]

All three support redirect="https://your-site.example/thank-you/". The submission handler validates this against WordPress's allowed redirect hosts. The form additionally accepts amount; its readonly attribute is a UI hint, not server-side price enforcement. The button defaults to 100 ETB; the form defaults to a customer-entered amount; donation defaults to 50,100,250,500. The shared amount helper accepts plain decimal amounts from 0.01 to 1,000,000.00 ETB and normalizes to two decimal places. UI fields currently set a 1 ETB minimum; reconcile this with approved merchant limits during acceptance testing.

For invoices, use Telebirr > Create Invoice, enter the title, ETB amount and optional customer details, then copy the generated link:

https://your-site.example/?telebirr_invoice=OPAQUE_TOKEN

Anyone holding that URL can view the invoice's displayed customer information and start payment. Treat it as a bearer link. The URL requires an invoice token; merchant references are not accepted as public invoice identifiers. Existing reference-based links must be replaced with token links. Invoice links currently have no expiry or revocation controls.

System architecture

flowchart TB
    Browser[Customer browser]
    Admin[WordPress administrator]
    subgraph WP[WordPress plugin]
        Boot[Bootstrap and shared helpers]
        Forms[Shortcodes and invoice pages]
        Gateway[Optional WooCommerce gateway / Blocks]
        API[Shared API client]
        Security[RSA signing / verification and AES-GCM]
        Webhook[REST webhook handler]
        Txn[Standalone transaction manager]
        Logs[Redacting logger]
    end
    Store[(WordPress options / posts / postmeta / transients)]
    WC[(WooCommerce order storage)]
    Telebirr[Telebirr token / preOrder / queryOrder APIs]
    Hosted[Telebirr hosted paygate]
    Admin --> Boot
    Browser --> Forms
    Browser --> Gateway
    Forms --> API
    Gateway --> API
    API --> Security
    API --> Telebirr
    API --> Logs
    Forms --> Txn --> Store
    Gateway --> WC
    API --> Store
    Browser --> Hosted
    Hosted --> Browser
    Telebirr --> Webhook
    Webhook --> Security
    Webhook --> API
    Webhook --> Txn
    Webhook --> WC

sequenceDiagram
    actor Customer
    participant WP as WordPress / WooCommerce
    participant API as Telebirr API
    participant Paygate as Hosted checkout
    Customer->>WP: Submit payment / place order
    WP->>WP: Validate amount and persist merchant reference
    WP->>API: Obtain cached/new Fabric token
    WP->>API: Signed preOrder
    API-->>WP: prepay_id
    WP-->>Customer: Signed checkout redirect URL
    Customer->>Paygate: Approve payment
    Paygate-->>Customer: Return to merchant site (not proof of payment)
    API->>WP: Signed webhook callback
    WP->>WP: Check signature, timestamp, reference and replay cache
    WP->>API: Signed queryOrder
    API-->>WP: Payment status and facts
    WP->>WP: Match reference, amount, ETB and optional returned prepay ID
    WP->>WP: Update transaction/order and emit completion/failure hook

The plugin boots on plugins_loaded. Standalone services always register; admin services load for admin requests; WooCommerce services load only when WooCommerce gateway classes exist. init registers transaction storage and handles standalone submissions. REST routes register on rest_api_init; invoice pages intercept template_redirect. There is no separate queue, worker, cron reconciliation task, or custom table migration.

See architecture for module responsibilities, persisted fields, state transitions, trust boundaries, and known concurrency limitations.

Repository structure

telebirr-woocommerce.php       Plugin metadata, bootstrap, compatibility hooks
includes/
  core/                       API, security, logging, transaction storage, webhook
  standalone/                 Shortcodes, form submission, invoice rendering
  woocommerce/                Gateway and Checkout Blocks integration
  admin/                      Settings, invoice creation, standalone transaction list
  helpers.php                 Amount handling and legacy namespace wrappers
assets/css/                   Public and admin styles
assets/js/                    Checkout Blocks registration (no build step)
languages/                    Translation template
docs/                         Architecture, operations, review, progress, test plan
tests/                        Dependency-free PHP regression harness with WP/HTTP fakes
scripts/                      Validation, translation extraction, clean ZIP packaging
.github/                      CI and issue/PR templates
readme.txt                    WordPress plugin-directory style documentation

The original demo/signing ZIPs and old plugin ZIPs remain local and are ignored. They are not runtime dependencies and are not included in the public repository or release package. Their contents and redistribution rights have not been audited.

Security and data

• Requests use RSA SHA-256 signatures; stored App Secret/private key use AES-256-GCM with a key derived from wp_salt('auth'). New secret encryption fails closed if OpenSSL is unavailable. Legacy unprefixed plaintext values remain readable for compatibility and should be re-saved.
• Webhooks are public by design and authenticate payloads by signature, then apply a five-minute timestamp window and transient replay caching. They independently query the payment before completing it.
• Sequential duplicate completion is suppressed. Transients and read-then-write status checks are not atomic; exactly-once completion under concurrent callbacks is an open release blocker.
• Standalone records store customer name, phone/email where supplied, amount, reference, public token, status, and provider identifiers in WordPress postmeta. WooCommerce orders store their Telebirr reference and identifiers through order metadata APIs.
• Logs redact known secret/contact keys recursively, but can still contain payment metadata. Restrict log access and retention. Do not post raw logs in public issues.
• Authentication tokens and replay markers use WordPress transients. WordPress salts and encrypted secrets can live on the same server; this does not protect against a fully compromised site.

Read SECURITY.md for reporting and review findings for remaining security and reliability work. No live merchant credentials were provided or used for the repository checks.

Development and validation

No Composer dependencies, npm installation, or frontend bundling are required to run the current plugin. A WordPress installation is still required for real application behavior.

php scripts/check.php
php tests/run.php
php -n -d disable_functions=openssl_encrypt,openssl_decrypt tests/no-openssl.php
node --check assets/js/telebirr-blocks.js
node scripts/update-translations.mjs

PHP CLI must load OpenSSL for cryptographic checks. On Windows, if PHP ships without an enabled php.ini, pass -d extension_dir="<php-directory>/ext" -d extension=openssl to php tests/run.php. Do not disable TLS verification to troubleshoot a merchant connection.

GitHub Actions runs syntax and isolated regression checks on PHP 8.1 and 8.4. A green result covers those checks only; see TESTING.md for the unexecuted integration matrix and go-live gates. Build a clean plugin ZIP with pwsh -File scripts/build-release.ps1; generated ZIPs stay out of Git.

Progress and contributions

PROGRESS.md is the versioned status ledger, with completed work, prioritized next work, acceptance criteria, and a release checklist. REVIEW.md records the inspection findings. Use GitHub Issues for actionable work; include a progress ID such as REL-01 or SEC-01 in the issue/PR and update the ledger when the evidence changes. No completion percentage is claimed without a defined scope.

See CONTRIBUTING.md. Keep changes focused, add regression coverage for payment/security behavior, describe test evidence, and never commit merchant credentials or customer records. Existing plugin metadata declares GPLv2 or later; this repository retains that licensing choice. See LICENSE.

Documentation

The endpoint paths documented here describe the implementation in this repository. Confirm the merchant's current Telebirr contract, endpoint URLs, signature rules, callback schema, and acknowledgement requirements directly with Telebirr before production use; no live provider certification is claimed.