Metadata-Version: 2.1
Name: odoo-addon-payment_easypay
Version: 18.0.1.0.0.2
Requires-Python: >=3.10
Requires-Dist: odoo==18.0.*
Summary: Payment Provider for EasyPay with multiple payment methods
Home-page: https://github.com/OCA/l10n-portugal
License: LGPL-3
Author: Open Source Integrators, Odoo Community Association (OCA)
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 18.0
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Description-Content-Type: text/x-rst

.. image:: https://odoo-community.org/readme-banner-image
   :target: https://odoo-community.org/get-involved?utm_source=readme
   :alt: Odoo Community Association

=========================
Payment Provider: EasyPay
=========================

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:6041b83be1366758729b1da4bd1fdaae91babafdc815dba189e75e16ab358ef8
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
    :target: https://odoo-community.org/page/development-status
    :alt: Beta
.. |badge2| image:: https://img.shields.io/badge/license-LGPL--3-blue.png
    :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
    :alt: License: LGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fl10n--portugal-lightgray.png?logo=github
    :target: https://github.com/OCA/l10n-portugal/tree/18.0/payment_easypay
    :alt: OCA/l10n-portugal
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/l10n-portugal-18-0/l10n-portugal-18-0-payment_easypay
    :alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
    :target: https://runboat.odoo-community.org/builds?repo=OCA/l10n-portugal&target_branch=18.0
    :alt: Try me on Runboat

|badge1| |badge2| |badge3| |badge4| |badge5|

This module integrates EasyPay as a payment provider in Odoo, allowing
customers to pay via credit card and other payment methods using
EasyPay's secure payment gateway.

EasyPay is a Portuguese payment service provider that supports multiple
payment methods including credit cards, Multibanco, MB WAY, SEPA Direct
Debit, and more.

Verified as supported: Credit/Debit Card payments, Multibanco (MB)
reference payments, MB WAY.

Not yet implemented or verified: SEPA Direct Debit, Pay by Link,
Multibanco reference on invoices.

Learn more about EasyPay at https://www.easypay.pt/

**Table of contents**

.. contents::
   :local:

Configuration
=============

**Currency requirement:** EasyPay only supports **EUR**. The provider is
pre-configured to appear only for EUR transactions and will be hidden
automatically when the customer's currency is different.

1. Create an EasyPay Account
----------------------------

- **Test environment**: Sign up at https://backoffice.test.easypay.pt/
- **Production**: Sign up at https://www.easypay.pt/ and complete
  merchant verification

Once logged in, note your **Account ID** and **API Key** (both UUID
format) from the EasyPay dashboard.

2. Configure the Provider in Odoo
---------------------------------

1. Go to **Accounting → Configuration → Payment Providers** (or
   **Website → Configuration → Payment Providers**)
2. Search for **EasyPay** and open the provider form
3. Fill in:

   - **Account ID** — from your EasyPay dashboard
   - **API Key** — from your EasyPay dashboard (admin-only field)
   - **Payment Methods** — select the methods to offer (Credit/Debit
     Card, Multibanco, MB WAY, etc.)
   - **Allow Saving Payment Methods** — when enabled, logged-in
     customers can tick "Save my payment details" at checkout to
     tokenize their card or SEPA Direct Debit mandate for future charges
     (e.g. subscriptions). Enabled by default.

4. Set the provider **State**:

   - **Test Mode** → uses ``https://api.test.easypay.pt`` and enables
     the ``testing`` flag in the SDK automatically
   - **Enabled** → uses ``https://api.prod.easypay.pt`` (production)

5. Click **Save**

3. Register Webhooks
--------------------

EasyPay sends payment status updates to three separate Odoo endpoints.
The simplest way to register them is to use the built-in button:

1. On the EasyPay provider form, click **Configure Webhooks**
2. Odoo will call ``PATCH /2.0/config`` on the EasyPay API and register:

   - ``https://yourdomain.com/payment/easypay/webhook/generic``
   - ``https://yourdomain.com/payment/easypay/webhook/authorisation``
   - ``https://yourdomain.com/payment/easypay/webhook/transaction``

If you need to register webhooks manually in the EasyPay dashboard, use
the three URLs above. All three must be registered for all payment
methods to work correctly (Multibanco confirmation, for example, arrives
via the transaction webhook).

**Note:** Webhooks must be reachable from the internet. If running
locally, use a tunnel such as localtunnel
(https://theboroer.github.io/localtunnel-www/) or ngrok and update the
Odoo base URL accordingly before clicking **Configure Webhooks**.

4. Test the Connection
----------------------

Click **Test Connection** on the provider form to verify that your
credentials are correct and the EasyPay API is reachable.

5. Go Live
----------

1. Replace test credentials with production values
2. Change provider **State** to **Enabled**
3. Click **Configure Webhooks** again to register production webhook
   URLs
4. Test with a small real payment before going fully live
5. Set the provider to **Published** so customers can see it

Usage
=====

Once configured, customers can use EasyPay to make payments:

1. During checkout, select **EasyPay** as the payment method
2. Click **Pay Now**
3. A secure inline payment form loads. The customer selects a payment
   method and completes the payment without leaving the site.

Payment method behaviour
------------------------

- **Credit/Debit Card**: Payment is captured immediately. Order is
  confirmed as soon as the card is charged.
- **MB WAY**: The customer enters their mobile number. A push
  notification is sent to their phone for confirmation. The order is
  placed in *Pending* state until the user confirms (or rejects) on the
  MB WAY app.
- **Multibanco**: An ATM reference (Entity + Reference + Amount) is
  displayed. The customer pays at any ATM or via online banking. The
  order remains *Pending* until the payment is confirmed, which may take
  minutes to days. The customer should **not** close the confirmation
  page before noting down the reference.
- **SEPA Direct Debit**: The customer enters their IBAN and accepts a
  SEPA mandate authorizing EasyPay to debit their account. The order
  remains *Pending* until the bank settles the debit (typically 2–5
  business days). When used with tokenization, the mandate is saved and
  subsequent charges are pulled automatically.
- **Virtual IBAN**: A dedicated IBAN is displayed. The customer
  transfers the exact amount via online banking. The order remains
  *Pending* until the transfer is received and matched by EasyPay.
- **Save payment details (tokenization)**: Logged-in customers can tick
  *Save my payment details* at checkout. The payment method is saved as
  a token for future charges (e.g. subscriptions). This works with cards
  and SEPA Direct Debit.

Refunds
-------

Refunds can be initiated from the Odoo backend on any confirmed
transaction:

1. Open the payment transaction and click **Refund**
2. A refund request is sent to EasyPay and a child refund transaction is
   created in *Pending* state
3. Once EasyPay processes the refund, a webhook updates the refund
   transaction to *Done* (or *Error* if it failed)

Partial refunds are supported — enter the amount to refund when
prompted.

Test card details (test environment only)
-----------------------------------------

See the `EasyPay Payment Methods
guide <https://docs.easypay.pt/docs/guides/payment-methods>`__ for full
test credentials for all payment methods.

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/OCA/l10n-portugal/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/OCA/l10n-portugal/issues/new?body=module:%20payment_easypay%0Aversion:%2018.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
-------

* Open Source Integrators

Contributors
------------

- Open Source Integrators <https://www.opensourceintegrators.com>

  - Daniel Reis (dreis@opensourceintegrators.com)

This work was developed with the aid of AI tools under human guidance
and supervision, specifically Cascade (IDE coding assistant) and
Anthropic Claude. All AI-assisted changes were reviewed and approved by
human maintainers.

Maintainers
-----------

This module is maintained by the OCA.

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

This module is part of the `OCA/l10n-portugal <https://github.com/OCA/l10n-portugal/tree/18.0/payment_easypay>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
