Skip to content

Commit 7075b2d

Browse files
dekozadekoza
committed
docs: add PyPI-ready README
1 parent ce8dba5 commit 7075b2d

File tree

1 file changed

+83
-103
lines changed

1 file changed

+83
-103
lines changed

‎README.md‎

Lines changed: 83 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,81 @@
1-
# getpaid-przelewy24
1+
# python-getpaid-przelewy24
22

3-
[![PyPI](https://img.shields.io/pypi/v/python-getpaid-przelewy24.svg)](https://pypi.org/project/python-getpaid-przelewy24/)
4-
[![Python Version](https://img.shields.io/pypi/pyversions/python-getpaid-przelewy24)](https://pypi.org/project/python-getpaid-przelewy24/)
5-
[![License](https://img.shields.io/pypi/l/python-getpaid-przelewy24)](https://github.com/django-getpaid/python-getpaid-przelewy24/blob/main/LICENSE)
3+
[![PyPI version](https://img.shields.io/pypi/v/python-getpaid-przelewy24.svg)](https://pypi.org/project/python-getpaid-przelewy24/)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5+
[![Python versions](https://img.shields.io/pypi/pyversions/python-getpaid-przelewy24.svg)](https://pypi.org/project/python-getpaid-przelewy24/)
66

7-
[Przelewy24](https://www.przelewy24.pl/) payment gateway plugin for the
8-
[python-getpaid](https://github.com/django-getpaid) ecosystem. Provides an
9-
async HTTP client (`P24Client`) and a payment processor (`P24Processor`) that
10-
integrates with getpaid-core's `BaseProcessor` interface. Authentication uses
11-
HTTP Basic Auth against the Przelewy24 REST API.
7+
**Przelewy24 payment processor for the [python-getpaid](https://github.com/django-getpaid/python-getpaid-core) ecosystem.**
128

13-
## Architecture
9+
[Przelewy24](https://www.przelewy24.pl/) is a leading Polish payment service provider that supports a wide range of payment methods, including bank transfers (pay-by-link), credit cards, and e-wallets (BLIK, Google Pay, Apple Pay).
1410

15-
The plugin is split into two layers:
11+
This package provides a clean, async-first integration with the Przelewy24 REST API v1.1, implementing the standard `python-getpaid` processor interface.
1612

17-
- **`P24Client`** — low-level async HTTP client wrapping the Przelewy24 REST
18-
API. Uses `httpx.AsyncClient` with HTTP Basic Auth (pos_id / api_key). Can be
19-
used standalone or as an async context manager for connection reuse.
20-
- **`P24Processor`** — high-level payment processor implementing
21-
`BaseProcessor`. Orchestrates transaction registration, callback verification,
22-
payment confirmation, status polling, and refunds. Integrates with the
23-
getpaid-core FSM for state transitions.
13+
## Features
2414

25-
## Key Features
15+
- **Direct Payment Flow**: Full implementation of the `register -> redirect -> notification -> verify` flow.
16+
- **Secure by Default**: Automatic signature verification (SHA-384) for all incoming notifications from Przelewy24.
17+
- **Async-First**: Built on top of `httpx` for efficient, non-blocking I/O.
18+
- **Multi-Currency Support**: PLN, EUR, GBP, USD, CZK, BGN, DKK, HUF, NOK, SEK, CHF, RON, HRK.
19+
- **Sandbox Support**: Easy switching between Sandbox and Production environments.
20+
- **Payment Status Polling**: Support for the PULL flow to check transaction status via API.
21+
- **Refunds**: Full support for processing refunds through the Przelewy24 API.
22+
- **FSM Integration**: Seamlessly integrates with the `python-getpaid-core` finite state machine for robust payment state management.
2623

27-
- **Register transaction** — create a payment session and get a redirect URL
28-
- **Verify transaction** — mandatory confirmation after P24 callback (without
29-
this, P24 treats the payment as advance only)
30-
- **Refund** — batch refund support via P24 API
31-
- **Get transaction info** — look up transaction by session ID
32-
- **Get refund info** — look up refunds by P24 order ID
33-
- **Get payment methods** — retrieve available payment methods for a language
34-
- **Test access** — verify API credentials
35-
- **PUSH and PULL** — callback-based notifications with optional status polling
36-
- **SHA-384 signatures** — automatic sign calculation and verification
24+
## Installation
3725

38-
## Quick Usage
26+
Install the package using `pip`:
3927

40-
### Standalone Client
28+
```bash
29+
pip install python-getpaid-przelewy24
30+
```
31+
32+
Or using `uv`:
33+
34+
```bash
35+
uv add python-getpaid-przelewy24
36+
```
37+
38+
## Quick Start
39+
40+
### Configuration
41+
42+
Add `przelewy24` to your `python-getpaid` configuration. For example, in a Django project using `django-getpaid`:
43+
44+
```python
45+
GETPAID_BACKEND_SETTINGS = {
46+
"przelewy24": {
47+
"merchant_id": 12345,
48+
"pos_id": 12345, # Usually the same as merchant_id
49+
"api_key": "your_api_key_here",
50+
"crc_key": "your_crc_key_here",
51+
"sandbox": True, # Use True for testing, False for production
52+
"url_status": "https://your-domain.com/payments/p24/status/{payment_id}/",
53+
"url_return": "https://your-domain.com/payments/p24/return/{payment_id}/",
54+
}
55+
}
56+
```
57+
58+
### Configuration Parameters
59+
60+
| Key | Type | Description |
61+
|-----|------|-------------|
62+
| `merchant_id` | `int` | Your Przelewy24 Merchant ID. |
63+
| `pos_id` | `int` | Your Przelewy24 POS ID (defaults to `merchant_id`). |
64+
| `api_key` | `str` | REST API Key from the Przelewy24 panel. |
65+
| `crc_key` | `str` | CRC Key from the Przelewy24 panel (used for signing). |
66+
| `sandbox` | `bool` | If `True` (default), uses the P24 Sandbox environment. |
67+
| `url_status` | `str` | Callback URL for asynchronous notifications. Supports `{payment_id}`. |
68+
| `url_return` | `str` | Return URL after payment completion. Supports `{payment_id}`. |
69+
| `refund_url_status` | `str` | (Optional) Callback URL for refund status notifications. |
70+
71+
Both `url_status`, `url_return`, and `refund_url_status` can include the `{payment_id}` placeholder, which will be automatically replaced with the actual payment ID.
72+
73+
## Standalone Usage
74+
75+
While designed to work with `python-getpaid` framework wrappers, you can also use the `P24Client` directly:
4176

4277
```python
43-
import anyio
78+
import asyncio
4479
from decimal import Decimal
4580
from getpaid_przelewy24 import P24Client
4681

@@ -52,96 +87,41 @@ async def main():
5287
crc_key="your-crc-key",
5388
sandbox=True,
5489
) as client:
55-
# Test connection
56-
ok = await client.test_access()
57-
print(f"Connection OK: {ok}")
58-
5990
# Register a transaction
6091
response = await client.register_transaction(
6192
session_id="order-001",
6293
amount=Decimal("49.99"),
6394
currency="PLN",
6495
description="Order #001",
6596
email="buyer@example.com",
66-
url_return="https://shop.example.com/return/order-001",
67-
url_status="https://shop.example.com/callback/order-001",
97+
url_return="https://shop.example.com/return/",
98+
url_status="https://shop.example.com/callback/",
6899
)
69100
token = response["data"]["token"]
70-
redirect_url = client.get_transaction_redirect_url(token)
71-
print(f"Redirect buyer to: {redirect_url}")
101+
print(f"Redirect URL: {client.get_transaction_redirect_url(token)}")
72102

73-
anyio.run(main)
103+
if __name__ == "__main__":
104+
asyncio.run(main())
74105
```
75106

76-
### With django-getpaid
77-
78-
Register the plugin via entry point in `pyproject.toml`:
79-
80-
```toml
81-
[project.entry-points."getpaid.backends"]
82-
przelewy24 = "getpaid_przelewy24.processor:P24Processor"
83-
```
84-
85-
Then configure in your Django settings (or config dict):
86-
87-
```python
88-
GETPAID_BACKEND_SETTINGS = {
89-
"przelewy24": {
90-
"merchant_id": 12345,
91-
"pos_id": 12345,
92-
"api_key": "your-api-key",
93-
"crc_key": "your-crc-key",
94-
"sandbox": True,
95-
"url_status": "https://shop.example.com/payments/{payment_id}/callback/",
96-
"url_return": "https://shop.example.com/payments/{payment_id}/return/",
97-
"refund_url_status": "https://shop.example.com/payments/{payment_id}/refund-callback/",
98-
}
99-
}
100-
```
101-
102-
## Configuration Reference
103-
104-
| Key | Type | Default | Description |
105-
|-----|------|---------|-------------|
106-
| `merchant_id` | `int` | *required* | Merchant ID from P24 panel |
107-
| `pos_id` | `int` | *required* | POS ID (often same as merchant_id) |
108-
| `api_key` | `str` | *required* | REST API key from P24 panel |
109-
| `crc_key` | `str` | *required* | CRC key for signature calculation |
110-
| `sandbox` | `bool` | `True` | Use sandbox (`sandbox.przelewy24.pl`) or production (`secure.przelewy24.pl`) |
111-
| `url_status` | `str` | `""` | Callback URL template; use `{payment_id}` placeholder |
112-
| `url_return` | `str` | `""` | Return URL template; use `{payment_id}` placeholder |
113-
| `refund_url_status` | `str` | `""` | Refund callback URL template; use `{payment_id}` placeholder |
114-
115-
## Supported Currencies
116-
117-
PLN, EUR, GBP, CZK, USD, BGN, DKK, HUF, NOK, SEK, CHF, RON, HRK (13 total).
118-
119-
## Limitations
120-
121-
Przelewy24 does not support pre-authorization. The `charge()` and
122-
`release_lock()` methods raise `NotImplementedError`.
123-
124107
## Requirements
125108

126-
- Python 3.12+
127-
- `python-getpaid-core >= 0.1.0`
109+
- Python 3.12 or 3.13
110+
- `python-getpaid-core >= 3.0.0a2`
128111
- `httpx >= 0.27.0`
129112

130-
## Related Projects
131-
132-
- [python-getpaid-core](https://github.com/django-getpaid/python-getpaid-core) — core abstractions (protocols, FSM, processor base class)
133-
- [django-getpaid](https://github.com/django-getpaid/django-getpaid) — Django adapter (models, views, admin)
134-
135113
## License
136114

137-
MIT
138-
139-
## Disclaimer
115+
This project is licensed under the MIT License.
140116

141-
This project has nothing in common with the
142-
[getpaid](http://code.google.com/p/getpaid/) plone project.
143-
It is part of the `django-getpaid` / `python-getpaid` ecosystem.
117+
## Links
144118

145-
## Credits
119+
- [python-getpaid-core](https://github.com/django-getpaid/python-getpaid-core)
120+
- [django-getpaid](https://github.com/django-getpaid/django-getpaid)
121+
- [litestar-getpaid](https://github.com/django-getpaid/litestar-getpaid)
122+
- [fastapi-getpaid](https://github.com/django-getpaid/fastapi-getpaid)
123+
- [Przelewy24 API Documentation](https://developers.przelewy24.pl/)
146124

125+
---
147126
Created by [Dominik Kozaczko](https://github.com/dekoza).
127+
Part of the `python-getpaid` ecosystem.

0 commit comments

Comments
 (0)