eupago 0.5.0__tar.gz

eupago-0.5.0/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "mkdocs.yml"
+      - "mkdocs_hooks.py"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[docs]"
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

eupago-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+# Publishes to PyPI via Trusted Publishing (OIDC) — no tokens or secrets.
+# Trigger: publish a GitHub Release (which also creates the tag).
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check artifacts
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/eupago/
+    permissions:
+      id-token: write # required for OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

eupago-0.5.0/.gitignore

@@ -0,0 +1,37 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+*.whl
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+.env
+.env.*
+!.env.example
+.venv/
+venv/
+*.log
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+site/
+site/
+
+# Local-only working notes
+eupago-duvidas.md
+*.local.md
+CLAUDE.*

eupago-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.8
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [pydantic>=2.0, httpx>=0.27, cryptography>=42.0]
+        args: [--strict, src/]
+        pass_filenames: false
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.2
+    hooks:
+      - id: gitleaks

eupago-0.5.0/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-05-31
+
+First production-validated release. MB WAY, Multibanco, Pay By Link and
+Refunds were exercised against a live eupago production channel
+(`Destrezàvolta`) with real money — 5 transactions paid and 3 refunds
+emitted, all webhooks captured and verified through the SDK. Several
+real wire-shape bugs surfaced and were fixed.
+
+### Added
+- **Subscription management** on `client.credit_card` — four new methods covering the full `/api/management/v1.02/subscriptions` + `/creditcard/edit` surface that the eupago backoffice uses (sync + async):
+  - `list_subscriptions()` — returns every subscription on the channel.
+  - `get_subscription(subscription_id)` — full detail incl. `nextCollectionDate` and current `autoProcess` / `collectionDay`.
+  - `edit_subscription(subscription_id, collection_day=..., auto_process=...)` — changes the billing schedule. With `auto_process=True` eupago bills the registered card itself on every `collection_day` of the period — no need to call `charge_subscription`. Sends as `application/x-www-form-urlencoded`, which the SDK transport now supports.
+  - `revoke_subscription(subscription_id)` — cancels an active subscription (raises `SUBSCRIPTION_NOT_FOUND` on `Pendente`).
+  - All four take the **integer** `subscriptionId` from the backoffice URL — not the hex `eupagoToken` (`charge_subscription` still takes the hex). The list response does not include the integer ID today; this is documented as a known eupago UX gap.
+- **HTTP transport** now accepts a `data=` parameter for `application/x-www-form-urlencoded` bodies (with the Content-Type override). Used by `edit_subscription`.
+- **`EupagoClient(management_bearer=...)`** — inject a pre-obtained Bearer for the `/api/management/*` endpoints (refunds, transactions, …). Bypasses the OAuth `client_id`/`client_secret` flow. Useful for tests/scripts where the caller already has a token, e.g. from the eupago backoffice login. Production callers should still prefer OAuth.
+- New live integration test `tests/integration/test_refund_live.py` that pays an MB WAY transaction, captures the webhook, then calls `client.refunds.refund(...)` end-to-end and asserts `REFUNDED` + a real `refundId` in the response. Uses `management_bearer` from the backoffice helper as the temporary auth path until eupago issues OAuth credentials.
+
+### Added
+- **`client.refunds.get(refund_id)`** (sync + async) — `GET /api/management/v1.02/refund/{refundId}`. Returns the refund's current state (`identifier`, `reference`, `status`). Particularly useful for Multibanco refunds, which settle asynchronously (`status: "pendente"` until the bank transfer clears, then `"Reembolsado"`).
+- **`eupago.utils.bic_for_pt_iban(iban)`** — helper that maps a Portuguese IBAN's bank code (positions 5–8) to the corresponding BIC. Covers the major retail banks in Portugal (~99% of consumer accounts). Returns `None` for niche banks. Built because Multibanco refunds require a `bic` argument and eupago doesn't expose a lookup API for it.
+- **`WebhookEvent.original_transaction_id`** — populated on refund webhooks (`method="refund"`) with the trid of the original payment being refunded. Lets callers correlate the refund back to the original payment without keeping their own mapping. eupago sends this as `originalTrid` in the webhook payload.
+
+### Docs
+- **Pay By Link behaviour learned from prod smoke tests (2026-05-31):**
+  - When the customer completes a Pay By Link payment, the webhook fires as the **chosen method's** webhook (e.g. `method="mbway"`), not a generic "paybylink" event. Your handler doesn't need Pay By Link special-casing — treat the webhook like any direct payment of that method.
+  - When a Pay By Link expires unpaid (`expires_at` passes with no payment started), **no webhook fires**. This is different from MB WAY's direct push (which does fire an `"Expired"` webhook). Track expiry from your own clock.
+- **Multibanco refund actually requires `bic` even though docs say optional** — `client.refunds.refund(...)` without `bic` returns `BIC_INVALID` on Multibanco transactions in production. Updated `docs/payments/refund.md` and `examples/12_refund.py` to make `bic` mandatory in Multibanco refund examples (with `BCOMPTPL` for Millennium BCP as the canonical example). Also documented that Multibanco refunds settle asynchronously — the sync response is `"Pendente"`, the settlement webhook arrives later (sometimes hours).
+
+### Fixed
+- **Refund webhook support** — the eupago documentation says no webhook fires on refunds. **In practice it does** (confirmed live in production, 2026-05-31): an async webhook arrives with `method="RB:PT"`, `status="REFUNDED"` (uppercase, distinct from the synchronous response's `"Reembolsado"`), and an `originalTrid` field. The SDK now maps `RB:PT` → `"refund"`, `"REFUNDED"` → `PaymentStatus.REFUNDED`, and surfaces the original trid via `WebhookEvent.original_transaction_id`. Without these mappings the refund webhook fell through to `method="rb:pt"` + `status=PENDING`, silently dropping the actual state.
+- **Status normalization** for cancelled MB WAY: eupago webhooks use the US spelling `"Canceled"` (single L) for transactions the customer rejected on the MB WAY app — confirmed live in production on 2026-05-31. The SDK now maps `Canceled` / `Cancelled` / `Pending` / `Pendente` / `Reembolsado` to the right `PaymentStatus`; previously these fell through to `PaymentStatus.PENDING` (silent loss of state). Added new live smoke-test script (`scripts/prod_smoke_test.py`) used to discover this.
+- **Refund** body shape: was `{value, currency, motivo}`, eupago expects `{amount, reason}` (plus optional `iban`/`bic` for non-MB WAY / non-Card transactions). The old shape returned `AMOUNT_MISSING`. Response parser now reads `refundId` correctly (live-verified: `{"transactionStatus":"Success","refundId":"2788","status":"Reembolsado"}`). Parameter renamed from `value` to `amount` to match the wire field.
+- **MB WAY** request body now includes the required `countryCode` (default `"351"`) and `customerPhone` on every endpoint, not only `create`. Without `countryCode` the `authorize` endpoint returns `CUSTOMERPHONE_MISSING` / `BAD_REQUEST` even though the value was present, because the eupago spec ties the two together.
+- **MB WAY capture** body shape: was `{"payment": {"amount": X}}`, eupago expects `{"payment": {"value": X, "currency": "EUR"}}`. The old body returned `AMOUNT_MISSING`. Fixed and asserted by unit test.
+- **Credit Card capture** now sends the full payment body (amount object + URLs) — the previous empty body returned `AMOUNT_MISSING`. New required parameter `amount`; optional `success_url`/`error_url`/`back_url`/`customer`/`order_id`.
+- **Credit Card subscription**:
+  - `create_subscription` now wraps the request with the required `subscription` block (`date`, `autoProcess`, `collectionDay`, `periodicity`, `limitDate`). Without it the endpoint returns 500 BAD_REQUEST. New optional parameters: `start_date`, `periodicity` (default `"Mensal"`), `collection_day` (default `1`), `limit_date` (default 1 year out), `auto_process` (default `False`).
+  - Response parser now reads `subscriptionID` and `referenceSubs` (the names the subscription endpoint actually uses) in addition to `transactionID`/`reference`. The `subscriptionID` is mapped to `PaymentResult.transaction_id` so it can be passed straight to `charge_subscription`.
+  - `charge_subscription` takes `recurrent_id: str` (eupago returns a hex string, not an int) and accepts the required `success_url`/`error_url`/`back_url` + optional `days_to_capture`.
+
+### Added
+- **MB WAY**: `create_payment`, `authorize`, `capture` (sync + async). Live-verified against the eupago sandbox.
+- **Multibanco**: `create_reference`, `get_info` (sync + async). Live-verified, including the paid `info` response.
+- **Credit Card**: `create_payment`, `authorize`, `capture`, `create_subscription`, `charge_subscription` (sync + async). Full 3D-Secure flow is end-to-end validated by a Playwright integration test using the official sandbox test card (`4018810000150015`, OTP `0101`) — Playwright drives the Shift4 form and the Credorax ACS challenge, and the test asserts the `Paid` webhook lands in the test receiver.
+- **Refunds**: `client.refunds.refund` (sync + async). OAuth-authenticated against `/api/management/v1.02/refund/{trid}`; live verification requires `client_id` / `client_secret` on the channel and a paid transaction to refund. Per the eupago docs, **refunds do not fire webhooks** — verify via the response or the management transactions endpoint. OAuth credentials are issued by eupago support on request (customer.support.eupago.com); they are not the API key and are not self-service in the backoffice.
+- **Apple Pay**: `client.apple_pay.create_payment` (sync + async). Forwards the `PKPaymentToken` from Apple Wallet to `payment.applePayToken`; same verified v1.02 body shape as credit card. Live verification needs a real Wallet-enabled device.
+- **Google Pay**: `client.google_pay.create_payment` (sync + async). Same pattern with `googlePayToken`. Live verification needs a real Google Pay-enabled device.
+- **Pay By Link**: `client.pay_by_link.create_payment` (sync + async). Generates an eupago-hosted checkout URL where the customer picks the payment method (MB WAY, Multibanco, Card, Apple/Google Pay, Cofidis…). Supports optional `expires_at`, `shipping`, `products` line items, and `customer` notification. Body shape verified against the v1.02 reference and live against the sandbox (`tests/integration/test_pay_by_link_live.py`).
+- New `e2e` optional extra (`pip install eupago[e2e]`) — Playwright dep for the headless 3DS test.
+- **`EupagoClient(webhook_secret=...)`** and a **`client.webhooks.parse(body, headers)`** namespace (Stripe-style configuration on the client; the module-level `parse_webhook` stays as the escape hatch).
+- **Encrypted webhook support** (AES-256-CBC) — auto-detected from `X-Initialization-Vector` and the `{"data": "..."}` body shape, validated end-to-end against a real encrypted payload from the sandbox. New `crypto` extra (`pip install eupago[crypto]`).
+- `currency` parameter on MB WAY create/authorize (defaults to `EUR`).
+- Comprehensive typed exception hierarchy with `status_code`, `error_code` (now `int | str | None`) and `message`.
+- PII redaction filter (`_logging.py`) — phone, email, NIF.
+- Audit hook (`client.set_audit_hook(...)`).
+- Headless integration test suite (`tests/integration/`) with a Terraform-managed AWS webhook receiver (Lambda + API Gateway + DynamoDB) and a sandbox-backoffice automation helper, so every paid flow is exercised end-to-end without manual clicks.
+- Lifecycle examples covering every payment method (`examples/01`–`12`): MB WAY (payment, auth+capture), Multibanco (reference, get_info), Credit Card (payment, auth+capture, subscription+charge), Apple Pay, Google Pay, Pay By Link, and a standalone Refund flow — each ending with the refund pattern so the full pay → refund cycle is visible end to end.
+
+### Changed
+- Auth header is now **`Authorization: ApiKey <key>`** (not a header named `ApiKey`). Affects every v1.02 endpoint.
+- Error responses with **string** `code` (e.g. `APIKEY_MISSING`) no longer crash the error path; the message in the `text` field is surfaced.
+- MB WAY create request: `amount` is now `{value, currency}` (object), and the phone goes in `payment.customerPhone` (not `alias`).
+- Webhook v2.0 parsing: `transaction` (singular) — the previously-assumed `transactions` (plural) was incorrect.
+- Webhook signature: `X-Signature` is **base64**(HMAC-SHA256), not hex. For encrypted channels the HMAC payload is the **base64 ciphertext string** (the value of `data`); for cleartext channels it is the **raw body**. Both schemes are auto-detected.
+- AES key for encrypted webhooks: the channel's *Chave Criptográfica* is the **32-byte AES-256 key directly** (UTF-8 bytes). It is not a passphrase to derive with SHA-256.
+- Multibanco `get_info`: paid detection now uses the `estado_referencia == "paga"` field and the `pagamentos` array (the old `data_pagamento`-only heuristic returned PENDING for actually-paid references).
+- Multibanco `order_id` is read from `identificador` (not `id`).
+- v0.6.0 roadmap entry refocused to **webhook docs/recipes only** — no framework adapters, matching Stripe/Mollie.
+
+### Removed
+- The premature `Credit Card`, `Apple Pay` and `Google Pay` scaffolding (services, tests, examples, docs) — they were ahead of the v0.3.0 phase. They will return when that milestone starts.
+
+### Fixed
+- `MB WAY` request body shape against the real v1.02 API (confirmed via sandbox).
+- Webhook decryption error message now points at the `crypto` extra.
+
+## [0.0.1] - 2026-05-26
+- Initial scaffolding.

eupago-0.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,34 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer at breathpilatestudio@gmail.com.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

eupago-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+pytest
+```
+
+## Running checks
+
+```bash
+ruff check .          # lint
+ruff format .         # format
+mypy src/             # type check
+pytest                # tests (coverage enforced ≥85%)
+```
+
+## Pull requests
+
+- One feature or fix per PR
+- Include tests for new code
+- Update CHANGELOG.md under `[Unreleased]`
+- All CI checks must pass (lint, types, tests across Python 3.9–3.13)
+
+## Test discipline (please read)
+
+Two layers, **both required** for new wire-touching code:
+
+- **Unit** (`tests/unit/`) — mock httpx with `respx` and **assert the exact request body** sent on the wire, not just the return value. This is what catches wrong field names / shapes / required-but-missing fields. Coverage gate ≥85%.
+- **Live** (`tests/integration/`) — exercise the operation against the real eupago sandbox (skipped automatically when env vars are missing). When the upstream channel doesn't have a feature provisioned, use `pytest.skip("clear reason …")` rather than letting the test pass silently.
+
+For the README / CHANGELOG / roadmap, status is **per operation** (not per service). `service.create_payment` being live-validated does not entitle `service.authorize` to a green check. See the matrix style in `README.md` for the convention.
+
+## Reporting security issues
+
+See [SECURITY.md](SECURITY.md) — do not open a public issue for vulnerabilities.

eupago-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Bilouro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eupago-0.5.0/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: eupago
+Version: 0.5.0
+Summary: Unofficial Python SDK for the eupago payment gateway
+Project-URL: Homepage, https://github.com/bilouro/eupago-python
+Project-URL: Documentation, https://bilouro.github.io/eupago-python/
+Project-URL: Issues, https://github.com/bilouro/eupago-python/issues
+Project-URL: Changelog, https://github.com/bilouro/eupago-python/blob/main/CHANGELOG.md
+Author: Victor Bilouro
+License: MIT
+License-File: LICENSE
+Keywords: eupago,mbway,multibanco,payments,portugal
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: crypto
+Requires-Dist: cryptography>=42.0; extra == 'crypto'
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: cryptography>=42.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.0; extra == 'django'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocs-static-i18n; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: e2e
+Requires-Dist: playwright>=1.40; extra == 'e2e'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Provides-Extra: integration
+Requires-Dist: boto3>=1.34; extra == 'integration'
+Description-Content-Type: text/markdown
+
+# eupago
+
+[![PyPI version](https://img.shields.io/pypi/v/eupago)](https://pypi.org/project/eupago/)
+[![Python versions](https://img.shields.io/pypi/pyversions/eupago)](https://pypi.org/project/eupago/)
+[![CI](https://github.com/bilouro/eupago-python/actions/workflows/test.yml/badge.svg)](https://github.com/bilouro/eupago-python/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Typed](https://img.shields.io/badge/typed-mypy--strict-blue)](https://mypy.readthedocs.io/)
+[![Docs](https://img.shields.io/badge/docs-bilouro.github.io-blue)](https://bilouro.github.io/eupago-python/)
+
+The first Python SDK for [eupago](https://www.eupago.com), Portugal's payment gateway.
+MB WAY, Multibanco, and more — in 5 lines of Python.
+
+**[Documentation (PT/EN)](https://bilouro.github.io/eupago-python/)** | [Examples](examples/) | [API Reference](https://bilouro.github.io/eupago-python/api/)
+
+> **Community SDK** — not affiliated with or endorsed by eupago.
+> For official integrations, visit [eupago.com](https://www.eupago.com/integrations/api-payment-gateway).
+
+## Status
+
+Per-operation coverage. **Unit** = `respx`-mocked unit test asserting the wire body.
+**Sandbox** = integration test against the eupago sandbox.
+**Prod** = real production transaction exercised against a live eupago channel
+on 2026-05-31 (real money moved + verified back via webhook).
+
+| Operation | Unit | Sandbox | Prod |
+|---|:-:|:-:|:-:|
+| `mbway.create_payment` (sync + async) | ✅ | ✅ | ✅ |
+| `mbway.authorize` / `capture` (sync + async) | ✅ | ⚠️ skip — channel needs *Auth & Capture* | — |
+| `multibanco.create_reference` (sync + async) | ✅ | ✅ | ✅ |
+| `multibanco.get_info` (sync + async) | ✅ | ✅ | — |
+| `credit_card.create_payment` (sync + async, 3DS) | ✅ | ✅ Playwright drives Shift4 + Credorax | — |
+| `credit_card.authorize` / `capture` (sync + async) | ✅ | ⚠️ skip — channel needs *Auth & Capture* | — |
+| `credit_card.create_subscription` / `charge_subscription` (sync + async) | ✅ | ⚠️ partial — channel needs *Subscription* feature | — |
+| `credit_card.list_subscriptions` / `get_subscription` / `edit_subscription` / `revoke_subscription` (sync + async) | ✅ | ✅ | — |
+| `apple_pay.create_payment` (sync + async) | ✅ | ❌ needs a real Apple Wallet token | — |
+| `google_pay.create_payment` (sync + async) | ✅ | ❌ needs a real Google Pay token | — |
+| `pay_by_link.create_payment` (sync + async) | ✅ | ✅ URL only | ✅ |
+| `refunds.refund` (sync + async) | ✅ | ✅ | ✅ |
+| `refunds.get` (sync + async) | ✅ | ✅ | ✅ |
+| Webhooks v2.0 (POST + HMAC, cleartext **and** AES-256-CBC encrypted) | ✅ | ✅ | ✅ |
+| Refund webhook (`method="RB:PT"`, links via `original_transaction_id`) | ✅ | — | ✅ |
+| Webhooks v1.0 (legacy GET) | ✅ | — | — |
+| HTTP transport (retry, audit hook, PII redaction, form-urlencoded support) | ✅ | — | — |
+
+Discovered in production and now mapped: `"Canceled"` (US 1-L spelling) → `CANCELLED`,
+`"REFUNDED"` (uppercase) → `REFUNDED`, `"RB:PT"` → method `"refund"`. Multibanco
+refunds settle async (`"Pendente"` → `"Reembolsado"` later via webhook). Pay By
+Link expiry is **silent** — no webhook, link becomes a generic 404 page; track
+`expires_at` yourself.
+
+Planned: Direct Debit, Payshop, Cofidis, Floa, PIX, Pagaqui, Paysafecard.
+
+## Installation
+
+```bash
+pip install eupago
+```
+
+Requires Python 3.9+. Runtime deps: [httpx](https://www.python-httpx.org/)
+and [Pydantic v2](https://docs.pydantic.dev/). Add the `crypto` extra
+(`pip install eupago[crypto]`) only if you receive encrypted webhooks.
+
+## Quick Start
+
+```python
+from decimal import Decimal
+from eupago import EupagoClient
+
+client = EupagoClient(
+    api_key="xxxx-xxxx-xxxx-xxxx-xxxx",
+    sandbox=True,  # False for production
+)
+
+# MB WAY — direct mobile payment
+payment = client.mbway.create_payment(
+    order_id="ORD-2026-001",
+    amount=Decimal("49.90"),
+    phone_number="912345678",  # 9-digit Portuguese MB WAY number
+)
+
+print(payment.transaction_id)  # "txn-abc-123"
+print(payment.status)          # PaymentStatus.PENDING
+print(payment.amount)          # Decimal("49.90")
+```
+
+```python
+# Multibanco — entity + reference for ATM/homebanking
+ref = client.multibanco.create_reference(
+    order_id="ORD-2026-002",
+    amount=Decimal("99.00"),
+)
+print(ref.entity, ref.reference)   # "12345", "999888777"
+```
+
+## Async Support
+
+Every method has an async variant — same client, `_async` suffix:
+
+```python
+async with EupagoClient(api_key="...", sandbox=True) as client:
+    payment = await client.mbway.create_payment_async(
+        order_id="ORD-2026-001",
+        amount=Decimal("49.90"),
+        phone_number="912345678",
+    )
+```
+
+## Auth & Capture (MB WAY)
+
+For two-step payments (authorize first, capture later):
+
+```python
+auth = client.mbway.authorize(
+    order_id="ORD-002",
+    amount=Decimal("120.00"),
+    phone_number="912345678",
+)
+
+captured = client.mbway.capture(
+    transaction_id=auth.transaction_id,
+    amount=Decimal("120.00"),
+)
+```
+
+## Webhooks
+
+Configure the secret once on the client; `client.webhooks.parse` handles both
+cleartext **and** AES-256-CBC encrypted payloads — the SDK auto-detects from
+the headers:
+
+```python
+client = EupagoClient(
+    api_key="…",
+    webhook_secret="…",   # the channel's "Chave Criptográfica"
+)
+
+# v2.0 — POST with HMAC signature; decrypts automatically if the channel encrypts
+event = client.webhooks.parse(body=request.body, headers=request.headers)
+
+# v1.0 — legacy GET query string
+event = client.webhooks.parse(query_params=dict(request.query_params))
+
+print(event.order_id)   # "ORD-2026-001"
+print(event.status)     # PaymentStatus.PAID
+print(event.amount)     # Decimal("49.90")
+print(event.method)     # "mbway"
+```
+
+The module-level `eupago.webhooks.parse_webhook(...)` is still available as
+an escape hatch for multi-channel cases that need to pick a secret per call.
+
+## Error Handling
+
+All errors inherit from `EupagoError` with typed subclasses:
+
+```python
+from eupago import EupagoClient, AuthenticationError, PaymentError, NetworkError
+
+try:
+    payment = client.mbway.create_payment(...)
+except AuthenticationError:
+    # Invalid API key
+    ...
+except PaymentError as e:
+    print(e.status_code, e.error_code, e.message)
+except NetworkError:
+    # Timeout, connection refused
+    ...
+```
+
+## Configuration
+
+```python
+client = EupagoClient(
+    api_key="xxxx-xxxx-xxxx-xxxx-xxxx",
+    webhook_secret="…",     # The channel's Chave Criptográfica (HMAC + AES key)
+    sandbox=True,           # Use sandbox environment (default: False)
+    timeout=10.0,           # Request timeout in seconds (default: 10)
+    max_retries=3,          # Retry failed GET requests (default: 3)
+    # OAuth credentials for management endpoints (refunds, transactions)
+    client_id="...",
+    client_secret="...",
+)
+
+# Audit hook — log every API call to your DB / observability stack
+client.set_audit_hook(
+    lambda request, response, duration_ms: log_api_call(request, response, duration_ms)
+)
+```
+
+## Why This SDK
+
+- **Fully typed** — `mypy --strict` passes, `py.typed` marker included. Full autocomplete in VS Code and PyCharm.
+- **Sync + Async** — one client, no separate packages. httpx powers both.
+- **Decimal amounts** — no floating-point surprises with money.
+- **Safe retries** — GET requests retry with exponential backoff + jitter. POSTs never retry (no idempotency keys = risk of duplicate payments).
+- **PII redaction** — phone, email and NIF are auto-redacted from logs.
+- **Webhook verification** — HMAC-SHA256 constant-time signature; AES-256-CBC decryption when the channel encrypts. Both schemes verified against real eupago payloads.
+- **Unified vocabulary** — eupago's API has two generations with inconsistent field names (`valor`/`amount`, `chave`/`ApiKey`). The SDK normalizes everything to consistent English.
+- **Exception hierarchy** — catch `PaymentError`, `NetworkError`, or `EupagoError`. Each carries `status_code`, `error_code` and `message`.
+
+## Development
+
+```bash
+git clone https://github.com/bilouro/eupago-python.git
+cd eupago-python
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+```
+
+Run checks:
+
+```bash
+ruff check .          # lint
+ruff format .         # format
+mypy src/             # type check (strict)
+pytest                # tests with coverage (≥85% enforced)
+```
+
+The default `pytest` runs unit tests only. Live integration tests against the
+sandbox live under `tests/integration/` — see `tests/integration/infra/README.md`
+for the Terraform-managed AWS receiver they need.
+
+## Contributing
+
+PRs are welcome — especially for new payment methods on the roadmap, framework
+recipes, docs improvements, or anything that makes the SDK easier to adopt.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Production use / Consulting
+
+This is a community SDK. If you're integrating it into a production system and
+want **prioritised features, custom payment methods, audit support, or hands-on
+help with eupago's quirks**, you can reach me at **consulting@bilouro.com** —
+happy to help on a paid consulting basis.
+
+For general questions, file an issue.
+
+## Security
+
+Report vulnerabilities privately — see [SECURITY.md](SECURITY.md). Do not open
+public issues for security bugs.
+
+## License
+
+[MIT](LICENSE) — use it however you want.