Metadata-Version: 2.4
Name: paylabs-sdk
Version: 1.0.3
Summary: Official Python SDK for Paylabs Virtual Account SNAP (BI SNAP) API
Project-URL: Homepage, https://paylabs.co.id
Project-URL: Documentation, https://docs.paylabs.co.id
Project-URL: Repository, https://github.com/paylabs/paylabs-python-sdk
Project-URL: Issues, https://github.com/paylabs/paylabs-python-sdk/issues
Author-email: Paylabs Developer Team <developer@paylabs.co.id>
License: MIT
License-File: LICENSE
Keywords: bi-snap,indonesia,paylabs,payment-gateway,sdk,snap-va,virtual-account,virtual-account-snap
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: pycryptodome>=3.15.0
Requires-Dist: requests>=2.28.0
Provides-Extra: async
Requires-Dist: httpx>=0.24.0; extra == 'async'
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: responses>=0.23.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Paylabs Python SDK (`paylabs-sdk`)

Official Python SDK for Paylabs Virtual Account SNAP (BI SNAP Standard) & Payment Gateway API.

[![PyPI Version](https://img.shields.io/pypi/v/paylabs-sdk.svg)](https://pypi.org/project/paylabs-sdk/)
[![Python Versions](https://img.shields.io/pypi/pyversions/paylabs-sdk.svg)](https://pypi.org/project/paylabs-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 🚀 Key Features

- 🏛️ **Virtual Account SNAP (BI SNAP Standard)**: Create Virtual Account (`/transfer-va/create-va`), check status (`/transfer-va/status`), cancel VA (`/transfer-va/delete-va`), and verify callback notification signatures with hardcoded `stringToSign` path (`/transfer-va/payment`).
- 📱 **SNAP QRIS (BI SNAP Standard)**: Generate QRIS MPM (`/qr/qr-mpm-generate`), check status (`/qr/qr-mpm-query`), and verify QRIS callback signatures (`/qr/qr-mpm-notify`).
- 💳 **Modular Payment Gateway Services**: Dedicated domain properties for Virtual Account (`client.va`), SNAP VA (`client.snap_va`), QRIS (`client.qris`), SNAP QRIS (`client.snap_qris`), E-Wallet (`client.emoney`), Credit Card (`client.credit_card`), OTC (`client.otc`), H5 Payment Link (`client.h5`), DANA Subscription (`client.dana_sub`), Credit Card Subscription (`client.cc_sub`), and Reconciliation (`client.reconcile`).
- 🔐 **RSA SHA256 Security & Log Masking**: Automated request signing (`X-SIGNATURE`), debug log sensitive data masking (`cardNo`, `CVV`, `phone`, secrets), and optional callback timestamp skew validation (`max_timestamp_skew_seconds`).
- 🌐 **Dual English & Indonesian Error Messages**: Standardized Paylabs and BI SNAP error code descriptions via `err.error_description_en` and `err.error_description_id`.
- 🐍 **Python 3.8 – 3.14 Compatible**: Tested and certified for Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14.
- ⚡ **PEP 561 Compliant**: Fully type-annotated (`py.typed`) for IDE autocompletion (VS Code / PyCharm).

---

## 📦 Installation

```bash
pip install paylabs-sdk
```

---

## 🔑 RSA Key Pair Setup

Paylabs API requires RSA 2048-bit key pairs for request signing and callback signature verification. You can generate a testing key pair using the included script:

```bash
python examples/generate_keys.py
```

This creates `private_key.pem` and `public_key.pem` in your `examples/` directory.

---

## 💻 Quickstart Usage

### 1. Initialize Client (Context Manager / Standard)

```python
from paylabs import PaylabsClient, Environment

# Option A: Using Context Manager (Recommended for auto-closing HTTP session)
with PaylabsClient(
    merchant_id="YOUR_MERCHANT_ID",
    private_key=open("private_key.pem").read(),
    public_key=open("public_key.pem").read(),
    environment=Environment.SANDBOX,  # Use Environment.PRODUCTION for live deployment
) as client:
    response = client.qris.create(amount=15000, product_name="Espresso Coffee")
    print("QR Code String:", response.get("qrCode"))

# Option B: Standard Instance
client = PaylabsClient(
    merchant_id="YOUR_MERCHANT_ID",
    private_key=open("private_key.pem").read(),
    public_key=open("public_key.pem").read(),
    environment=Environment.SANDBOX,
)
```

### 2. QRIS Transaction (Payin / SNAP)

```python
from paylabs.exceptions import PaylabsAPIError

try:
    # Standard QRIS Payin
    response = client.qris.create(
        amount=15000,
        product_name="Espresso Coffee",
        notify_url="https://your-domain.com/callback",
    )
    print("QR Code String:", response.get("qrCode"))

    # SNAP QRIS (BI SNAP Standard)
    snap_qr = client.snap_qris.generate_qr(
        amount=10000,
        notify_url="https://your-domain.com/snap-callback",
        payer="Ahmad",
    )
    print("SNAP QR Content:", snap_qr.get("qrContent"))

except PaylabsAPIError as e:
    print(f"API Error [{e.err_code}]: {e.error_description_en}")
    print(f"Indonesian Description: {e.error_description_id}")
```

### 3. Virtual Account (BCA, Mandiri, BRI, BNI, etc.)

```python
response = client.va.create(
    payment_type="BCAVA",
    amount=50000,
    product_name="Plain T-Shirt",
    payer="John Doe",
)
print("Virtual Account Number:", response.get("vaCode"))
```

### 4. H5 Payment Link

```python
response = client.h5.create(
    amount=25000,
    phone_number="081234567890",
    product_name="Game Voucher",
    redirect_url="https://your-domain.com/finish",
)
print("Payment Link URL:", response.get("url"))
```

### 5. Order Reconciliation File Download

```python
response = client.reconcile.download_order_file_url(
    pay_date="2026-06-30",
    transaction_type="10",
)
print("Download File URL:", response.get("fileUrl"))
```

### 6. Verify Webhook Callback Notification

```python
is_valid = client.verify_callback_signature(
    path="/callback",
    raw_body_or_json=raw_json_body_string,
    signature=headers.get("X-SIGNATURE"),
    timestamp=headers.get("X-TIMESTAMP"),
)

if is_valid:
    print("Valid callback from Paylabs!")
else:
    print("Invalid callback signature!")
```

---

## 📂 Webhook & Web Framework Examples

Check out full, production-ready integration examples in the `examples/` directory:
- ⚡ [FastAPI Webhook Server](examples/fastapi_webhook.py)
- 🌶️ [Flask Webhook Server](examples/flask_webhook.py)
- 🏛️ [SNAP Virtual Account Demo](examples/snap_va_payment.py)
- 💳 [Standard Virtual Account Demo](examples/va_payment.py)
- 📱 [E-Wallet Demo](examples/emoney_payment.py)
- 💳 [Credit Card Demo](examples/credit_card_payment.py)
- 🏪 [Retail Store / OTC Demo](examples/otc_payment.py)
- 🔄 [DANA Subscription Demo](examples/dana_subscription.py)
- 🔄 [Credit Card Subscription Demo](examples/cc_subscription.py)
- 📊 [Order Reconciliation Demo](examples/reconciliation.py)

---

## 🛠️ Testing & Development

### Run Unit Tests:
```bash
pip install -e .[dev]
pytest tests/ -v
```

### Type Checking & Linting:
```bash
mypy src/paylabs
ruff check .
```

### Build Distribution Package:
```bash
python -m build
twine check dist/*
```

---

## 📄 License
[MIT License](LICENSE) © Paylabs Developer Team.
