payitgo 0.1.0__tar.gz

payitgo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 payitgo
+
+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.

payitgo-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: payitgo
+Version: 0.1.0
+Summary: Python client for the payitgo crypto payment gateway
+License-Expression: MIT
+Project-URL: Repository, https://github.com/thedivinez/payitgo-sdk/tree/main/python
+Keywords: payitgo,payments,crypto,usdt,bitcoin
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# payitgo for Python
+
+Accept crypto payments with [payitgo](https://api.payitgo.co/docs) from Python 3.8+. No dependencies.
+
+Full reference, with every method, option, type and error: [api.payitgo.co/docs/sdk-python](https://api.payitgo.co/docs/sdk-python).
+
+```bash
+pip install payitgo
+```
+
+The package is `payitgo` on PyPI; you import it as `payitgo`.
+
+## Accept a payment in three steps
+
+```python
+import os
+import payitgo
+from flask import Flask, abort, redirect, request
+
+client = payitgo.Client(
+    os.environ["PAYITGO_KEY"],
+    base_url=os.environ["PAYITGO_BASE_URL"],
+    webhook_secret=os.environ["PAYITGO_WEBHOOK_SECRET"],  # "whsec_…": see Webhooks (IPN) below
+)
+app = Flask(__name__)
+
+# 1. Create a payment and send the customer to the checkout page.
+@app.post("/checkout")
+def checkout():
+    payment = client.payments.create(
+        order_id=request.form["order_id"],   # your order id: safe to retry
+        amount_usd=request.form["total"],    # e.g. "19.99"
+        # token="USDT_TRC20",                # optional: without it the customer picks the coin
+        success_url="https://shop.example/thanks",
+    )
+    return redirect(payment.checkout_url)
+
+# 2. Receive the notification (the complete handler is under Webhooks (IPN) below).
+#    Use the raw body: the signature covers its exact bytes.
+@app.post("/payitgo/ipn")
+def ipn():
+    try:
+        event = client.webhooks.construct_event(request.get_data(), request.headers.get("X-Webhook-Signature"))
+    except payitgo.SignatureVerificationError:
+        abort(400)
+    # 3. Fulfil the order once the payment is final.
+    if event.type == "payment.confirmed":
+        mark_order_paid(event.data.order_id)  # make this idempotent: events can arrive twice
+    return "", 200
+```
+
+Start with your test key (`sk_test_…`) and testnet coins; switch to the live key
+(`sk_live_…`) when the account owner has turned live mode on.
+
+## Your own payment page
+
+`checkout_url` is only for payitgo's hosted page. To show the payment on your own page,
+render the payment your server gets back (`deposit_address`, `crypto_amount`,
+`destination_tag` for XRP, a QR code of `qr_payload`, `expires_at`); no `checkout` calls
+are needed.
+
+- **You know the coin:** create the payment with `token` and render the payment it returns.
+- **The customer chooses it:** create the payment without `token`, show
+  `payment.token_options` on your page, then call
+  `client.payments.select_token(payment.id, chosen)` from your server and render the
+  payment it returns: it now has its coin, address, amount, locked rate and a deadline 15
+  minutes away.
+
+```python
+payment = client.payments.create(order_id="ORD-1", amount_usd=10)
+# your page shows payment.token_options; the customer picks one
+chosen = client.payments.select_token(payment.id, "USDT_TRC20")  # or your order id
+# render chosen.deposit_address, chosen.crypto_amount, chosen.qr_payload, chosen.expires_at
+```
+
+The coin is chosen once: choosing again is a `409` (`payments.retrieve` then returns the
+payment with its coin). A coin outside `token_options`, or a payment that can no longer be
+paid, is a `400`.
+
+## Webhooks (IPN)
+
+payitgo POSTs a signed notification for every change of a payment (`payment.confirmed`,
+`payment.expired`, …), of a direct settlement and of a payout. Each mode has one webhook:
+a test key manages the test one, a live key the live one.
+
+**Where the notifications go.** Set the URL once per mode (https:// on a public host,
+accepting POST requests), or give a payment its own when you create it:
+
+```python
+# Once per mode (safe to repeat):
+client.webhooks.set("https://shop.example/payitgo/ipn")
+
+# Or per payment: its events go there instead of the webhook's URL.
+client.payments.create(order_id="ORD-1", amount_usd=10, webhook_url="https://shop.example/orders/ipn")
+
+# Or as the client's default for every payment it creates (a payment's own webhook_url wins):
+shop = payitgo.Client(os.environ["PAYITGO_KEY"], webhook_url="https://shop.example/orders/ipn")
+```
+
+A storefront's key cannot set the account's URL (`403`): pass `webhook_url` instead.
+Payout events always go to the webhook's URL.
+
+**The signing secret.** Every notification of a mode is signed with that mode's secret
+(`whsec_…`), whichever URL it goes to. Copy it from the dashboard or read it with
+`client.webhooks.get().secret`, and give it to the client once:
+
+```python
+client = payitgo.Client(os.environ["PAYITGO_KEY"], webhook_secret=os.environ["PAYITGO_WEBHOOK_SECRET"])
+```
+
+**Receiving them** (Flask). Verify the raw body, handle each event once, and answer
+`2xx` within 10 seconds; otherwise payitgo retries after 1 min, 5 min, 30 min, 2 h, 6 h and
+24 h.
+
+```python
+@app.post("/payitgo/ipn")
+def ipn():
+    try:
+        # Checks the signature with the client's webhook_secret and refuses anything older than 5 minutes.
+        event = client.webhooks.construct_event(request.get_data(), request.headers.get("X-Webhook-Signature"))
+    except payitgo.SignatureVerificationError:
+        abort(400)
+    # The same event can arrive more than once: handle each event id once,
+    # e.g. by inserting it into a table with a unique key.
+    if not record_event_once(event.id):
+        return "", 200
+    if event.type == "payment.confirmed":
+        jobs.enqueue("fulfil", event.data.order_id)  # slow work off the request
+    elif event.type == "payment.expired":
+        jobs.enqueue("release_stock", event.data.order_id)
+    return "", 200
+```
+
+**Testing it.** `client.webhooks.test()` queues a signed `ping` event to the webhook's
+URL and returns its delivery (`400` when no URL is set).
+
+## API
+
+```python
+client = payitgo.Client(api_key, base_url="https://api.example.com",  # or PAYITGO_BASE_URL
+                      timeout=30, max_retries=2,                    # network errors, 429, 5xx
+                      webhook_secret="whsec_…",                     # for webhooks.construct_event
+                      webhook_url="https://…")                      # default webhook_url of payments.create
+
+client.livemode                                    # False for sk_test_ keys
+client.payments.create(order_id, amount_usd, token, webhook_url=None, description=None, metadata=None,
+                       customer_email=None, success_url=None, cancel_url=None)
+client.payments.select_token("pay_…", token)       # or your order id: the payment with its coin
+client.payments.retrieve("pay_…")                  # or your order id
+client.payments.list(status="confirmed", store_id="sto_…", limit=50, offset=0)  # every filter optional
+client.tokens.list()                               # [{token, chain, min_usd, network_fee_usd, fee_note}]
+client.tokens.list(amount_usd="49.90")             # the coins a $49.90 payment offers, with amount_due_usd
+client.checkout.retrieve(checkout_token)           # public payer view
+client.webhooks.get()                              # {livemode, url, secret, created_at, updated_at}
+client.webhooks.set(url)                           # the webhook
+client.webhooks.remove()                           # the webhook, url None (the secret stays)
+client.webhooks.test()                             # the delivery of a "ping" event
+client.webhooks.construct_event(raw_body, signature_header, secret=None, tolerance=300)
+payitgo.Webhook.construct_event(raw_body, signature_header, secret, tolerance=300)  # no client needed
+```
+
+Responses are dicts that also allow attribute access: `payment["status"]` or
+`payment.status`. Field names are the API's own (see the
+[payment object](https://api.payitgo.co/docs/payments) and [webhooks](https://api.payitgo.co/docs/webhooks)).
+`payitgo.WEBHOOK_EVENTS` lists the event types.
+
+## Errors
+
+```python
+try:
+    client.payments.create(order_id="ORD-1", amount_usd=1, token="BTC")
+except payitgo.PayitgoError as e:
+    print(e.status, e.message)   # 400 minimum payment in BTC is $10 right now (network fees)
+```
+
+`PayitgoError.status` is the HTTP status (0 for a network error).
+`construct_event` raises `SignatureVerificationError` for a bad signature, a stale
+timestamp, or when it has no secret (none passed and no `webhook_secret`).
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests
+```

payitgo-0.1.0/README.md

@@ -0,0 +1,184 @@
+# payitgo for Python
+
+Accept crypto payments with [payitgo](https://api.payitgo.co/docs) from Python 3.8+. No dependencies.
+
+Full reference, with every method, option, type and error: [api.payitgo.co/docs/sdk-python](https://api.payitgo.co/docs/sdk-python).
+
+```bash
+pip install payitgo
+```
+
+The package is `payitgo` on PyPI; you import it as `payitgo`.
+
+## Accept a payment in three steps
+
+```python
+import os
+import payitgo
+from flask import Flask, abort, redirect, request
+
+client = payitgo.Client(
+    os.environ["PAYITGO_KEY"],
+    base_url=os.environ["PAYITGO_BASE_URL"],
+    webhook_secret=os.environ["PAYITGO_WEBHOOK_SECRET"],  # "whsec_…": see Webhooks (IPN) below
+)
+app = Flask(__name__)
+
+# 1. Create a payment and send the customer to the checkout page.
+@app.post("/checkout")
+def checkout():
+    payment = client.payments.create(
+        order_id=request.form["order_id"],   # your order id: safe to retry
+        amount_usd=request.form["total"],    # e.g. "19.99"
+        # token="USDT_TRC20",                # optional: without it the customer picks the coin
+        success_url="https://shop.example/thanks",
+    )
+    return redirect(payment.checkout_url)
+
+# 2. Receive the notification (the complete handler is under Webhooks (IPN) below).
+#    Use the raw body: the signature covers its exact bytes.
+@app.post("/payitgo/ipn")
+def ipn():
+    try:
+        event = client.webhooks.construct_event(request.get_data(), request.headers.get("X-Webhook-Signature"))
+    except payitgo.SignatureVerificationError:
+        abort(400)
+    # 3. Fulfil the order once the payment is final.
+    if event.type == "payment.confirmed":
+        mark_order_paid(event.data.order_id)  # make this idempotent: events can arrive twice
+    return "", 200
+```
+
+Start with your test key (`sk_test_…`) and testnet coins; switch to the live key
+(`sk_live_…`) when the account owner has turned live mode on.
+
+## Your own payment page
+
+`checkout_url` is only for payitgo's hosted page. To show the payment on your own page,
+render the payment your server gets back (`deposit_address`, `crypto_amount`,
+`destination_tag` for XRP, a QR code of `qr_payload`, `expires_at`); no `checkout` calls
+are needed.
+
+- **You know the coin:** create the payment with `token` and render the payment it returns.
+- **The customer chooses it:** create the payment without `token`, show
+  `payment.token_options` on your page, then call
+  `client.payments.select_token(payment.id, chosen)` from your server and render the
+  payment it returns: it now has its coin, address, amount, locked rate and a deadline 15
+  minutes away.
+
+```python
+payment = client.payments.create(order_id="ORD-1", amount_usd=10)
+# your page shows payment.token_options; the customer picks one
+chosen = client.payments.select_token(payment.id, "USDT_TRC20")  # or your order id
+# render chosen.deposit_address, chosen.crypto_amount, chosen.qr_payload, chosen.expires_at
+```
+
+The coin is chosen once: choosing again is a `409` (`payments.retrieve` then returns the
+payment with its coin). A coin outside `token_options`, or a payment that can no longer be
+paid, is a `400`.
+
+## Webhooks (IPN)
+
+payitgo POSTs a signed notification for every change of a payment (`payment.confirmed`,
+`payment.expired`, …), of a direct settlement and of a payout. Each mode has one webhook:
+a test key manages the test one, a live key the live one.
+
+**Where the notifications go.** Set the URL once per mode (https:// on a public host,
+accepting POST requests), or give a payment its own when you create it:
+
+```python
+# Once per mode (safe to repeat):
+client.webhooks.set("https://shop.example/payitgo/ipn")
+
+# Or per payment: its events go there instead of the webhook's URL.
+client.payments.create(order_id="ORD-1", amount_usd=10, webhook_url="https://shop.example/orders/ipn")
+
+# Or as the client's default for every payment it creates (a payment's own webhook_url wins):
+shop = payitgo.Client(os.environ["PAYITGO_KEY"], webhook_url="https://shop.example/orders/ipn")
+```
+
+A storefront's key cannot set the account's URL (`403`): pass `webhook_url` instead.
+Payout events always go to the webhook's URL.
+
+**The signing secret.** Every notification of a mode is signed with that mode's secret
+(`whsec_…`), whichever URL it goes to. Copy it from the dashboard or read it with
+`client.webhooks.get().secret`, and give it to the client once:
+
+```python
+client = payitgo.Client(os.environ["PAYITGO_KEY"], webhook_secret=os.environ["PAYITGO_WEBHOOK_SECRET"])
+```
+
+**Receiving them** (Flask). Verify the raw body, handle each event once, and answer
+`2xx` within 10 seconds; otherwise payitgo retries after 1 min, 5 min, 30 min, 2 h, 6 h and
+24 h.
+
+```python
+@app.post("/payitgo/ipn")
+def ipn():
+    try:
+        # Checks the signature with the client's webhook_secret and refuses anything older than 5 minutes.
+        event = client.webhooks.construct_event(request.get_data(), request.headers.get("X-Webhook-Signature"))
+    except payitgo.SignatureVerificationError:
+        abort(400)
+    # The same event can arrive more than once: handle each event id once,
+    # e.g. by inserting it into a table with a unique key.
+    if not record_event_once(event.id):
+        return "", 200
+    if event.type == "payment.confirmed":
+        jobs.enqueue("fulfil", event.data.order_id)  # slow work off the request
+    elif event.type == "payment.expired":
+        jobs.enqueue("release_stock", event.data.order_id)
+    return "", 200
+```
+
+**Testing it.** `client.webhooks.test()` queues a signed `ping` event to the webhook's
+URL and returns its delivery (`400` when no URL is set).
+
+## API
+
+```python
+client = payitgo.Client(api_key, base_url="https://api.example.com",  # or PAYITGO_BASE_URL
+                      timeout=30, max_retries=2,                    # network errors, 429, 5xx
+                      webhook_secret="whsec_…",                     # for webhooks.construct_event
+                      webhook_url="https://…")                      # default webhook_url of payments.create
+
+client.livemode                                    # False for sk_test_ keys
+client.payments.create(order_id, amount_usd, token, webhook_url=None, description=None, metadata=None,
+                       customer_email=None, success_url=None, cancel_url=None)
+client.payments.select_token("pay_…", token)       # or your order id: the payment with its coin
+client.payments.retrieve("pay_…")                  # or your order id
+client.payments.list(status="confirmed", store_id="sto_…", limit=50, offset=0)  # every filter optional
+client.tokens.list()                               # [{token, chain, min_usd, network_fee_usd, fee_note}]
+client.tokens.list(amount_usd="49.90")             # the coins a $49.90 payment offers, with amount_due_usd
+client.checkout.retrieve(checkout_token)           # public payer view
+client.webhooks.get()                              # {livemode, url, secret, created_at, updated_at}
+client.webhooks.set(url)                           # the webhook
+client.webhooks.remove()                           # the webhook, url None (the secret stays)
+client.webhooks.test()                             # the delivery of a "ping" event
+client.webhooks.construct_event(raw_body, signature_header, secret=None, tolerance=300)
+payitgo.Webhook.construct_event(raw_body, signature_header, secret, tolerance=300)  # no client needed
+```
+
+Responses are dicts that also allow attribute access: `payment["status"]` or
+`payment.status`. Field names are the API's own (see the
+[payment object](https://api.payitgo.co/docs/payments) and [webhooks](https://api.payitgo.co/docs/webhooks)).
+`payitgo.WEBHOOK_EVENTS` lists the event types.
+
+## Errors
+
+```python
+try:
+    client.payments.create(order_id="ORD-1", amount_usd=1, token="BTC")
+except payitgo.PayitgoError as e:
+    print(e.status, e.message)   # 400 minimum payment in BTC is $10 right now (network fees)
+```
+
+`PayitgoError.status` is the HTTP status (0 for a network error).
+`construct_event` raises `SignatureVerificationError` for a bad signature, a stale
+timestamp, or when it has no secret (none passed and no `webhook_secret`).
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests
+```

payitgo-0.1.0/payitgo/__init__.py

@@ -0,0 +1,273 @@
+"""Python client for the payitgo crypto payment gateway.
+
+    import payitgo
+
+    client = payitgo.Client(os.environ["PAYITGO_KEY"], base_url="https://api.example.com")
+    payment = client.payments.create(order_id="ORD-1001", amount_usd=10, token="USDT_TRC20")
+    # send the customer to payment.checkout_url; fulfil on the payment.confirmed webhook
+
+Use the client from your server only: the API key is a secret.
+"""
+
+import hashlib
+import hmac
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+__version__ = "0.1.0"
+__all__ = ["Client", "Webhook", "PayitgoError", "SignatureVerificationError", "PayitgoObject", "WEBHOOK_EVENTS"]
+
+# Used when neither base_url nor PAYITGO_BASE_URL is set.
+DEFAULT_BASE_URL = "https://api.payitgo.co"
+
+#: The events payitgo sends. A test (``client.webhooks.test()``) sends "ping".
+WEBHOOK_EVENTS = (
+    "payment.partially_paid", "payment.detecting", "payment.confirmed", "payment.underpaid",
+    "payment.expired", "payment.failed", "payment.wrong_asset", "payment.late_deposit",
+    "payout.approved", "payout.rejected", "payout.sent", "settlement.completed", "settlement.failed",
+    "ping",
+)
+
+
+class PayitgoError(Exception):
+    """The API refused the request. ``status`` is the HTTP status, or 0 for a network error."""
+
+    def __init__(self, message, status=0):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+
+
+class SignatureVerificationError(Exception):
+    """A webhook request whose signature or timestamp did not check out."""
+
+
+class PayitgoObject(dict):
+    """A dict whose keys can also be read as attributes: ``payment.status``."""
+
+    def __getattr__(self, name):
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(name) from None
+
+
+def _wrap(value):
+    if isinstance(value, dict):
+        return PayitgoObject({k: _wrap(v) for k, v in value.items()})
+    if isinstance(value, list):
+        return [_wrap(v) for v in value]
+    return value
+
+
+class Client:
+    """The payitgo client, for one secret key (``sk_test_…`` or ``sk_live_…``).
+
+    ``webhook_secret`` is the signing secret of the key's mode (``whsec_…``), which
+    ``webhooks.construct_event`` uses when given none; ``webhook_url`` is sent as the
+    ``webhook_url`` of every payment this client creates without its own.
+    """
+
+    def __init__(self, api_key, base_url=None, timeout=30, max_retries=2, webhook_secret=None, webhook_url=None):
+        if not isinstance(api_key, str) or not api_key.startswith(("sk_test_", "sk_live_")):
+            raise ValueError("payitgo: the API key must start with sk_test_ or sk_live_")
+        base_url = base_url or os.environ.get("PAYITGO_BASE_URL") or DEFAULT_BASE_URL
+        if not base_url:
+            raise ValueError("payitgo: set base_url (or PAYITGO_BASE_URL) to your gateway's address")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._webhook_secret = webhook_secret or None
+        self._webhook_url = webhook_url or None
+        #: False for a test key, True for a live key.
+        self.livemode = api_key.startswith("sk_live_")
+        self.payments = _Payments(self)
+        self.tokens = _Tokens(self)
+        self.checkout = _Checkout(self)
+        self.webhooks = _Webhooks(self)
+
+    def _request(self, method, path, body=None, authenticated=True):
+        headers = {"Accept": "application/json", "User-Agent": "payitgo-python/" + __version__}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["Content-Type"] = "application/json"
+        if authenticated:
+            headers["Authorization"] = "Bearer " + self._api_key
+
+        attempt = 0
+        while True:
+            req = urllib.request.Request(self._base_url + path, data=data, method=method, headers=headers)
+            try:
+                with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                    raw = resp.read()
+                    return _wrap(json.loads(raw)) if raw else None
+            except urllib.error.HTTPError as e:
+                with e:
+                    raw = e.read()
+                if (e.code == 429 or e.code >= 500) and attempt < self._max_retries:
+                    attempt += 1
+                    time.sleep(0.5 * 2 ** (attempt - 1))
+                    continue
+                try:
+                    message = json.loads(raw).get("error") or e.reason
+                except (ValueError, AttributeError):
+                    message = e.reason or "HTTP %d" % e.code
+                raise PayitgoError(message, e.code) from None
+            except (urllib.error.URLError, OSError) as e:
+                if attempt < self._max_retries:
+                    attempt += 1
+                    time.sleep(0.5 * 2 ** (attempt - 1))
+                    continue
+                raise PayitgoError("request failed: %s" % e, 0) from None
+
+
+class _Payments:
+    def __init__(self, client):
+        self._client = client
+
+    def create(self, order_id, amount_usd, token=None, webhook_url=None, **optional):
+        """Creates a payment. Safe to retry: an order with an open payment returns that payment.
+
+        Leave token out to let the customer choose the coin on the checkout page.
+        webhook_url (https) gets the payment's events instead of the webhook's URL,
+        signed with the same secret (default: the client's webhook_url).
+        Optional fields: tokens (the coins to offer), description, metadata,
+        customer_email, success_url, cancel_url.
+        """
+        body = {"order_id": order_id, "amount_usd": str(amount_usd)}
+        if token:
+            body["token"] = token
+        webhook_url = webhook_url if webhook_url is not None else self._client._webhook_url
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        body.update({k: v for k, v in optional.items() if v is not None})
+        return self._client._request("POST", "/v1/payments", body)
+
+    def retrieve(self, id):
+        """A payment by its id (pay_…) or by your order id (the order's open payment)."""
+        return self._client._request("GET", "/v1/payments/" + urllib.parse.quote(id, safe=""))
+
+    def select_token(self, payment_id, token):
+        """Sets the coin of a payment created without one, when the customer chose it on your
+        own page: one of its token_options. payment_id is the payment's id (pay_…) or your order id.
+
+        Returns the whole payment, now with its address, amount, locked rate and a deadline
+        15 minutes away. The coin is chosen once: choosing again is a 409.
+        """
+        return self._client._request("POST", "/v1/payments/" + urllib.parse.quote(payment_id, safe="") + "/token",
+                                     {"token": token})
+
+    def list(self, status=None, chain=None, token=None, limit=None, offset=None, store_id=None):
+        """Payments of the key's mode, newest first: {payments, total, limit, offset}.
+
+        store_id keeps the payments of one store (ignored for a storefront's key, which
+        sees its own).
+        """
+        params = {k: v for k, v in {"status": status, "chain": chain, "token": token, "store_id": store_id,
+                                    "limit": limit, "offset": offset}.items() if v is not None}
+        query = "?" + urllib.parse.urlencode(params) if params else ""
+        return self._client._request("GET", "/v1/payments" + query)
+
+
+class _Tokens:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, amount_usd=None):
+        """The tokens a customer can pay with in the key's mode. With amount_usd,
+        only the ones a payment of that amount offers (its token_options), each
+        with amount_due_usd when fees are passed on."""
+        query = "?" + urllib.parse.urlencode({"amount_usd": str(amount_usd)}) if amount_usd is not None else ""
+        return self._client._request("GET", "/v1/tokens" + query)["tokens"]
+
+
+class _Checkout:
+    def __init__(self, client):
+        self._client = client
+
+    def retrieve(self, checkout_token):
+        """The payer's view of a payment, by its checkout token. Public: sent without the API key."""
+        return self._client._request("GET", "/checkout/" + urllib.parse.quote(checkout_token, safe=""),
+                                     authenticated=False)
+
+    def select_token(self, checkout_token, token):
+        """The customer's choice of coin for a payment created without one. Public."""
+        return self._client._request("POST", "/checkout/" + urllib.parse.quote(checkout_token, safe="") + "/token",
+                                     {"token": token}, authenticated=False)
+
+
+class _Webhooks:
+    """The webhook (IPN) of the key's mode: a test key manages the test webhook, a live key
+    the live one. A storefront's key may read and test it, not change it."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def get(self):
+        """The webhook: {livemode, url (None when not set), secret, created_at, updated_at}."""
+        return self._client._request("GET", "/v1/webhook")["webhook"]
+
+    def set(self, url):
+        """Sets the URL every event of the mode is POSTed to: https, public host, accepting POST
+        requests. Safe to retry."""
+        return self._client._request("PUT", "/v1/webhook", {"url": url})["webhook"]
+
+    def remove(self):
+        """Stops POSTing to the URL (payments with their own webhook_url still get theirs); the
+        secret stays."""
+        return self._client._request("DELETE", "/v1/webhook")["webhook"]
+
+    def test(self):
+        """Queues a signed "ping" event to the URL and returns its delivery."""
+        return self._client._request("POST", "/v1/webhook/test")["delivery"]
+
+    def construct_event(self, payload, signature_header, secret=None, tolerance=None):
+        """Verifies a webhook request and returns its event; see ``Webhook.construct_event``.
+
+        ``secret`` defaults to the client's ``webhook_secret``; without either it raises
+        SignatureVerificationError.
+        """
+        secret = secret or self._client._webhook_secret
+        if not secret:
+            raise SignatureVerificationError("no webhook secret: pass one, or set the client's webhook_secret")
+        if tolerance is None:
+            tolerance = Webhook.DEFAULT_TOLERANCE
+        return Webhook.construct_event(payload, signature_header, secret, tolerance)
+
+
+class Webhook:
+    DEFAULT_TOLERANCE = 300
+
+    @staticmethod
+    def construct_event(payload, signature_header, secret, tolerance=DEFAULT_TOLERANCE):
+        """Verifies a webhook request and returns its event.
+
+        Pass the raw request body (bytes, before any JSON parsing), the
+        X-Webhook-Signature header and the mode's signing secret (the webhook's
+        ``secret``, from ``client.webhooks.get()`` or the dashboard). Raises
+        SignatureVerificationError when the signature is wrong or the timestamp
+        is more than ``tolerance`` seconds old (0 disables the timestamp check).
+        """
+        if isinstance(payload, str):
+            payload = payload.encode()
+        parts = dict(p.strip().split("=", 1) for p in (signature_header or "").split(",") if "=" in p)
+        t, v1 = parts.get("t", ""), parts.get("v1", "")
+        if not t or not v1:
+            raise SignatureVerificationError("missing or malformed X-Webhook-Signature header")
+        expected = hmac.new(secret.encode(), t.encode() + b"." + payload, hashlib.sha256).hexdigest()
+        # Compared as bytes: a header with non-ASCII characters is a mismatch, not a TypeError.
+        if not hmac.compare_digest(expected.encode(), v1.encode()):
+            raise SignatureVerificationError("signature does not match")
+        if tolerance and tolerance > 0:
+            try:
+                if abs(time.time() - int(t)) > tolerance:
+                    raise SignatureVerificationError("timestamp outside the tolerance")
+            except ValueError:
+                raise SignatureVerificationError("malformed timestamp") from None
+        return _wrap(json.loads(payload))

payitgo-0.1.0/payitgo.egg-info/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: payitgo
+Version: 0.1.0
+Summary: Python client for the payitgo crypto payment gateway
+License-Expression: MIT
+Project-URL: Repository, https://github.com/thedivinez/payitgo-sdk/tree/main/python
+Keywords: payitgo,payments,crypto,usdt,bitcoin
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# payitgo for Python
+
+Accept crypto payments with [payitgo](https://api.payitgo.co/docs) from Python 3.8+. No dependencies.
+
+Full reference, with every method, option, type and error: [api.payitgo.co/docs/sdk-python](https://api.payitgo.co/docs/sdk-python).
+
+```bash
+pip install payitgo
+```
+
+The package is `payitgo` on PyPI; you import it as `payitgo`.
+
+## Accept a payment in three steps
+
+```python
+import os
+import payitgo
+from flask import Flask, abort, redirect, request
+
+client = payitgo.Client(
+    os.environ["PAYITGO_KEY"],
+    base_url=os.environ["PAYITGO_BASE_URL"],
+    webhook_secret=os.environ["PAYITGO_WEBHOOK_SECRET"],  # "whsec_…": see Webhooks (IPN) below
+)
+app = Flask(__name__)
+
+# 1. Create a payment and send the customer to the checkout page.
+@app.post("/checkout")
+def checkout():
+    payment = client.payments.create(
+        order_id=request.form["order_id"],   # your order id: safe to retry
+        amount_usd=request.form["total"],    # e.g. "19.99"
+        # token="USDT_TRC20",                # optional: without it the customer picks the coin
+        success_url="https://shop.example/thanks",
+    )
+    return redirect(payment.checkout_url)
+
+# 2. Receive the notification (the complete handler is under Webhooks (IPN) below).
+#    Use the raw body: the signature covers its exact bytes.
+@app.post("/payitgo/ipn")
+def ipn():
+    try:
+        event = client.webhooks.construct_event(request.get_data(), request.headers.get("X-Webhook-Signature"))
+    except payitgo.SignatureVerificationError:
+        abort(400)
+    # 3. Fulfil the order once the payment is final.
+    if event.type == "payment.confirmed":
+        mark_order_paid(event.data.order_id)  # make this idempotent: events can arrive twice
+    return "", 200
+```
+
+Start with your test key (`sk_test_…`) and testnet coins; switch to the live key
+(`sk_live_…`) when the account owner has turned live mode on.
+
+## Your own payment page
+
+`checkout_url` is only for payitgo's hosted page. To show the payment on your own page,
+render the payment your server gets back (`deposit_address`, `crypto_amount`,
+`destination_tag` for XRP, a QR code of `qr_payload`, `expires_at`); no `checkout` calls
+are needed.
+
+- **You know the coin:** create the payment with `token` and render the payment it returns.
+- **The customer chooses it:** create the payment without `token`, show
+  `payment.token_options` on your page, then call
+  `client.payments.select_token(payment.id, chosen)` from your server and render the
+  payment it returns: it now has its coin, address, amount, locked rate and a deadline 15
+  minutes away.
+
+```python
+payment = client.payments.create(order_id="ORD-1", amount_usd=10)
+# your page shows payment.token_options; the customer picks one
+chosen = client.payments.select_token(payment.id, "USDT_TRC20")  # or your order id
+# render chosen.deposit_address, chosen.crypto_amount, chosen.qr_payload, chosen.expires_at
+```
+
+The coin is chosen once: choosing again is a `409` (`payments.retrieve` then returns the
+payment with its coin). A coin outside `token_options`, or a payment that can no longer be
+paid, is a `400`.
+
+## Webhooks (IPN)
+
+payitgo POSTs a signed notification for every change of a payment (`payment.confirmed`,
+`payment.expired`, …), of a direct settlement and of a payout. Each mode has one webhook:
+a test key manages the test one, a live key the live one.
+
+**Where the notifications go.** Set the URL once per mode (https:// on a public host,
+accepting POST requests), or give a payment its own when you create it:
+
+```python
+# Once per mode (safe to repeat):
+client.webhooks.set("https://shop.example/payitgo/ipn")
+
+# Or per payment: its events go there instead of the webhook's URL.
+client.payments.create(order_id="ORD-1", amount_usd=10, webhook_url="https://shop.example/orders/ipn")
+
+# Or as the client's default for every payment it creates (a payment's own webhook_url wins):
+shop = payitgo.Client(os.environ["PAYITGO_KEY"], webhook_url="https://shop.example/orders/ipn")
+```
+
+A storefront's key cannot set the account's URL (`403`): pass `webhook_url` instead.
+Payout events always go to the webhook's URL.
+
+**The signing secret.** Every notification of a mode is signed with that mode's secret
+(`whsec_…`), whichever URL it goes to. Copy it from the dashboard or read it with
+`client.webhooks.get().secret`, and give it to the client once:
+
+```python
+client = payitgo.Client(os.environ["PAYITGO_KEY"], webhook_secret=os.environ["PAYITGO_WEBHOOK_SECRET"])
+```
+
+**Receiving them** (Flask). Verify the raw body, handle each event once, and answer
+`2xx` within 10 seconds; otherwise payitgo retries after 1 min, 5 min, 30 min, 2 h, 6 h and
+24 h.
+
+```python
+@app.post("/payitgo/ipn")
+def ipn():
+    try:
+        # Checks the signature with the client's webhook_secret and refuses anything older than 5 minutes.
+        event = client.webhooks.construct_event(request.get_data(), request.headers.get("X-Webhook-Signature"))
+    except payitgo.SignatureVerificationError:
+        abort(400)
+    # The same event can arrive more than once: handle each event id once,
+    # e.g. by inserting it into a table with a unique key.
+    if not record_event_once(event.id):
+        return "", 200
+    if event.type == "payment.confirmed":
+        jobs.enqueue("fulfil", event.data.order_id)  # slow work off the request
+    elif event.type == "payment.expired":
+        jobs.enqueue("release_stock", event.data.order_id)
+    return "", 200
+```
+
+**Testing it.** `client.webhooks.test()` queues a signed `ping` event to the webhook's
+URL and returns its delivery (`400` when no URL is set).
+
+## API
+
+```python
+client = payitgo.Client(api_key, base_url="https://api.example.com",  # or PAYITGO_BASE_URL
+                      timeout=30, max_retries=2,                    # network errors, 429, 5xx
+                      webhook_secret="whsec_…",                     # for webhooks.construct_event
+                      webhook_url="https://…")                      # default webhook_url of payments.create
+
+client.livemode                                    # False for sk_test_ keys
+client.payments.create(order_id, amount_usd, token, webhook_url=None, description=None, metadata=None,
+                       customer_email=None, success_url=None, cancel_url=None)
+client.payments.select_token("pay_…", token)       # or your order id: the payment with its coin
+client.payments.retrieve("pay_…")                  # or your order id
+client.payments.list(status="confirmed", store_id="sto_…", limit=50, offset=0)  # every filter optional
+client.tokens.list()                               # [{token, chain, min_usd, network_fee_usd, fee_note}]
+client.tokens.list(amount_usd="49.90")             # the coins a $49.90 payment offers, with amount_due_usd
+client.checkout.retrieve(checkout_token)           # public payer view
+client.webhooks.get()                              # {livemode, url, secret, created_at, updated_at}
+client.webhooks.set(url)                           # the webhook
+client.webhooks.remove()                           # the webhook, url None (the secret stays)
+client.webhooks.test()                             # the delivery of a "ping" event
+client.webhooks.construct_event(raw_body, signature_header, secret=None, tolerance=300)
+payitgo.Webhook.construct_event(raw_body, signature_header, secret, tolerance=300)  # no client needed
+```
+
+Responses are dicts that also allow attribute access: `payment["status"]` or
+`payment.status`. Field names are the API's own (see the
+[payment object](https://api.payitgo.co/docs/payments) and [webhooks](https://api.payitgo.co/docs/webhooks)).
+`payitgo.WEBHOOK_EVENTS` lists the event types.
+
+## Errors
+
+```python
+try:
+    client.payments.create(order_id="ORD-1", amount_usd=1, token="BTC")
+except payitgo.PayitgoError as e:
+    print(e.status, e.message)   # 400 minimum payment in BTC is $10 right now (network fees)
+```
+
+`PayitgoError.status` is the HTTP status (0 for a network error).
+`construct_event` raises `SignatureVerificationError` for a bad signature, a stale
+timestamp, or when it has no secret (none passed and no `webhook_secret`).
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests
+```

payitgo-0.1.0/payitgo.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+payitgo/__init__.py
+payitgo.egg-info/PKG-INFO
+payitgo.egg-info/SOURCES.txt
+payitgo.egg-info/dependency_links.txt
+payitgo.egg-info/top_level.txt
+tests/test_payitgo.py

payitgo-0.1.0/payitgo.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

payitgo-0.1.0/payitgo.egg-info/top_level.txt

@@ -0,0 +1 @@
+payitgo

payitgo-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "payitgo"
+version = "0.1.0"
+description = "Python client for the payitgo crypto payment gateway"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.8"
+dependencies = []
+keywords = ["payitgo", "payments", "crypto", "usdt", "bitcoin"]
+
+[project.urls]
+Repository = "https://github.com/thedivinez/payitgo-sdk/tree/main/python"
+
+[tool.setuptools]
+packages = ["payitgo"]

payitgo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

payitgo-0.1.0/tests/test_payitgo.py

@@ -0,0 +1,273 @@
+import hashlib
+import hmac
+import json
+import os
+import sys
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+import payitgo  # noqa: E402
+
+# Signed by the gateway's own signer.
+SECRET = "whsec_test_secret"
+HEADER = "t=1760000000,v1=6abd292fdf2ecc51779c161f5d4be2d47236f7a43fbaa9dd7093303904b91a7b"
+BODY = b'{"id":"evt_test_123","type":"payment.confirmed","livemode":false,"created_at":"2026-10-09T12:00:00Z","data":{"id":"pay_123","order_id":"ORD-1","status":"confirmed","usd_amount":"10"}}'
+
+
+def sign(secret, t, body):
+    return "t=%d,v1=%s" % (t, hmac.new(secret.encode(), str(t).encode() + b"." + body, hashlib.sha256).hexdigest())
+
+
+class WebhookTest(unittest.TestCase):
+    def test_accepts_gateway_signature(self):
+        event = payitgo.Webhook.construct_event(BODY, HEADER, SECRET, tolerance=0)
+        self.assertEqual(event.type, "payment.confirmed")
+        self.assertEqual(event.data.order_id, "ORD-1")
+        self.assertFalse(event.livemode)
+
+    def test_accepts_str_body(self):
+        self.assertEqual(payitgo.Webhook.construct_event(BODY.decode(), HEADER, SECRET, tolerance=0)["id"], "evt_test_123")
+
+    def test_rejects(self):
+        for body, header, secret in [
+            (BODY.replace(b'"10"', b'"1000"'), HEADER, SECRET),
+            (BODY, HEADER, "whsec_other"),
+            (BODY, None, SECRET),
+        ]:
+            with self.assertRaises(payitgo.SignatureVerificationError):
+                payitgo.Webhook.construct_event(body, header, secret, tolerance=0)
+
+    def test_rejects_non_ascii_signature(self):
+        with self.assertRaisesRegex(payitgo.SignatureVerificationError, "signature does not match"):
+            payitgo.Webhook.construct_event(BODY, "t=1760000000,v1=" + "é" * 64, SECRET, tolerance=0)
+
+    def test_rejects_non_numeric_timestamp(self):
+        header = "t=soon,v1=" + hmac.new(SECRET.encode(), b"soon." + BODY, hashlib.sha256).hexdigest()
+        with self.assertRaisesRegex(payitgo.SignatureVerificationError, "malformed timestamp"):
+            payitgo.Webhook.construct_event(BODY, header, SECRET)
+        self.assertEqual(payitgo.Webhook.construct_event(BODY, header, SECRET, tolerance=0).id, "evt_test_123")
+
+    def test_tolerance(self):
+        with self.assertRaises(payitgo.SignatureVerificationError):
+            payitgo.Webhook.construct_event(BODY, HEADER, SECRET)
+        fresh = sign(SECRET, int(time.time()), BODY)
+        self.assertEqual(payitgo.Webhook.construct_event(BODY, fresh, SECRET).id, "evt_test_123")
+
+
+class ClientTest(unittest.TestCase):
+    def test_checks(self):
+        os.environ.pop("PAYITGO_BASE_URL", None)
+        with self.assertRaises(ValueError):
+            payitgo.Client("pk_123", base_url="http://x")
+        # Without an address the client uses the release's default, or refuses.
+        if payitgo.DEFAULT_BASE_URL:
+            self.assertEqual(payitgo.Client("sk_test_abc")._base_url, payitgo.DEFAULT_BASE_URL.rstrip("/"))
+        else:
+            with self.assertRaises(ValueError):
+                payitgo.Client("sk_test_abc")
+        self.assertFalse(payitgo.Client("sk_test_abc", base_url="http://x").livemode)
+        self.assertTrue(payitgo.Client("sk_live_abc", base_url="http://x").livemode)
+
+
+WEBHOOK = {
+    "livemode": False, "url": "https://shop.example/payitgo/ipn", "secret": "whsec_" + "ab" * 32,
+    "created_at": "2026-10-10T09:00:00Z", "updated_at": "2026-10-10T09:05:00Z",
+}
+DELIVERY = {
+    "id": "whd_1", "merchant_id": "mch_1", "target": "account", "url": WEBHOOK["url"], "event_id": "evt_1",
+    "event_type": "ping", "payload": '{"id":"evt_1","type":"ping"}', "status": "pending", "attempts": 0,
+    "max_attempts": 7, "next_attempt_at": "2026-10-10T12:00:00Z", "created_at": "2026-10-10T12:00:00Z",
+}
+# A payment whose coin the customer chose on the merchant's own page.
+CHOSEN = {
+    "id": "pay_1", "merchant_id": "mch_1", "order_id": "ORD-7", "status": "pending", "livemode": False,
+    "token": "XRP", "chain": "xrp", "deposit_address": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
+    "destination_tag": 1042, "crypto_amount": "20", "received_amount": "0", "usd_amount": "10",
+    "amount_due_usd": "10", "fees_paid_by_customer": False, "network_fee": "0.000012", "network_fee_usd": "0.01",
+    "settlement": "custodial", "received_usd": "0", "rate_locked": "0.5", "deposits": [],
+    "expires_at": "2026-10-10T12:15:00Z", "created_at": "2026-10-10T12:00:00Z",
+    "network_fee_note": "XRP Ledger testnet: test XRP only. Include destination tag — required.",
+    "qr_payload": "xrpl:rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe?amount=20.000000&dt=1042",
+    "checkout_token": "ct_abc", "checkout_url": "https://pay.example/ct_abc", "description": "Order 7",
+    "metadata": {"cart": "42"},
+}
+
+
+class _FakeGateway(BaseHTTPRequestHandler):
+    """Records each request and answers with the next queued (status, body), or echoes a
+    created payment's body back as the payment."""
+
+    def _handle(self):
+        length = int(self.headers.get("Content-Length") or 0)
+        raw = self.rfile.read(length) if length else b""
+        body = json.loads(raw) if raw else None
+        self.server.requests.append({"method": self.command, "path": self.path, "headers": dict(self.headers),
+                                     "body": body})
+        if self.server.replies:
+            status, reply = self.server.replies.pop(0)
+        elif self.path == "/v1/payments":
+            status, reply = 201, dict(body, id="pay_1", status="pending")
+        else:
+            status, reply = 500, {"error": "no reply queued"}
+        data = json.dumps(reply).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    do_GET = do_POST = do_PUT = do_DELETE = _handle
+
+    def log_message(self, *args):
+        pass
+
+
+class WebhookIPNTest(unittest.TestCase):
+    def setUp(self):
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), _FakeGateway)
+        self.server.requests, self.server.replies = [], []
+        threading.Thread(target=self.server.serve_forever, kwargs={"poll_interval": 0.05}, daemon=True).start()
+        self.addCleanup(self.server.server_close)
+        self.addCleanup(self.server.shutdown)
+        self.client = self.make_client()
+
+    def make_client(self, **options):
+        return payitgo.Client("sk_test_abc", base_url="http://127.0.0.1:%d/" % self.server.server_port,
+                            max_retries=0, **options)
+
+    def reply(self, status, body):
+        self.server.replies.append((status, body))
+
+    def request(self, i=0):
+        return self.server.requests[i]
+
+    def test_tokens(self):
+        tokens = [{"token": "USDT_BEP20", "chain": "bsc", "min_usd": "1", "network_fee_usd": "0.01", "amount_due_usd": "40.43", "fee_note": ""}]
+        self.reply(200, {"tokens": tokens})
+        self.assertEqual(self.client.tokens.list(), tokens)
+        self.assertEqual((self.request(0)["method"], self.request(0)["path"]), ("GET", "/v1/tokens"))
+        self.reply(200, {"tokens": tokens})
+        self.client.tokens.list(amount_usd="49.90")
+        self.assertEqual(self.request(1)["path"], "/v1/tokens?amount_usd=49.90")
+
+    def test_get(self):
+        self.reply(200, {"webhook": WEBHOOK})
+        webhook = self.client.webhooks.get()
+        req = self.request()
+        self.assertEqual((req["method"], req["path"], req["body"]), ("GET", "/v1/webhook", None))
+        self.assertEqual(req["headers"]["Authorization"], "Bearer sk_test_abc")
+        self.assertEqual(webhook, WEBHOOK)
+        self.assertEqual(webhook.secret, WEBHOOK["secret"])
+
+    def test_set(self):
+        self.reply(200, {"webhook": WEBHOOK})
+        webhook = self.client.webhooks.set(WEBHOOK["url"])
+        req = self.request()
+        self.assertEqual((req["method"], req["path"]), ("PUT", "/v1/webhook"))
+        self.assertEqual(req["headers"]["Content-Type"], "application/json")
+        self.assertEqual(req["body"], {"url": WEBHOOK["url"]})
+        self.assertEqual(webhook.url, WEBHOOK["url"])
+
+    def test_remove(self):
+        self.reply(200, {"webhook": dict(WEBHOOK, url=None)})
+        webhook = self.client.webhooks.remove()
+        self.assertEqual((self.request()["method"], self.request()["path"]), ("DELETE", "/v1/webhook"))
+        self.assertIsNone(webhook.url)
+        self.assertEqual(webhook.secret, WEBHOOK["secret"])
+
+    def test_test(self):
+        self.reply(202, {"delivery": DELIVERY})
+        delivery = self.client.webhooks.test()
+        req = self.request()
+        self.assertEqual((req["method"], req["path"]), ("POST", "/v1/webhook/test"))
+        self.assertEqual(req["headers"]["Authorization"], "Bearer sk_test_abc")
+        self.assertEqual((delivery.event_type, delivery.status, delivery.target), ("ping", "pending", "account"))
+
+    def test_errors(self):
+        self.reply(400, {"error": "no webhook url is set for this mode: set one first"})
+        with self.assertRaises(payitgo.PayitgoError) as ctx:
+            self.client.webhooks.test()
+        self.assertEqual((ctx.exception.status, ctx.exception.message),
+                         (400, "no webhook url is set for this mode: set one first"))
+        forbidden = "a storefront's key cannot change the account's webhook: set webhook_url on its payments instead"
+        self.reply(403, {"error": forbidden})
+        with self.assertRaises(payitgo.PayitgoError) as ctx:
+            self.client.webhooks.set(WEBHOOK["url"])
+        self.assertEqual((ctx.exception.status, ctx.exception.message), (403, forbidden))
+
+    def test_payment_webhook_url(self):
+        payment = self.client.payments.create("ORD-1", 10)
+        self.assertEqual(self.request(0)["body"], {"order_id": "ORD-1", "amount_usd": "10"})
+        self.assertNotIn("webhook_url", payment)
+        payment = self.client.payments.create("ORD-2", 10, webhook_url="https://shop.example/own")
+        self.assertEqual(self.request(1)["body"]["webhook_url"], "https://shop.example/own")
+        self.assertEqual(payment.webhook_url, "https://shop.example/own")
+
+    def test_payment_webhook_url_default(self):
+        client = self.make_client(webhook_url="https://shop.example/default")
+        payment = client.payments.create("ORD-1", 10)
+        self.assertEqual(self.request(0)["body"]["webhook_url"], "https://shop.example/default")
+        self.assertEqual(payment.webhook_url, "https://shop.example/default")
+        payment = client.payments.create("ORD-2", 10, webhook_url="https://shop.example/own")  # the call's own wins
+        self.assertEqual(self.request(1)["body"]["webhook_url"], "https://shop.example/own")
+        self.assertEqual(payment.webhook_url, "https://shop.example/own")
+
+    def test_payment_select_token(self):
+        self.reply(200, CHOSEN)
+        payment = self.client.payments.select_token("pay_1", "XRP")
+        req = self.request()
+        self.assertEqual((req["method"], req["path"]), ("POST", "/v1/payments/pay_1/token"))
+        self.assertEqual(req["headers"]["Authorization"], "Bearer sk_test_abc")
+        self.assertEqual(req["headers"]["Content-Type"], "application/json")
+        self.assertEqual(req["body"], {"token": "XRP"})
+        self.assertEqual(payment, CHOSEN)
+        self.assertEqual((payment.deposit_address, payment.destination_tag, payment.metadata.cart),
+                         (CHOSEN["deposit_address"], 1042, "42"))
+        # An order id is escaped in the path, as payments.retrieve does.
+        self.reply(200, CHOSEN)
+        self.client.payments.select_token("ORD 7/1", "XRP")
+        self.assertEqual(self.request(1)["path"], "/v1/payments/ORD%207%2F1/token")
+
+    def test_payments_list(self):
+        self.reply(200, {"payments": [], "total": 0, "limit": 10, "offset": 20})
+        page = self.client.payments.list(status="confirmed", store_id="sto_1", limit=10, offset=20)
+        req = self.request()
+        self.assertEqual(req["method"], "GET")
+        self.assertEqual(req["path"], "/v1/payments?status=confirmed&store_id=sto_1&limit=10&offset=20")
+        self.assertEqual((page.total, page.limit, page.offset), (0, 10, 20))
+        self.reply(200, {"payments": [], "total": 0, "limit": 50, "offset": 0})
+        self.client.payments.list()
+        self.assertEqual(self.request(1)["path"], "/v1/payments")
+
+    def test_payment_select_token_chosen(self):
+        self.reply(409, {"error": "the coin for this payment has already been chosen"})
+        with self.assertRaises(payitgo.PayitgoError) as ctx:
+            self.client.payments.select_token("pay_1", "XRP")
+        self.assertEqual((ctx.exception.status, ctx.exception.message),
+                         (409, "the coin for this payment has already been chosen"))
+
+
+class ClientConstructEventTest(unittest.TestCase):
+    def test_client_secret(self):
+        client = payitgo.Client("sk_test_abc", base_url="http://x", webhook_secret=SECRET)
+        self.assertEqual(client.webhooks.construct_event(BODY, HEADER, tolerance=0).id, "evt_test_123")
+        fresh = sign(SECRET, int(time.time()), BODY)
+        self.assertEqual(client.webhooks.construct_event(BODY, fresh).id, "evt_test_123")
+
+    def test_explicit_secret_wins(self):
+        client = payitgo.Client("sk_test_abc", base_url="http://x", webhook_secret="whsec_other")
+        with self.assertRaises(payitgo.SignatureVerificationError):
+            client.webhooks.construct_event(BODY, HEADER, tolerance=0)
+        self.assertEqual(client.webhooks.construct_event(BODY, HEADER, SECRET, tolerance=0).id, "evt_test_123")
+
+    def test_no_secret(self):
+        client = payitgo.Client("sk_test_abc", base_url="http://x")
+        with self.assertRaisesRegex(payitgo.SignatureVerificationError, "no webhook secret"):
+            client.webhooks.construct_event(BODY, HEADER)
+
+
+if __name__ == "__main__":
+    unittest.main()