Metadata-Version: 2.4
Name: django-payments-payzum
Version: 0.1.0
Summary: Payzum provider for django-payments — accept crypto & stablecoin payments (USDC, USDT and more), non-custodial
Author-email: Payzum <dev@payzum.com>
License: MIT
Project-URL: homepage, https://github.com/payzum-dev/django-payments-payzum
Project-URL: issues, https://github.com/payzum-dev/django-payments-payzum/issues
Keywords: django,payments,django-payments,crypto,stablecoin,usdc,usdt,payzum
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django-payments>=2.0
Requires-Dist: payzum~=0.1.0
Dynamic: license-file

# django-payments-payzum

Accept **crypto and stablecoin payments** (USDC, USDT and more, multi-chain) in
any [django-payments](https://github.com/jazzband/django-payments) project
through [Payzum](https://payzum.com) — **non-custodial**: funds settle directly
to your own wallet, Payzum never takes custody.

## How it works

1. The buyer picks Payzum at checkout and is redirected to a hosted checkout
   page, where they choose the asset and chain and send the payment. No wallet
   data touches your server.
2. Crypto confirmation is **asynchronous**, so the payment is confirmed from
   Payzum's signed server-to-server notification, never from the browser
   return. A buyer who comes back while the payment is still confirming lands
   on your success page with the payment in `waiting` — the signed
   notification flips it to `confirmed`.
3. Every notification is verified with **HMAC-SHA-512 over the raw request
   bytes** (with a replay window) before a single field of it is read, and the
   invoice amount and currency are re-checked against the payment before it is
   confirmed. Redelivered notifications are a no-op, so an order is never
   fulfilled twice.

## Installation

```bash
pip install django-payments-payzum
```

Add the provider to your `PAYMENT_VARIANTS`:

```python
PAYMENT_VARIANTS = {
    "payzum": ("payments_payzum.PayzumProvider", {
        "api_key": "...",           # merchant.payzum.com → Settings → API Keys
        "webhook_secret": "...",    # shown once, at merchant creation or rotation
        "endpoint": "production",   # or "sandbox" (staging, separate API keys)
        "pay_currency": "all",      # or pin one asset, e.g. "usdcmatic"
    }),
}
```

Keep both keys out of source control (environment variables or your secret
store), like any other payment credential.

| Setting | Meaning |
|---|---|
| `api_key` | From your Payzum merchant dashboard |
| `webhook_secret` | Verifies incoming payment notifications |
| `endpoint` | `production` or `sandbox` |
| `pay_currency` | Optional. `all` lets the buyer choose; or a specific code like `usdcmatic` |

There is nothing to configure in the Payzum dashboard: the notification URL
(django-payments' own `process/<token>/` route) is sent with every invoice.
The static `process/payzum/` route also works — the payment is resolved from
the signed payload only.

## Status mapping

| Payzum invoice | django-payments |
|---|---|
| `finished` | `confirmed` (after the amount and currency check) |
| `expired`, `failed` | `rejected` — but never downgrades a confirmed payment |
| `partially_paid` | unchanged (underpaid; logged, never fulfils) |
| `waiting`, `confirming` | unchanged |
| anything unknown | acknowledged and ignored |

## Tests

```bash
pip install -e . pytest pytest-django
pytest
```

## License

MIT. The [`payzum`](https://pypi.org/project/payzum/) SDK it builds on is MIT
as well.
