Metadata-Version: 2.4
Name: mongolian-payment-paylink
Version: 1.0.0
Summary: PayLink card payment SDK for Python
Project-URL: Homepage, https://github.com/mongolian-payment/paylink-py
Project-URL: Repository, https://github.com/mongolian-payment/paylink-py
Project-URL: Issues, https://github.com/mongolian-payment/paylink-py/issues
Author: mongolian-payment
License-Expression: MIT
Keywords: card,mongolia,paylink,payment,sdk
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# mongolian-payment-paylink

PayLink card payment SDK for Python — create invoices, query transactions, run reports.

Wraps the PayLink External API (single `POST /external/process` endpoint, process-code driven).

## Installation

```bash
pip install mongolian-payment-paylink
```

Requires Python >= 3.8. Depends on `httpx`.

## Quick Start

```python
from mongolian_payment_paylink import PayLinkClient, PayLinkConfig, CreateInvoiceInput

client = PayLinkClient(PayLinkConfig(
    base_url="https://paylink.mn/api/v1",   # test: https://pay-link.fiba.mn/api/v1
    username="MERCHANT_USERNAME",
    signature_key="YOUR_SIGNATURE_KEY",
))

invoice = client.create_invoice(CreateInvoiceInput(
    amount_total=10000,
    count_total=1,
    amount=10000,
    description="Order #123",
    merchant_ref="ORDER-123",
))
print(invoice.payment_link)   # redirect the buyer here
print(invoice.invid)
```

### Async

```python
import asyncio
from mongolian_payment_paylink import AsyncPayLinkClient, PayLinkConfig

async def main():
    async with AsyncPayLinkClient(PayLinkConfig(
        base_url="https://paylink.mn/api/v1",
        username="MERCHANT_USERNAME",
        signature_key="YOUR_SIGNATURE_KEY",
    )) as client:
        detail = await client.get_invoice("INV-123")
        print(detail["status"])

asyncio.run(main())
```

## Authentication & signing

Every request sends three headers: `pc` (process code), `X-USERNAME`, and `X-SIGNATURE`.

> **Note on the signature.** PayLink's exact signing scheme is not published. By
> default this SDK signs the **HMAC-SHA256 (hex) of the JSON request body**, keyed
> by `signature_key`. If PayLink specifies a different scheme, pass your own
> `sign` function — it receives the exact body string and returns the signature:
>
> ```python
> PayLinkConfig(base_url=..., username=..., sign=lambda body: my_signature(body))
> ```

## Environment variables

```bash
PAYLINK_BASE_URL=https://paylink.mn/api/v1
PAYLINK_USERNAME=MERCHANT_USERNAME
PAYLINK_SIGNATURE_KEY=your-signature-key
```

```python
from mongolian_payment_paylink import PayLinkClient, load_config_from_env
client = PayLinkClient(load_config_from_env())
```

## Methods

| Method | Process code | Description |
|--------|--------------|-------------|
| `create_invoice(input)` | cu0900 | Create an invoice → `CreatedInvoice` |
| `list_invoices(input)` | cu0901 | List invoices |
| `get_invoice(invid)` | cu0904 | Invoice detail incl. transactions |
| `cancel_invoice(invid)` | cu0905 | Cancel an invoice |
| `batch_mark_paid(invid)` | cu0906 | Batch mark an invoice paid |
| `invoice_report(input)` | cu0907 | Paginated invoice report |
| `invoice_summary(input)` | cu0908 | Invoice summary counters |
| `transaction_report(input)` | cu0909 | Paginated transaction report |
| `transaction_summary(input)` | cu0910 | Transaction summary counters |

List/report/summary results are returned as plain dicts/lists exactly as the API
sends them (snake_case keys). `create_invoice` maps to the `CreatedInvoice` dataclass.

Dates use the `YYYY-MM-DD HH24:MI:SS` format.

## Endpoints

| Environment | Base URL |
|-------------|----------|
| Production | `https://paylink.mn/api/v1` |
| Test | `https://pay-link.fiba.mn/api/v1` |

## Error handling

Every call returns HTTP 200; the result is driven by `response_code` (`RC000000` =
success). Non-success codes and transport errors raise `PayLinkError`:

```python
from mongolian_payment_paylink import PayLinkError

try:
    client.get_invoice("INV-404")
except PayLinkError as err:
    print(err)                 # "PayLink cu0904 failed: RC000015 - Record not found"
    print(err.response_code)   # "RC000015"
    print(err.status_code)     # set for HTTP-level failures
    print(err.response)        # raw response body
```

## License

MIT
