Metadata-Version: 2.5
Name: pywayforpay
Version: 0.2.1
Summary: Strongly typed WayForPay PSP API SDK (msgspec-based, sync + async)
Project-URL: Documentation, https://wiki.wayforpay.com/en/
Project-URL: Repository, https://github.com/HermanPlay/pywayforpay
Author: Filip Shramko
License: MIT
License-File: LICENSE
Keywords: api,msgspec,payment-gateway,payments,psp,sdk,wayforpay
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: msgspec>=0.18
Description-Content-Type: text/markdown

# pywayforpay

[![CI](https://img.shields.io/github/actions/workflow/status/HermanPlay/pywayforpay/ci.yml?branch=master&label=CI)](https://github.com/HermanPlay/pywayforpay/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/HermanPlay/pywayforpay/graph/badge.svg?token=8V2RQUJEMM)](https://codecov.io/gh/HermanPlay/pywayforpay)
[![Python](https://img.shields.io/pypi/pyversions/pywayforpay)](https://pypi.org/project/pywayforpay/)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://HermanPlay.github.io/pywayforpay/)

Strongly typed [WayForPay](https://wiki.wayforpay.com/en/) PSP API SDK for Python (3.11+),
built on [msgspec](https://msgspec.dev/) with explicit structs, HMAC-MD5 signature handling,
and sync + async [httpx](https://www.python-httpx.org/) clients.

## Features

- **Payments** — purchase (redirect form, widget, offline link), verify, charge (host-to-host),
  3-DS completion, settle, refund, invoices, QR, P2P transfers, currency rates.
- **Recurring payments** — status, suspend, resume, remove, change.
- **Reporting** — check status, transaction list.
- **Merchant management (MMS)** — merchants, partners, balances.
- **Antifraud** — validate and check status.
- **Webhooks** — verify callbacks and acks, build acks.
- Fully typed (`py.typed`), documented, sync + async APIs in lockstep.

## Installation

```bash
pip install pywayforpay
```

Requires Python 3.11+.

## Quickstart

```python
from wayforpay import Client, Credentials, money
from wayforpay.models import PurchaseRequest, Product, Currency

creds = Credentials(
    merchant_account="test_merch_n1",
    merchant_secret_key="flk3409refn54t54t*FNJRET",
    merchant_domain_name="www.market.ua",
)

product = Product(name="Dell XPS", price=money("1547.36"), count=1)
request = PurchaseRequest.from_products(
    order_reference="DH783023",
    order_date=1415379863,
    amount=money("1547.36"),
    currency=Currency.UAH,
    products=[product],
)

with Client(creds) as client:
    url = client.purchase_url()            # https://secure.wayforpay.com/pay
    form = client.purchase_form(request)   # signed POST payload for the payment page
```

Render `form` as hidden fields inside `<form action="{url}" method="POST">`.

Async mirrors sync:

```python
import asyncio
from wayforpay import AsyncClient, Credentials

async def main() -> None:
    async with AsyncClient(creds) as client:
        result = await client.check_status(CheckStatusRequest(order_reference="DH783023"))

asyncio.run(main())
```

## Examples

Runnable examples live in [`examples/`](examples/):

```bash
uv run python examples/purchase_form.py   # signed purchase form + HTML snippet
uv run python examples/widget.py          # payment-widget config
uv run python examples/webhooks.py        # callback verification + ack
uv run python examples/verify_form.py     # card verification form
uv run python examples/async_api.py       # async client (dry-run; add --live)
uv run python examples/charge.py          # host-to-host charge (dry-run; add --live)
```

## Documentation

Full documentation is available at <https://HermanPlay.github.io/pywayforpay/>.

- [Quickstart](https://HermanPlay.github.io/pywayforpay/quickstart/)
- [Payments](https://HermanPlay.github.io/pywayforpay/payment-flows/)
- [Payment widget](https://HermanPlay.github.io/pywayforpay/widget/)
- [Webhooks](https://HermanPlay.github.io/pywayforpay/webhooks/)
- [Recurring payments](https://HermanPlay.github.io/pywayforpay/recurring/)
- [Merchant management (MMS)](https://HermanPlay.github.io/pywayforpay/mms/)
- [Antifraud](https://HermanPlay.github.io/pywayforpay/antifraud/)
- [Errors & reason codes](https://HermanPlay.github.io/pywayforpay/errors/)
- [PCI DSS](https://HermanPlay.github.io/pywayforpay/pci-dss/)
- [API reference](https://HermanPlay.github.io/pywayforpay/api/clients/)

WayForPay API docs: <https://wiki.wayforpay.com/en/>

## PCI DSS

This library exposes host-to-host card operations (`ChargeRequest`, `CardData`).
Handling raw card data carries PCI DSS obligations; the merchant/integrator remains
responsible for compliance. Prefer the hosted payment widget or redirect form to avoid
touching card data. See the [PCI DSS guide](https://HermanPlay.github.io/pywayforpay/pci-dss/).

## Development

Install dev deps: `uv sync`.

### Conventional commits

Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
(`feat:`, `fix:`, `docs:`, `refactor:`, `ci:`, ...). The `commit-lint` CI job checks
every commit in a PR (and the PR title) with commitizen and fails on violations.

The `master` branch is protected by a GitHub ruleset (`scripts/apply-protection.sh`):

- direct pushes and force-pushes to `master` are rejected — all changes go through PRs;
- a PR needs one approving review and a green `commit-lint` check before merge.

So the remote rejects non-conventional commits even if a contributor skips local hooks.
The pre-commit hook is convenience only:

```bash
uv run pre-commit install --hook-type commit-msg   # one-time local setup
```

### Releases

Publishing creates a version tag, a GitHub release with a changelog generated from
the commit log, and a PyPI package published via trusted publishing (OIDC).

1. Bump the version and tag it:

   ```bash
   uv run cz bump
   ```

   Bumps `pyproject.toml`, `__init__.py` and `uv.lock`, updates `CHANGELOG.md`, and
   creates a `vX.Y.Z` tag. Add `--yes --increment patch|minor|major` to skip the
   interactive prompt (e.g. in scripts/CI).

2. Push the tag:

   ```bash
   git push origin master --tags
   ```

   The `release` workflow builds the changelog for the tag and creates a GitHub
   release. The `publish` workflow then publishes the package to PyPI.

#### One-time PyPI setup (trusted publishing)

The `publish` workflow uses PyPI trusted publishing (OIDC) — no API tokens stored.

- Enable 2FA on your PyPI and TestPyPI accounts (PyPI policy requirement).
- Register the project `pywayforpay` on PyPI (and TestPyPI).
- Add a trusted publisher on each: owner `HermanPlay`, repository `pywayforpay`,
  workflow file `publish.yml`, environment `release`.

To validate a release against TestPyPI first, trigger the `publish` workflow manually
with repository `testpypi` (Actions tab → Publish to PyPI → Run workflow).

## License

[MIT](LICENSE)