{"id":28569641,"url":"https://github.com/abilian/flask-taler","last_synced_at":"2025-10-05T01:51:29.596Z","repository":{"id":270696756,"uuid":"911188079","full_name":"abilian/flask-taler","owner":"abilian","description":"Flask / Taler integration (not working yet)","archived":false,"fork":false,"pushed_at":"2025-01-02T12:48:42.000Z","size":63,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-10T17:15:31.853Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abilian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-02T12:47:14.000Z","updated_at":"2025-01-02T12:48:44.000Z","dependencies_parsed_at":"2025-01-02T17:04:13.694Z","dependency_job_id":null,"html_url":"https://github.com/abilian/flask-taler","commit_stats":null,"previous_names":["abilian/flask-taler"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/abilian/flask-taler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fflask-taler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fflask-taler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fflask-taler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fflask-taler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abilian","download_url":"https://codeload.github.com/abilian/flask-taler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fflask-taler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278399610,"owners_count":25980331,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-10T17:15:19.652Z","updated_at":"2025-10-05T01:51:29.566Z","avatar_url":"https://github.com/abilian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flask-Taler: GNU Taler Integration for Flask\n\n[![PyPI version](https://badge.fury.io/py/flask-taler.svg)](https://badge.fury.io/py/flask-taler)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\n`Flask-Taler` is a Flask extension that simplifies the integration of [GNU Taler](https://taler.net/), a privacy-preserving electronic payment system, into your Flask web applications. This extension provides a convenient way to create payment orders, handle payment redirects, process refunds, and manage callbacks from the Taler system.\n\n\n\u003e NOT READY FOR RELEASE\n\n\n## Features\n\n*   **Easy Order Creation:**  Create Taler payment orders with just a few lines of code.\n*   **Payment URL Retrieval:** Obtain payment URLs to redirect users to the Taler wallet for payment.\n*   **Refund Handling:** Process full or partial refunds for completed transactions.\n*   **Callback Handling:**  Implement routes to handle payment success and failure callbacks.\n*   **Webhook Support (Recommended):** Integrate with Taler's webhook functionality for real-time payment status updates.\n*   **Error Handling:** Robust error handling and logging for debugging.\n*   **Secure Configuration:** Store API keys and other sensitive information securely.\n\n## Installation\n\n```bash\npip install flask-taler\n```\n\n## Configuration\n\nConfigure the `Flask-Taler` extension using the following parameters in your Flask app's configuration (`app.config`):\n\n*   `TALER_EXCHANGE_URL`: The URL of the Taler exchange.\n*   `TALER_MERCHANT_BACKEND_URL`: The URL of your Taler merchant backend.\n*   `TALER_MERCHANT_API_KEY`: Your Taler merchant API key.\n*   `TALER_DEFAULT_CURRENCY`: The default currency for orders (e.g., \"EUR\").\n\n**Example:**\n\n```python\napp = Flask(__name__)\napp.config['TALER_EXCHANGE_URL'] = 'https://exchange.taler.example.com'\napp.config['TALER_MERCHANT_BACKEND_URL'] = 'https://merchant.taler.example.com'\napp.config['TALER_MERCHANT_API_KEY'] = 'your_api_key_here'\napp.config['TALER_DEFAULT_CURRENCY'] = 'USD'\n```\n\nIt's highly recommended to store sensitive information like API keys in environment variables rather than directly in your code. You can use libraries like `python-dotenv` to manage environment variables.\n\n## Usage\n\nHere's a basic example of how to use `Flask-Taler` to create an order and handle payment:\n\n```python\nfrom flask import Flask, render_template, request, redirect, url_for\nfrom flask_taler import Taler\n\napp = Flask(__name__)\n# ... (Configuration as described above) ...\n\ntaler = Taler(app)\n\n@app.route('/buy/\u003cint:product_id\u003e')\ndef buy_product(product_id):\n    # 1. Retrieve product information from your database\n    product = get_product_from_db(product_id)\n\n    # 2. Create a Taler payment order\n    order = taler.create_order(\n        amount=product.price,\n        currency=product.currency,\n        order_id=f\"product-{product_id}\", # Optional custom order ID\n        product_description=product.name,\n        fulfillment_url=url_for('payment_success', product_id=product_id, _external=True) # URL to redirect to after successful payment.\n    )\n\n    # 3. Get the payment URL and redirect the user\n    payment_url = taler.get_payment_url(order['order_id'])\n    if payment_url:\n        return redirect(payment_url)\n    else:\n        return \"Error creating order or getting payment URL.\"\n\n@app.route('/payment/success/\u003cint:product_id\u003e')\ndef payment_success(product_id):\n    # 4. (Recommended) Verify the payment status using Taler's webhooks.\n    # For this demo, we'll assume the payment was successful.\n\n    product = get_product_from_db(product_id)\n    return f\"Thank you for purchasing {product.name}!\"\n\n@app.route('/refund/\u003corder_id\u003e')\ndef refund_order(order_id):\n    # 5. Initiate a refund for a given order\n    refund_result = taler.process_refund(order_id)\n    if refund_result:\n        return f\"Refund for order {order_id} processed successfully.\"\n    else:\n        return f\"Error processing refund for order {order_id}.\"\n\n# ... (Helper function to get product details from the database) ...\ndef get_product_from_db(product_id):\n    # Replace with your actual database query logic\n    # This is just a placeholder example\n    products = {\n        1: {'name': 'Awesome T-Shirt', 'price': 25.0, 'currency': 'EUR'},\n        2: {'name': 'Cool Mug', 'price': 10.0, 'currency': 'USD'},\n    }\n    return products.get(product_id)\n\nif __name__ == '__main__':\n    app.run(debug=True)\n```\n\n**Explanation:**\n\n1. **Retrieve Product:** The `buy_product` route first fetches product details (replace `get_product_from_db` with your actual database logic).\n2. **Create Order:** It then uses `taler.create_order()` to create a new payment order with the Taler backend. You need to provide the amount, currency, an optional order ID, product description, and a fulfillment URL (where the user will be redirected after successful payment).\n3. **Redirect to Payment:** `taler.get_payment_url()` retrieves the URL for the Taler payment page. The user is redirected to this URL to complete the payment.\n4. **Handle Success (Webhook Recommended):** The `payment_success` route is a placeholder for handling successful payments. Ideally, you should use Taler's webhook functionality to receive real-time notifications about payment status changes. In a real application, you would verify the payment status with the Taler backend before fulfilling the order.\n5. **Refund:** The `refund_order` route demonstrates how to initiate a refund using `taler.process_refund()`.\n\n**Important Notes:**\n\n*   **Webhooks:** For production environments, it's crucial to implement webhooks to receive asynchronous notifications from Taler about payment status changes. This ensures that you don't rely solely on user redirects for order fulfillment.\n*   **Error Handling:** The example code includes basic error handling. You should expand this to handle various error scenarios and provide appropriate feedback to the user.\n*   **Security:** Always store your Taler API key securely, preferably as an environment variable.\n\n\n## Conceptual Overview\n\nThe `flask-taler` extension provides a simple and intuitive API for Flask developers to:\n\n1. **Initialize Taler:** Configure the extension with necessary parameters like the Taler exchange URL, merchant backend URL, API keys, etc.\n2. **Create Orders:** Easily create payment orders with details like amount, currency, product description, and fulfillment URL.\n3. **Get Payment URL:** Obtain a payment URL that redirects the user to the Taler wallet for payment.\n4. **Handle Payment Callbacks:**  Define routes to handle payment success/failure callbacks from the Taler system.\n5. **Process Refunds:** Issue full or partial refunds for completed transactions.\n6. **Manage Wallet Operations:** Handle wallet operations.\n\n\n## API Reference\n\n### `Taler` Class\n\n**`__init__(self, app=None)`:** Initializes the extension. If `app` is provided, it calls `init_app(app)`.\n\n**`init_app(self, app)`:** Initializes the extension with the Flask app. Loads configuration from `app.config`.\n\n**`create_order(self, amount, currency=None, order_id=None, product_description=None, fulfillment_url=None, metadata=None)`:** Creates a payment order.\n    *   `amount` (float): The amount to be paid.\n    *   `currency` (str, optional): The currency code. Defaults to `TALER_DEFAULT_CURRENCY`.\n    *   `order_id` (str, optional): A custom order ID.\n    *   `product_description` (str, optional): A description of the product or service.\n    *   `fulfillment_url` (str, optional): The URL to redirect to after successful payment.\n    *   `metadata` (dict, optional): Additional metadata to store with the order.\n    *   **Returns:** A dictionary containing the order details from the Taler backend.\n\n**`get_payment_url(self, order_id)`:** Retrieves the payment URL for an order.\n    *   `order_id` (str): The ID of the order.\n    *   **Returns:** The payment URL (str) or `None` if the order is not found or not payable.\n\n**`process_refund(self, order_id, amount=None)`:** Initiates a refund.\n    *   `order_id` (str): The ID of the order to refund.\n    *   `amount` (float, optional): The amount to refund. If `None`, a full refund is issued.\n    *   **Returns:** The refund response from the Taler backend.\n\n\n## Contributing\n\nContributions are welcome! Please feel free to submit pull requests or open issues on the project's [GitHub repository](your-repo-url).\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n\n## Further Development / Roadmap\n\n*   **Wallet Operations:** Add methods to the extension to interact with Corporate and Collaborator wallets for managing funds, transfers, etc.\n*   **Dolibarr Integration:** Create helper functions or classes to map Taler orders and payments to Dolibarr invoices and transactions.\n*   **Advanced Features:** Implement support for features like session-bound payments, repurchase detection, and more complex order customization options offered by the Taler API.\n*   **Testing:** Write comprehensive unit and integration tests to ensure the extension works correctly and handles various scenarios.\n*   **Documentation:** Provide clear and detailed documentation for the extension, including usage examples, API reference, and troubleshooting tips.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabilian%2Fflask-taler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabilian%2Fflask-taler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabilian%2Fflask-taler/lists"}