paymos-sdk 1.0.0__tar.gz

paymos_sdk-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: python -m pip install --disable-pip-version-check ".[dev]"
+      - run: python -m ruff format --check .
+      - run: python -m ruff check .
+      - run: python -m mypy src/paymos
+      - run: python -m unittest discover -s tests
+      - run: python -m build
+      - name: Test the built wheel in isolation
+        run: |
+          python -m venv /tmp/paymos-smoke
+          /tmp/paymos-smoke/bin/python -m pip install --disable-pip-version-check dist/*.whl
+          cd /tmp
+          /tmp/paymos-smoke/bin/python -c "import paymos; assert paymos.VERSION"

paymos_sdk-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - name: Verify immutable release version
+        run: python -c "import os,tomllib,pathlib; actual=tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version']; expected=os.environ['GITHUB_REF_NAME'][1:]; assert actual == expected, f'tag {expected} != package {actual}'"
+      - run: python -m pip install --disable-pip-version-check ".[dev]"
+      - run: python -m ruff format --check .
+      - run: python -m ruff check .
+      - run: python -m mypy src/paymos
+      - run: python -m unittest discover -s tests
+      - run: python -m build
+      - name: Test the built wheel in isolation
+        run: |
+          python -m venv /tmp/paymos-smoke
+          /tmp/paymos-smoke/bin/python -m pip install --disable-pip-version-check dist/*.whl
+          cd /tmp
+          /tmp/paymos-smoke/bin/python -c "import paymos; assert paymos.VERSION"
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: python-package
+          path: dist/
+          if-no-files-found: error
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-package
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1

paymos_sdk-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+/dist/
+/build/
+/.pytest_cache/
+/.mypy_cache/
+**/__pycache__/
+*.egg-info/

paymos_sdk-1.0.0/.paymos-source.json

@@ -0,0 +1,6 @@
+{
+  "source_repository": "shockk73/paymos",
+  "source_path": "plugins/python-sdk",
+  "source_commit": "ff7ac0de110726a02b796e00345630fef5e89b76",
+  "version": "1.0.0"
+}

paymos_sdk-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.0.0]
+
+- Initial official SDK.

paymos_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paymos Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paymos_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: paymos-sdk
+Version: 1.0.0
+Summary: Official Python SDK for the Paymos Merchant API
+Project-URL: Documentation, https://paymos.io/docs/server-sdks
+Project-URL: Repository, https://github.com/Paymos-labs/python-sdk
+Project-URL: Issues, https://github.com/Paymos-labs/python-sdk/issues
+Author-email: Paymos Labs <support@paymos.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: payments,paymos,stablecoins,usdc,usdt
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build==1.5.1; extra == 'dev'
+Requires-Dist: mypy==2.2.0; extra == 'dev'
+Requires-Dist: ruff==0.15.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Paymos Python SDK
+
+Official Python 3.10+ client for the Paymos Merchant API. It includes HMAC request
+signing, invoices, withdrawals, balances, bounded cursor iterators, structured
+errors, safe retries, and raw-body webhook verification.
+
+```bash
+pip install paymos-sdk
+```
+
+```python
+import os
+
+from paymos import Paymos
+
+paymos = Paymos(
+    api_key=os.environ["PAYMOS_API_KEY"],
+    api_secret=os.environ["PAYMOS_API_SECRET"],
+)
+invoice = paymos.invoices.create(
+    project_id="prj_...", amount="10.00", currency="USD",
+    external_order_id="order_123",
+)
+```
+
+Use decimal strings for money. `list()` returns one cursor page; `iterate()`
+follows cursors lazily and stops after 100 pages by default.
+
+```python
+for invoice in paymos.invoices.iterate(status=["paid", "paid_over"], max_pages=10):
+    print(invoice["invoice_id"])
+```
+
+API failures raise typed subclasses of `ApiError` and preserve the HTTP status,
+problem details, field, error code, headers, and `Retry-After` value.
+
+Verify webhooks against the exact raw request body before parsing it:
+
+```python
+from paymos import WebhookVerifier
+
+event = WebhookVerifier(os.environ["PAYMOS_WEBHOOK_SECRET"]).construct_event(
+    request.headers["X-Webhook-Signature"], request.get_data()
+)
+```
+
+Never use the API secret in browser or mobile code. Full documentation:
+https://paymos.io/docs/server-sdks

paymos_sdk-1.0.0/README.md

@@ -0,0 +1,48 @@
+# Paymos Python SDK
+
+Official Python 3.10+ client for the Paymos Merchant API. It includes HMAC request
+signing, invoices, withdrawals, balances, bounded cursor iterators, structured
+errors, safe retries, and raw-body webhook verification.
+
+```bash
+pip install paymos-sdk
+```
+
+```python
+import os
+
+from paymos import Paymos
+
+paymos = Paymos(
+    api_key=os.environ["PAYMOS_API_KEY"],
+    api_secret=os.environ["PAYMOS_API_SECRET"],
+)
+invoice = paymos.invoices.create(
+    project_id="prj_...", amount="10.00", currency="USD",
+    external_order_id="order_123",
+)
+```
+
+Use decimal strings for money. `list()` returns one cursor page; `iterate()`
+follows cursors lazily and stops after 100 pages by default.
+
+```python
+for invoice in paymos.invoices.iterate(status=["paid", "paid_over"], max_pages=10):
+    print(invoice["invoice_id"])
+```
+
+API failures raise typed subclasses of `ApiError` and preserve the HTTP status,
+problem details, field, error code, headers, and `Retry-After` value.
+
+Verify webhooks against the exact raw request body before parsing it:
+
+```python
+from paymos import WebhookVerifier
+
+event = WebhookVerifier(os.environ["PAYMOS_WEBHOOK_SECRET"]).construct_event(
+    request.headers["X-Webhook-Signature"], request.get_data()
+)
+```
+
+Never use the API secret in browser or mobile code. Full documentation:
+https://paymos.io/docs/server-sdks

paymos_sdk-1.0.0/conformance/contract.json

@@ -0,0 +1,98 @@
+{
+  "schema": 1,
+  "base_url": "https://api.paymos.io",
+  "user_agent_prefix": "paymos-",
+  "request_signing": {
+    "algorithm": "HMAC-SHA256",
+    "signature_encoding": "base64",
+    "timestamp_header": "X-Request-Timestamp",
+    "authorization_format": "HMAC-SHA256 {api_key}:{signature}",
+    "canonical_format": "{timestamp}\\n{uppercase_method}\\n{path}\\n{query_with_optional_leading_question_mark}\\n{sha256_hex_body_or_empty}"
+  },
+  "query": {
+    "encoding": "RFC3986",
+    "sort_keys": true,
+    "sort_repeated_values": true,
+    "include_leading_question_mark_in_signature": true
+  },
+  "retry": {
+    "default_max_retries": 2,
+    "default_base_delay_ms": 150,
+    "retry_after": true,
+    "transport_errors": ["GET", "HEAD", "OPTIONS"],
+    "http_5xx": ["GET", "HEAD", "OPTIONS"],
+    "http_429": ["GET", "HEAD", "OPTIONS", "POST"]
+  },
+  "pagination": {
+    "default_max_pages": 100,
+    "next_cursor_field": "next_cursor",
+    "reject_repeated_cursor": true
+  },
+  "errors": {
+    "400": "validation",
+    "401": "authentication",
+    "403": "authentication",
+    "404": "not_found",
+    "409": "conflict",
+    "410": "gone",
+    "429": "rate_limit",
+    "500": "server",
+    "503": "unavailable"
+  },
+  "resources": {
+    "system": [
+      { "method": "GET", "path": "/v1/time", "operation": "time" }
+    ],
+    "invoices": [
+      { "method": "POST", "path": "/v1/invoices", "operation": "create" },
+      { "method": "GET", "path": "/v1/invoices/{id}", "operation": "get" },
+      { "method": "GET", "path": "/v1/invoices", "operation": "list" },
+      { "method": "POST", "path": "/v1/invoices/{id}/cancel", "operation": "cancel" },
+      { "method": "POST", "path": "/v1/invoices/{id}/confirm-payment", "operation": "confirm_payment" },
+      { "method": "POST", "path": "/v1/sandbox/invoices/{id}/simulate-payment", "operation": "simulate_payment" }
+    ],
+    "withdrawals": [
+      { "method": "POST", "path": "/v1/withdrawals", "operation": "create" },
+      { "method": "GET", "path": "/v1/withdrawals/{id}", "operation": "get" },
+      { "method": "GET", "path": "/v1/withdrawals", "operation": "list" },
+      { "method": "POST", "path": "/v1/withdrawals/{id}/cancel", "operation": "cancel" },
+      { "method": "POST", "path": "/v1/sandbox/withdrawals/{id}/simulate-completion", "operation": "simulate_completion" }
+    ],
+    "balances": [
+      { "method": "GET", "path": "/v1/balances", "operation": "get" }
+    ]
+  },
+  "vectors": {
+    "post_signing": {
+      "api_key": "pk_test_key",
+      "api_secret": "sk_test_secret",
+      "timestamp": "1700000000",
+      "method": "POST",
+      "path": "/v1/invoices",
+      "query": "",
+      "body": "{\"amount\":\"10.00\"}",
+      "body_sha256": "e9eb495accbce2a0e95bbe079b9f9e42ccae20371c1516e3ed3036d2a787cf53",
+      "signature": "AS+pbf8GlSGee9Oh5XhpasBpXB488AGEoqjDMx+dwak=",
+      "authorization": "HMAC-SHA256 pk_test_key:AS+pbf8GlSGee9Oh5XhpasBpXB488AGEoqjDMx+dwak="
+    },
+    "get_query_signing": {
+      "api_key": "pk_test_key",
+      "api_secret": "sk_test_secret",
+      "timestamp": "1700000000",
+      "method": "GET",
+      "path": "/v1/invoices",
+      "query": "?limit=50&project_id=prj%2Fa&status=paid&status=paid_over",
+      "body": "",
+      "signature": "O8M5GGSzzJAgj5w1jDViIWS4njJvohvnZi7+twuG+e0="
+    },
+    "webhook": {
+      "secret": "whsec_test_secret",
+      "timestamp": 1700000000,
+      "now": 1700000000,
+      "tolerance_seconds": 300,
+      "raw_body": "{\"event_id\":\"evt_123\",\"event_type\":\"invoice.paid\",\"version\":1,\"occurred_at\":1700000000,\"data\":{\"invoice_id\":\"inv_123\"}}",
+      "signature": "8f62822925c2d12af1b822edcc1e9392ce064c20d003cbbc11f131485348005b",
+      "header": "t=1700000000,v1=ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff,v1=8f62822925c2d12af1b822edcc1e9392ce064c20d003cbbc11f131485348005b"
+    }
+  }
+}

paymos_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling==1.31.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "paymos-sdk"
+version = "1.0.0"
+description = "Official Python SDK for the Paymos Merchant API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Paymos Labs", email = "support@paymos.io" }]
+keywords = ["paymos", "payments", "stablecoins", "usdt", "usdc"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build==1.5.1",
+  "mypy==2.2.0",
+  "ruff==0.15.21"
+]
+
+[project.urls]
+Documentation = "https://paymos.io/docs/server-sdks"
+Repository = "https://github.com/Paymos-labs/python-sdk"
+Issues = "https://github.com/Paymos-labs/python-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/paymos"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["paymos"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP", "B"]

paymos_sdk-1.0.0/src/paymos/__init__.py

@@ -0,0 +1,65 @@
+from .client import Paymos, Response
+from .errors import (
+    ApiError,
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    GoneError,
+    NotFoundError,
+    PaymosError,
+    RateLimitError,
+    ServerError,
+    SignatureMismatchError,
+    TimestampSkewError,
+    UnavailableError,
+    ValidationError,
+)
+from .models import (
+    Balance,
+    Invoice,
+    InvoiceListItem,
+    InvoicePage,
+    InvoiceStatus,
+    ServerTime,
+    WebhookEvent,
+    Withdrawal,
+    WithdrawalPage,
+    WithdrawalStatus,
+)
+from .signing import authorization_header, build_query, sign, string_to_sign
+from .version import VERSION
+from .webhooks import WebhookVerifier
+
+__all__ = [
+    "ApiError",
+    "AuthenticationError",
+    "ConfigurationError",
+    "ConflictError",
+    "GoneError",
+    "NotFoundError",
+    "Paymos",
+    "PaymosError",
+    "RateLimitError",
+    "Response",
+    "ServerError",
+    "SignatureMismatchError",
+    "TimestampSkewError",
+    "UnavailableError",
+    "ValidationError",
+    "VERSION",
+    "WebhookVerifier",
+    "Balance",
+    "Invoice",
+    "InvoiceListItem",
+    "InvoicePage",
+    "InvoiceStatus",
+    "ServerTime",
+    "WebhookEvent",
+    "Withdrawal",
+    "WithdrawalPage",
+    "WithdrawalStatus",
+    "authorization_header",
+    "build_query",
+    "sign",
+    "string_to_sign",
+]