pyXRocketAPI 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

pyXRocketAPI/api.py

@@ -4,23 +4,11 @@ from typing import Any
 import requests
 
 from .exceptions import xRocketAPIException
-from .models import App, Balance, Cheque, ChequesList, Currency, Invoice, InvoicePaymentAddress, InvoicePaymentsList, InvoicesList, MassPayouts, xPage, Payout, PayoutsList, Rate, Withdrawal, WithdrawalLink, WithdrawalQuotas, WithdrawalsList, xRocketObject
+from .models import App, Balance, Cheque, ChequeCallback, ChequeUrl, ChequesList, Currency, Health, Invoice, InvoiceCallback, InvoiceCustomer, InvoicePaymentAddress, InvoicePaymentsList, InvoiceUrl, InvoicesList, MassPayout, MassPayouts, Payout, PayoutCallback, PayoutsList, Rate, Withdrawal, WithdrawalCallback, WithdrawalLink, WithdrawalQuotas, WithdrawalsList, xPage, xRocketObject
 
 PRODUCTION_API_URL = "https://pay.api.xrocket.exchange"
 TESTNET_API_URL = "https://pay.api.testnet.xrocket.exchange"
 
-
-def _without_none(**values: Any) -> dict[str, Any]:
-    """Keep valid falsey API values while omitting arguments not supplied."""
-    return {key: value for key, value in values.items() if value is not None}
-
-
-def _identifier(first_name: str, first_value: str | None, second_name: str, second_value: str | None) -> dict[str, str]:
-    if first_value is None and second_value is None:
-        raise ValueError(f"Specify {first_name} or {second_name}.")
-    return _without_none(**{first_name: first_value, second_name: second_value})
-
-
 class xRocketPayAPI:
     """Client for the current xRocket Pay API.
 
@@ -28,20 +16,52 @@ class xRocketPayAPI:
     ----------
     token:
         App-specific Pay API Bearer token. Public calls such as
-        ``health_check()`` and ``get_available_currencies()`` do not require
-        one.
+        ``health_check()`` and ``get_available_currencies()`` do not require one.
     testnet:
         Select the xRocket Pay testnet URL. A testnet token is required.
     timeout:
-        Timeout passed to every request, in seconds. ``None`` uses requests'
-        default behaviour.
+        Timeout passed to every request, in seconds.
+        ``None`` uses requests' default behaviour.
+        Default is 30 seconds.
+        A tuple of ``(connect, read)`` timeouts can be passed to override the default for each phase.
     """
 
+    @staticmethod
+    def __without_none(**values: Any) -> dict[str, Any]:
+        """Keep valid falsey API values while omitting arguments not supplied."""
+        return {key: value for key, value in values.items() if value is not None}
+
+    @staticmethod
+    def __identifier(first_name: str, first_value: str | None,
+                     second_name: str, second_value: str | None) -> dict[str, str]:
+        """Return identifier query parameters after validating their presence."""
+        if first_value is None and second_value is None:
+            raise ValueError(f"Specify {first_name} or {second_name}.")
+        return xRocketPayAPI.__without_none(**{first_name: first_value, second_name: second_value})
+
+    @staticmethod
+    def __request_model(value: Any, model_type: type, parameter_name: str) -> dict[str, Any] | None:
+        """Serialize one known nested request model or reject a plain mapping."""
+        if value is None:
+            return None
+        if not isinstance(value, model_type):
+            raise TypeError("{} must be an instance of {}.".format(parameter_name, model_type.__name__))
+        return value.to_dict()
+
+    @staticmethod
+    def __number_as_string(value: str | int | float | None, parameter_name: str) -> str | None:
+        """Encode one numeric API field whose wire type is string."""
+        if value is None:
+            return None
+        if isinstance(value, bool):
+            raise TypeError("{} must be a string or number, not bool.".format(parameter_name))
+        return str(value)
+
     def __init__(
         self,
         token: str | None = None,
         testnet: bool = False,
-        timeout: float | tuple[float, float] | None = 10,
+        timeout: float | tuple[float, float] | None = 30,
     ) -> None:
         self.token = token
         self.timeout = timeout
@@ -113,14 +133,14 @@ class xRocketPayAPI:
         except ValueError as error:
             raise xRocketAPIException("xRocket Pay returned invalid JSON.", status=response.status_code) from error
 
-    def health_check(self) -> xRocketObject:
+    def health_check(self) -> Health:
         """Run the public health check.
 
         API: https://docs.xrocket.exchange/api/pay/reference/http/health-controller-health
 
-        :return: ``xRocketObject``.
+        :return: ``Health``.
         """
-        return xRocketObject.de_json(self._request("GET", "/health", auth_required=False), process_mode=2)
+        return Health.de_json(self._request("GET", "/health", auth_required=False))
 
     def get_app_info(self) -> App:
         """Get information about your application.
@@ -150,7 +170,7 @@ class xRocketPayAPI:
         :return: ``list[Currency]``.
         """
         data = self._request(
-            "GET", "/api/v1/currencies", params=_without_none(kind=kind), auth_required=False
+            "GET", "/api/v1/currencies", params=self.__without_none(kind=kind), auth_required=False
         )
         return [Currency.de_json(item) for item in data]
 
@@ -173,17 +193,17 @@ class xRocketPayAPI:
     def create_invoice(
         self,
         price_currency: str,
-        price_amount: str | None = None,
-        min_payment: str | None = None,
+        price_amount: str | int | float | None = None,
+        min_payment: str | int | float | None = None,
         num_payments: int | None = None,
         payout_currency: str | None = None,
         pay_currencies: Iterable[str] | None = None,
         client_invoice_id: str | None = None,
         description: str | None = None,
         expires_in: int | None = None,
-        callback: Mapping[str, Any] | None = None,
-        url: Mapping[str, Any] | None = None,
-        customer: Mapping[str, Any] | None = None,
+        callback: InvoiceCallback | None = None,
+        url: InvoiceUrl | None = None,
+        customer: InvoiceCustomer | None = None,
         is_fee_paid_by_user: bool | None = None,
         data: Mapping[str, Any] | None = None,
         platform_id: str | None = None,
@@ -193,27 +213,32 @@ class xRocketPayAPI:
         API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-create-invoice
 
         :param price_currency: Invoice price currency (crypto or fiat).
-        :param price_amount: Invoice price amount.
-        :param min_payment: Minimum payment amount (for open-amount invoices).
+        :param price_amount: Invoice price amount. A numeric value is encoded as an API string.
+        :param min_payment: Minimum payment amount (for open-amount invoices). A numeric value is encoded as an API string.
         :param num_payments: Num payments for invoice.
         :param payout_currency: Invoice payout crypto currency.
         :param pay_currencies: Crypto currencies which can be used to pay the invoice.
         :param client_invoice_id: Client Invoice ID as assigned by the client.
         :param description: Description for invoice.
         :param expires_in: Payment expires in milliseconds.
-        :param callback: Callback data.
-        :param url: User redirect urls.
-        :param customer: Customer info.
+        :param callback: Callback data as an ``InvoiceCallback`` instance.
+        :param url: User redirect urls as an ``InvoiceUrl`` instance.
+        :param customer: Customer info as an ``InvoiceCustomer`` instance.
         :param is_fee_paid_by_user: If true, the user pays a commission.
         :param data: Custom user data passed through and returned in callbacks/webhooks (max size 4KB).
         :param platform_id: Platform identifier.
         :return: ``Invoice``.
         """
-        body = _without_none(
-            priceCurrency=price_currency, priceAmount=price_amount, minPayment=min_payment, numPayments=num_payments,
+        body = self.__without_none(
+            priceCurrency=price_currency,
+            priceAmount=self.__number_as_string(price_amount, "price_amount"),
+            minPayment=self.__number_as_string(min_payment, "min_payment"), numPayments=num_payments,
             payoutCurrency=payout_currency, payCurrencies=list(pay_currencies) if pay_currencies is not None else None,
-            clientInvoiceId=client_invoice_id, description=description, expiresIn=expires_in, callback=callback, url=url,
-            customer=customer, isFeePaidByUser=is_fee_paid_by_user, data=data, platformId=platform_id,
+            clientInvoiceId=client_invoice_id, description=description, expiresIn=expires_in,
+            callback=self.__request_model(callback, InvoiceCallback, "callback"),
+            url=self.__request_model(url, InvoiceUrl, "url"),
+            customer=self.__request_model(customer, InvoiceCustomer, "customer"),
+            isFeePaidByUser=is_fee_paid_by_user, data=data, platformId=platform_id,
         )
         return Invoice.de_json(self._request("POST", "/api/v1/invoices", body=body))
 
@@ -231,7 +256,7 @@ class xRocketPayAPI:
         :param limit: No description is provided.
         :return: ``InvoicesList``.
         """
-        params = _without_none(asset=asset, fiat=fiat, ids=list(ids) if ids is not None else None, status=status, cursor=cursor, limit=limit)
+        params = self.__without_none(asset=asset, fiat=fiat, ids=list(ids) if ids is not None else None, status=status, cursor=cursor, limit=limit)
         return InvoicesList.de_json(self._request("GET", "/api/v1/invoices", params=params))
 
     def get_invoice_info(self, invoice_id: str | None = None, client_invoice_id: str | None = None) -> Invoice:
@@ -244,7 +269,7 @@ class xRocketPayAPI:
         :param client_invoice_id: Client Invoice ID assigned by the client. Either invoiceId or clientInvoiceId is required.
         :return: ``Invoice``.
         """
-        return Invoice.de_json(self._request("GET", "/api/v1/invoice", params=_identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id)))
+        return Invoice.de_json(self._request("GET", "/api/v1/invoice", params=self.__identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id)))
 
     def delete_invoice(self, invoice_id: str | None = None, client_invoice_id: str | None = None) -> None:
         """Delete invoice.
@@ -256,7 +281,7 @@ class xRocketPayAPI:
         :param client_invoice_id: Client Invoice ID assigned by the client. Either invoiceId or clientInvoiceId is required.
         :return: ``None``.
         """
-        self._request("DELETE", "/api/v1/invoice", params=_identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id))
+        self._request("DELETE", "/api/v1/invoice", params=self.__identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id))
 
     def get_invoice_payments(self, invoice_id: str | None = None, client_invoice_id: str | None = None,
                          cursor: str | None = None, limit: int | None = None) -> InvoicePaymentsList:
@@ -271,8 +296,8 @@ class xRocketPayAPI:
         :param limit: No description is provided.
         :return: ``InvoicePaymentsList``.
         """
-        params = _identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id)
-        params.update(_without_none(cursor=cursor, limit=limit))
+        params = self.__identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id)
+        params.update(self.__without_none(cursor=cursor, limit=limit))
         return InvoicePaymentsList.de_json(self._request("GET", "/api/v1/invoice/payments", params=params))
 
     def create_invoice_payment_address(self, pay_network: str, invoice_id: str | None = None,
@@ -288,11 +313,11 @@ class xRocketPayAPI:
         """
         return InvoicePaymentAddress.de_json(self._request(
             "POST", "/api/v1/invoices/payments/address",
-            params=_identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id), body={"payNetwork": pay_network},
+            params=self.__identifier("invoiceId", invoice_id, "clientInvoiceId", client_invoice_id), body={"payNetwork": pay_network},
         ))
 
-    def create_cheque(self, asset: str, amount: str, client_cheque_id: str | None = None, password: str | None = None,
-                      description: str | None = None, callback: Mapping[str, Any] | None = None, url: Mapping[str, Any] | None = None,
+    def create_cheque(self, asset: str, amount: str | int | float, client_cheque_id: str | None = None, password: str | None = None,
+                      description: str | None = None, callback: ChequeCallback | None = None, url: ChequeUrl | None = None,
                       target_type: str | None = None, target: str | None = None) -> Cheque:
         """Create cheque.
 
@@ -300,19 +325,20 @@ class xRocketPayAPI:
         Issue a personal cheque to perform an accept-type payout. The amount is reserved from the application balance and can be redeemed by the recipient or cancelled before redemption. When targetType and target are set, only the addressed user is allowed to redeem the cheque.
 
         :param asset: Currency of transfer.
-        :param amount: Cheque amount.
+        :param amount: Cheque amount. A numeric value is encoded as an API string.
         :param client_cheque_id: Unique cheque ID in your system to prevent double spends.
         :param password: Cheque password, the recipient has to enter it to redeem the cheque.
         :param description: Description for cheque.
-        :param callback: Webhook settings for cheque activation updates.
-        :param url: User redirect urls after cheque activation.
+        :param callback: Webhook settings for cheque activation updates as a ``ChequeCallback`` instance.
+        :param url: User redirect urls after cheque activation as a ``ChequeUrl`` instance.
         :param target_type: Target type for cheque, has to be passed together with target.
         :param target: Target for cheque, has to be passed together with targetType.
         :return: ``Cheque``.
         """
-        return Cheque.de_json(self._request("POST", "/api/v1/cheques", body=_without_none(
-            asset=asset, amount=str(amount), clientChequeId=client_cheque_id, password=password, description=description,
-            callback=callback, url=url, targetType=target_type, target=target,
+        return Cheque.de_json(self._request("POST", "/api/v1/cheques", body=self.__without_none(
+            asset=asset, amount=self.__number_as_string(amount, "amount"), clientChequeId=client_cheque_id, password=password, description=description,
+            callback=self.__request_model(callback, ChequeCallback, "callback"),
+            url=self.__request_model(url, ChequeUrl, "url"), targetType=target_type, target=target,
         )))
 
     def get_cheques_list(self, from_date: str | None = None, to_date: str | None = None, target_type: str | None = None,
@@ -331,7 +357,7 @@ class xRocketPayAPI:
         :param limit: No description is provided.
         :return: ``ChequesList``.
         """
-        return ChequesList.de_json(self._request("GET", "/api/v1/cheques", params=_without_none(
+        return ChequesList.de_json(self._request("GET", "/api/v1/cheques", params=self.__without_none(
             fromDate=from_date, toDate=to_date, targetType=target_type, target=target, state=state, cursor=cursor, limit=limit,
         )))
 
@@ -345,7 +371,7 @@ class xRocketPayAPI:
         :param client_cheque_id: Unique cheque id in your system.
         :return: ``Cheque``.
         """
-        return Cheque.de_json(self._request("GET", "/api/v1/cheque", params=_identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id)))
+        return Cheque.de_json(self._request("GET", "/api/v1/cheque", params=self.__identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id)))
 
     def update_cheque(self, description: str, cheque_id: str | None = None, client_cheque_id: str | None = None) -> Cheque:
         """Update cheque.
@@ -358,7 +384,7 @@ class xRocketPayAPI:
         :param client_cheque_id: Unique cheque id in your system.
         :return: ``Cheque``.
         """
-        return Cheque.de_json(self._request("PUT", "/api/v1/cheques", params=_identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id), body={"description": description}))
+        return Cheque.de_json(self._request("PUT", "/api/v1/cheques", params=self.__identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id), body={"description": description}))
 
     def delete_cheque(self, cheque_id: str | None = None, client_cheque_id: str | None = None) -> None:
         """Delete cheque.
@@ -370,10 +396,10 @@ class xRocketPayAPI:
         :param client_cheque_id: Unique cheque id in your system.
         :return: ``None``.
         """
-        self._request("DELETE", "/api/v1/cheques", params=_identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id))
+        self._request("DELETE", "/api/v1/cheques", params=self.__identifier("chequeId", cheque_id, "clientChequeId", client_cheque_id))
 
-    def payout_funds_to_user(self, target: str, target_type: str, asset: str, amount: str, client_payout_id: str | None = None,
-                      description: str | None = None, callback: Mapping[str, Any] | None = None) -> Payout:
+    def create_payout(self, target: str, target_type: str, asset: str, amount: str | int | float, client_payout_id: str | None = None,
+                      description: str | None = None, callback: PayoutCallback | None = None) -> Payout:
         """Payout funds to user.
 
         API: https://docs.xrocket.exchange/api/pay/reference/http/payout-controller-payout
@@ -381,15 +407,15 @@ class xRocketPayAPI:
         :param target: Target.
         :param target_type: Target type.
         :param asset: Asset of transfer.
-        :param amount: Payout amount.
+        :param amount: Payout amount. A numeric value is encoded as an API string.
         :param client_payout_id: Unique payout ID in your system to prevent double spends.
         :param description: Payout description.
-        :param callback: Webhook settings for payout status updates.
+        :param callback: Webhook settings for payout status updates as a ``PayoutCallback`` instance.
         :return: ``Payout``.
         """
-        return Payout.de_json(self._request("POST", "/api/v1/payouts", body=_without_none(
-            target=target, targetType=target_type, asset=asset, amount=str(amount), clientPayoutId=client_payout_id,
-            description=description, callback=callback,
+        return Payout.de_json(self._request("POST", "/api/v1/payouts", body=self.__without_none(
+            target=target, targetType=target_type, asset=asset, amount=self.__number_as_string(amount, "amount"), clientPayoutId=client_payout_id,
+            description=description, callback=self.__request_model(callback, PayoutCallback, "callback"),
         )))
 
     def get_payouts_list(self, from_date: str | None = None, to_date: str | None = None, cursor: str | None = None,
@@ -404,7 +430,7 @@ class xRocketPayAPI:
         :param limit: No description is provided.
         :return: ``PayoutsList``.
         """
-        return PayoutsList.de_json(self._request("GET", "/api/v1/payouts", params=_without_none(fromDate=from_date, toDate=to_date, cursor=cursor, limit=limit)))
+        return PayoutsList.de_json(self._request("GET", "/api/v1/payouts", params=self.__without_none(fromDate=from_date, toDate=to_date, cursor=cursor, limit=limit)))
 
     def get_payout_info(self, payout_id: str | None = None, client_payout_id: str | None = None) -> Payout:
         """Get payout info.
@@ -415,21 +441,26 @@ class xRocketPayAPI:
         :param client_payout_id: Unique payout ID in your system to prevent double spends.
         :return: ``Payout``.
         """
-        return Payout.de_json(self._request("GET", "/api/v1/payout", params=_identifier("payoutId", payout_id, "clientPayoutId", client_payout_id)))
+        return Payout.de_json(self._request("GET", "/api/v1/payout", params=self.__identifier("payoutId", payout_id, "clientPayoutId", client_payout_id)))
 
-    def create_mass_payouts(self, asset: str, payouts: Iterable[Mapping[str, Any]]) -> MassPayouts:
+    def create_mass_payouts(self, asset: str, payouts: Iterable[MassPayout]) -> MassPayouts:
         """Create mass payouts (Telegram users only).
 
         API: https://docs.xrocket.exchange/api/pay/reference/http/mass-payouts-controller-create-mass-payouts
 
         :param asset: Asset of payouts.
-        :param payouts: List of payouts to process.
+        :param payouts: List of ``MassPayout`` instances to process.
         :return: ``MassPayouts``.
         """
-        return MassPayouts.de_json(self._request("POST", "/api/v1/mass-payouts", body={"asset": asset, "payouts": list(payouts)}))
-
-    def withdrawal_funds(self, client_withdrawal_id: str, network: str, address: str, asset: str, amount: str,
-                         comment: str | None = None, callback: Mapping[str, Any] | None = None) -> Withdrawal:
+        payout_data = []
+        for payout in payouts:
+            if not isinstance(payout, MassPayout):
+                raise TypeError("payouts must contain only MassPayout instances.")
+            payout_data.append(payout.to_dict())
+        return MassPayouts.de_json(self._request("POST", "/api/v1/mass-payouts", body={"asset": asset, "payouts": payout_data}))
+
+    def create_withdrawal(self, client_withdrawal_id: str, network: str, address: str, asset: str, amount: str | int | float,
+                         comment: str | None = None, callback: WithdrawalCallback | None = None) -> Withdrawal:
         """Withdrawal funds from application to external wallet.
 
         API: https://docs.xrocket.exchange/api/pay/reference/http/withdrawal-controller-create-withdrawal
@@ -438,14 +469,14 @@ class xRocketPayAPI:
         :param network: Network code.
         :param address: Withdrawal address.
         :param asset: Asset code.
-        :param amount: Withdrawal amount.
+        :param amount: Withdrawal amount. A numeric value is encoded as an API string.
         :param comment: Withdrawal comment.
-        :param callback: Webhook settings for withdrawal status updates.
+        :param callback: Webhook settings for withdrawal status updates as a ``WithdrawalCallback`` instance.
         :return: ``Withdrawal``.
         """
-        return Withdrawal.de_json(self._request("POST", "/api/v1/withdrawals", body=_without_none(
-            clientWithdrawalId=client_withdrawal_id, network=network, address=address, asset=asset, amount=str(amount),
-            comment=comment, callback=callback,
+        return Withdrawal.de_json(self._request("POST", "/api/v1/withdrawals", body=self.__without_none(
+            clientWithdrawalId=client_withdrawal_id, network=network, address=address, asset=asset, amount=self.__number_as_string(amount, "amount"),
+            comment=comment, callback=self.__request_model(callback, WithdrawalCallback, "callback"),
         )))
 
     def get_withdrawals_list(self, from_date: str | None = None, to_date: str | None = None, status: str | None = None,
@@ -461,7 +492,7 @@ class xRocketPayAPI:
         :param limit: No description is provided.
         :return: ``WithdrawalsList``.
         """
-        return WithdrawalsList.de_json(self._request("GET", "/api/v1/withdrawals", params=_without_none(
+        return WithdrawalsList.de_json(self._request("GET", "/api/v1/withdrawals", params=self.__without_none(
             fromDate=from_date, toDate=to_date, status=status, cursor=cursor, limit=limit,
         )))
 
@@ -474,7 +505,7 @@ class xRocketPayAPI:
         :param client_withdrawal_id: Unique withdrawal ID in your system to prevent double spends.
         :return: ``Withdrawal``.
         """
-        return Withdrawal.de_json(self._request("GET", "/api/v1/withdrawal", params=_identifier("withdrawalId", withdrawal_id, "clientWithdrawalId", client_withdrawal_id)))
+        return Withdrawal.de_json(self._request("GET", "/api/v1/withdrawal", params=self.__identifier("withdrawalId", withdrawal_id, "clientWithdrawalId", client_withdrawal_id)))
 
     def get_withdrawal_quotas(self, network: str, asset: str) -> WithdrawalQuotas:
         """Get application withdrawal quotas.
@@ -487,7 +518,7 @@ class xRocketPayAPI:
         """
         return WithdrawalQuotas.de_json(self._request("GET", "/api/v1/withdrawal-quotas", params={"network": network, "asset": asset}))
 
-    def create_withdrawal_link(self, network: str, address: str, asset: str, amount: str, comment: str | None = None,
+    def create_withdrawal_link(self, network: str, address: str, asset: str, amount: str | int | float, comment: str | None = None,
                                platform: str | None = None) -> WithdrawalLink:
         """Create withdrawal link.
 
@@ -496,11 +527,11 @@ class xRocketPayAPI:
         :param network: Network code.
         :param address: Withdrawal address.
         :param asset: Asset code.
-        :param amount: Withdrawal amount.
+        :param amount: Withdrawal amount. A numeric value is encoded as an API string.
         :param comment: Withdrawal comment.
         :param platform: Platform identifier (optional, use only if provided by xRocket).
         :return: ``WithdrawalLink``.
         """
-        return WithdrawalLink.de_json(self._request("POST", "/api/v1/withdrawal-link", body=_without_none(
-            network=network, address=address, asset=asset, amount=str(amount), comment=comment, platform=platform,
+        return WithdrawalLink.de_json(self._request("POST", "/api/v1/withdrawal-link", body=self.__without_none(
+            network=network, address=address, asset=asset, amount=self.__number_as_string(amount, "amount"), comment=comment, platform=platform,
         )))

pyXRocketAPI/models.py

@@ -2,6 +2,31 @@ import json
 from abc import ABC
 
 
+class Dictionaryable(ABC):
+    """Base class for models that can be converted to an API dictionary.
+
+    Subclasses implement :meth:`to_dict` to prepare their fields for use in a
+    JSON request body. ``None`` values are omitted; valid falsey values are
+    retained.
+    """
+
+    def to_dict(self):
+        """Return the model fields as a dictionary accepted by the API.
+
+        :return: API-ready dictionary.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def _number_as_string(value):
+        """Encode one number for an API field whose schema type is string."""
+        if value is None:
+            return None
+        if isinstance(value, bool):
+            raise TypeError("Boolean values are not valid numeric API values.")
+        return str(value)
+
+
 class xRocketObject(ABC):
     """Base class for xRocket Pay API response models.
 
@@ -62,6 +87,54 @@ class xRocketObject(ABC):
         return str(data)
 
 
+# noinspection method-overriding
+class HealthComponent(xRocketObject):
+    """One component reported by the xRocket Pay health check.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/health-controller-health
+
+    :param name: No description is provided.
+    :param status: No description is provided.
+    :param message: No description is provided.
+    """
+    def __init__(self):
+        self.name = None
+        self.status = None
+        self.message = None
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        return super(HealthComponent, cls).de_json(data, process_mode=2)
+
+
+# noinspection method-overriding
+class Health(xRocketObject):
+    """Response returned by the xRocket Pay health-check endpoint.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/health-controller-health
+
+    :param status: No description is provided.
+    :param info: No description is provided.
+    :param error: No description is provided.
+    :param details: No description is provided.
+    """
+    def __init__(self):
+        self.status = None
+        self.info = []
+        self.error = []
+        self.details = []
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        instance = super(Health, cls).de_json(data, process_mode=2)
+        instance.info = [HealthComponent.de_json(item) for item in instance.info]
+        instance.error = [HealthComponent.de_json(item) for item in instance.error]
+        instance.details = [HealthComponent.de_json(item) for item in instance.details]
+        return instance
+
+
 # noinspection method-overriding
 class App(xRocketObject):
     """Current application returned by xRocket Pay.
@@ -101,7 +174,14 @@ class Balance(xRocketObject):
     @classmethod
     def de_json(cls, json_dict):
         data = cls.check_json(json_dict)
-        return super(Balance, cls).de_json(data, process_mode=2)
+        instance = super(Balance, cls).de_json(data, process_mode=2)
+        if instance.balance is not None:
+            instance.balance = float(instance.balance)
+        if instance.available is not None:
+            instance.available = float(instance.available)
+        if instance.holds is not None:
+            instance.holds = float(instance.holds)
+        return instance
 
 
 # noinspection method-overriding
@@ -125,6 +205,86 @@ class InvoiceLinks(xRocketObject):
         return super(InvoiceLinks, cls).de_json(data, process_mode=2)
 
 
+# noinspection method-overriding
+class InvoiceCallback(Dictionaryable, xRocketObject):
+    """Webhook settings for an invoice.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-create-invoice
+
+    :param callbackUrl: Url for notify when order status is changed.
+    :param payload: Custom data sent to webhook.
+    """
+
+    def __init__(self, callbackUrl=None, payload=None):
+        self.callbackUrl = callbackUrl
+        self.payload = payload
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        return super(InvoiceCallback, cls).de_json(data, process_mode=2)
+
+    def to_dict(self):
+        return {key: value for key, value in {
+            "callbackUrl": self.callbackUrl, "payload": self.payload,
+        }.items() if value is not None}
+
+
+# noinspection method-overriding
+class InvoiceUrl(Dictionaryable, xRocketObject):
+    """User redirect URLs for an invoice.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-create-invoice
+
+    :param successUrl: Redirect user to url after successful payment.
+    :param cancelUrl: Redirect user to url after cancel payment.
+    """
+
+    def __init__(self, successUrl=None, cancelUrl=None):
+        self.successUrl = successUrl
+        self.cancelUrl = cancelUrl
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        return super(InvoiceUrl, cls).de_json(data, process_mode=2)
+
+    def to_dict(self):
+        return {key: value for key, value in {
+            "successUrl": self.successUrl, "cancelUrl": self.cancelUrl,
+        }.items() if value is not None}
+
+
+# noinspection method-overriding
+class InvoiceCustomer(Dictionaryable, xRocketObject):
+    """Customer information for an invoice.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-create-invoice
+
+    :param id: Customer id in your app.
+    :param email: Customer email.
+    :param telegramId: Customer telegram ID.
+    :param telegramUsername: Customer telegram username (without @).
+    """
+
+    def __init__(self, id=None, email=None, telegramId=None, telegramUsername=None):
+        self.id = id
+        self.email = email
+        self.telegramId = telegramId
+        self.telegramUsername = telegramUsername
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        return super(InvoiceCustomer, cls).de_json(data, process_mode=2)
+
+    def to_dict(self):
+        return {key: value for key, value in {
+            "id": self.id, "email": self.email, "telegramId": self.telegramId,
+            "telegramUsername": self.telegramUsername,
+        }.items() if value is not None}
+
+
 # noinspection method-overriding
 class Invoice(xRocketObject):
     """Invoice created in xRocket Pay.
@@ -142,10 +302,10 @@ class Invoice(xRocketObject):
     :param createdAt: Invoice creation time.
     :param expiresAt: Invoice expiration time (null if no expiration).
     :param status: Invoice status. **WARNING**: This list may be extended in the future. Always use exact status comparison and handle unknown statuses gracefully.
-    :param callback: No description is provided.
-    :param url: No description is provided.
-    :param customer: No description is provided.
-    :param links: No description is provided.
+    :param callback: Invoice webhook settings.
+    :param url: Invoice user redirect URLs.
+    :param customer: Invoice customer information.
+    :param links: Invoice payment links.
     """
     def __init__(self):
         self.id = None
@@ -168,6 +328,18 @@ class Invoice(xRocketObject):
     def de_json(cls, json_dict):
         data = cls.check_json(json_dict)
         instance = super(Invoice, cls).de_json(data, process_mode=2)
+        if instance.priceAmount is not None:
+            instance.priceAmount = float(instance.priceAmount)
+        if instance.minPayment is not None:
+            instance.minPayment = float(instance.minPayment)
+        if instance.expiresIn is not None:
+            instance.expiresIn = int(instance.expiresIn)
+        if instance.callback is not None:
+            instance.callback = InvoiceCallback.de_json(instance.callback)
+        if instance.url is not None:
+            instance.url = InvoiceUrl.de_json(instance.url)
+        if instance.customer is not None:
+            instance.customer = InvoiceCustomer.de_json(instance.customer)
         if instance.links is not None:
             instance.links = InvoiceLinks.de_json(instance.links)
         return instance
@@ -194,6 +366,54 @@ class ChequeLinks(xRocketObject):
         return super(ChequeLinks, cls).de_json(data, process_mode=2)
 
 
+# noinspection method-overriding
+class ChequeCallback(Dictionaryable, xRocketObject):
+    """Webhook settings for a cheque.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/cheque-controller-create-cheque
+
+    :param callbackUrl: Url for notifying when cheque status changes.
+    :param payload: Custom data sent to webhook along with cheque status updates.
+    """
+    def __init__(self, callbackUrl=None, payload=None):
+        self.callbackUrl = callbackUrl
+        self.payload = payload
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        return super(ChequeCallback, cls).de_json(data, process_mode=2)
+
+    def to_dict(self):
+        return {key: value for key, value in {
+            "callbackUrl": self.callbackUrl, "payload": self.payload,
+        }.items() if value is not None}
+
+
+# noinspection method-overriding
+class ChequeUrl(Dictionaryable, xRocketObject):
+    """User redirect URLs for a cheque.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/cheque-controller-create-cheque
+
+    :param successUrl: Redirect user to URL after successful cheque activation.
+    :param cancelUrl: Redirect user to URL after cheque activation is cancelled/failed.
+    """
+    def __init__(self, successUrl=None, cancelUrl=None):
+        self.successUrl = successUrl
+        self.cancelUrl = cancelUrl
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        return super(ChequeUrl, cls).de_json(data, process_mode=2)
+
+    def to_dict(self):
+        return {key: value for key, value in {
+            "successUrl": self.successUrl, "cancelUrl": self.cancelUrl,
+        }.items() if value is not None}
+
+
 # noinspection method-overriding
 class Cheque(xRocketObject):
     """Cheque created in xRocket Pay.
@@ -209,8 +429,8 @@ class Cheque(xRocketObject):
     :param links: Cheque activation links.
     :param state: Cheque state.
     :param deleted: Cheque is cancelled and the reserved funds are returned to the application balance.
-    :param callback: No description is provided.
-    :param url: No description is provided.
+    :param callback: Cheque webhook settings.
+    :param url: Cheque user redirect URLs.
     """
     def __init__(self):
         self.chequeId = None
@@ -231,9 +451,37 @@ class Cheque(xRocketObject):
         instance = super(Cheque, cls).de_json(data, process_mode=2)
         if instance.links is not None:
             instance.links = ChequeLinks.de_json(instance.links)
+        if instance.callback is not None:
+            instance.callback = ChequeCallback.de_json(instance.callback)
+        if instance.url is not None:
+            instance.url = ChequeUrl.de_json(instance.url)
         return instance
 
 
+# noinspection method-overriding
+class PayoutCallback(Dictionaryable, xRocketObject):
+    """Webhook settings for a payout.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/payout-controller-payout
+
+    :param callbackUrl: Url for notify when payout status is changed.
+    :param payload: Custom data sent to webhook.
+    """
+    def __init__(self, callbackUrl=None, payload=None):
+        self.callbackUrl = callbackUrl
+        self.payload = payload
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        return super(PayoutCallback, cls).de_json(data, process_mode=2)
+
+    def to_dict(self):
+        return {key: value for key, value in {
+            "callbackUrl": self.callbackUrl, "payload": self.payload,
+        }.items() if value is not None}
+
+
 # noinspection method-overriding
 class Payout(xRocketObject):
     """Payout from the current application to a user.
@@ -264,7 +512,36 @@ class Payout(xRocketObject):
     @classmethod
     def de_json(cls, json_dict):
         data = cls.check_json(json_dict)
-        return super(Payout, cls).de_json(data, process_mode=2)
+        instance = super(Payout, cls).de_json(data, process_mode=2)
+        if instance.amount is not None:
+            instance.amount = float(instance.amount)
+        if instance.callback is not None:
+            instance.callback = PayoutCallback.de_json(instance.callback)
+        return instance
+
+
+# noinspection method-overriding
+class WithdrawalCallback(Dictionaryable, xRocketObject):
+    """Webhook settings for a withdrawal.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/withdrawal-controller-create-withdrawal
+
+    :param callbackUrl: Url for notify when withdrawal status is changed.
+    :param payload: Custom data sent to webhook.
+    """
+    def __init__(self, callbackUrl=None, payload=None):
+        self.callbackUrl = callbackUrl
+        self.payload = payload
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        return super(WithdrawalCallback, cls).de_json(data, process_mode=2)
+
+    def to_dict(self):
+        return {key: value for key, value in {
+            "callbackUrl": self.callbackUrl, "payload": self.payload,
+        }.items() if value is not None}
 
 
 # noinspection method-overriding
@@ -299,7 +576,12 @@ class Withdrawal(xRocketObject):
     @classmethod
     def de_json(cls, json_dict):
         data = cls.check_json(json_dict)
-        return super(Withdrawal, cls).de_json(data, process_mode=2)
+        instance = super(Withdrawal, cls).de_json(data, process_mode=2)
+        if instance.amount is not None:
+            instance.amount = float(instance.amount)
+        if instance.callback is not None:
+            instance.callback = WithdrawalCallback.de_json(instance.callback)
+        return instance
 
 
 # noinspection method-overriding
@@ -360,7 +642,10 @@ class Rate(xRocketObject):
     @classmethod
     def de_json(cls, json_dict):
         data = cls.check_json(json_dict)
-        return super(Rate, cls).de_json(data, process_mode=2)
+        instance = super(Rate, cls).de_json(data, process_mode=2)
+        if instance.rate is not None:
+            instance.rate = float(instance.rate)
+        return instance
 
 
 # noinspection method-overriding
@@ -398,7 +683,10 @@ class CursorPagination(xRocketObject):
     @classmethod
     def de_json(cls, json_dict):
         data = cls.check_json(json_dict)
-        return super(CursorPagination, cls).de_json(data, process_mode=2)
+        instance = super(CursorPagination, cls).de_json(data, process_mode=2)
+        if instance.total is not None:
+            instance.total = int(instance.total)
+        return instance
 
 
 # noinspection method-overriding
@@ -418,6 +706,147 @@ class InvoicePaymentsPagination(xRocketObject):
         return super(InvoicePaymentsPagination, cls).de_json(data, process_mode=2)
 
 
+# noinspection method-overriding
+class InvoicePaymentPayer(xRocketObject):
+    """Payer information for an invoice payment transaction.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-get-invoice-payments
+
+    :param email: Payer email.
+    :param telegramId: Payer telegram ID.
+    :param telegramUsername: Payer telegram username (without @).
+    """
+    def __init__(self):
+        self.email = None
+        self.telegramId = None
+        self.telegramUsername = None
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        return super(InvoicePaymentPayer, cls).de_json(data, process_mode=2)
+
+
+# noinspection method-overriding
+class InvoicePaymentTransactionBlockchainDetails(xRocketObject):
+    """Blockchain-specific details of an invoice payment transaction.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-get-invoice-payments
+
+    :param network: Blockchain network code.
+    :param txHash: Transaction hash.
+    :param amount: Amount in this specific transaction.
+    :param currency: Currency of this transaction.
+    :param status: On-chain status. **WARNING**: This list may be extended in the future. Treat unknown statuses as "in progress".
+    """
+    def __init__(self):
+        self.network = None
+        self.txHash = None
+        self.amount = None
+        self.currency = None
+        self.status = None
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        instance = super(InvoicePaymentTransactionBlockchainDetails, cls).de_json(data, process_mode=2)
+        if instance.amount is not None:
+            instance.amount = float(instance.amount)
+        return instance
+
+
+# noinspection method-overriding
+class InvoiceInternalTransaction(xRocketObject):
+    """Internal transaction belonging to an invoice payment.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-get-invoice-payments
+
+    :param id: Payment id.
+    :param status: Payment status. **WARNING**: This list may be extended in the future. Use exact string comparison and treat unknown statuses as "in progress".
+    :param payAmount: Amount payer sent (gross, before fees). Null when payment is created but amount is not yet known.
+    :param payCurrency: Currency payer used. Null when payment is created but currency is not yet known.
+    :param receiveAmount: Amount merchant receives after fees (in invoice priceCurrency). Null until payment is finalized.
+    :param receiveCurrency: Currency merchant receives (= invoice priceCurrency). Null until payment is finalized.
+    :param comment: Payer comment.
+    :param payer: Payer information.
+    :param createdAt: Payment creation time.
+    :param finalizedAt: When payment reached final state (null for in-progress payments).
+    :param type: Payment type.
+    """
+    def __init__(self):
+        self.id = None
+        self.status = None
+        self.payAmount = None
+        self.payCurrency = None
+        self.receiveAmount = None
+        self.receiveCurrency = None
+        self.comment = None
+        self.payer = None
+        self.createdAt = None
+        self.finalizedAt = None
+        self.type = None
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        instance = super(InvoiceInternalTransaction, cls).de_json(data, process_mode=2)
+        if instance.payAmount is not None:
+            instance.payAmount = float(instance.payAmount)
+        if instance.receiveAmount is not None:
+            instance.receiveAmount = float(instance.receiveAmount)
+        if instance.payer is not None:
+            instance.payer = InvoicePaymentPayer.de_json(instance.payer)
+        return instance
+
+
+# noinspection method-overriding
+class InvoiceBlockchainTransaction(xRocketObject):
+    """Blockchain transaction belonging to an invoice payment.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-get-invoice-payments
+
+    :param id: Payment id.
+    :param status: Payment status. **WARNING**: This list may be extended in the future. Use exact string comparison and treat unknown statuses as "in progress".
+    :param payAmount: Amount payer sent (gross, before fees). Null when payment is created but amount is not yet known.
+    :param payCurrency: Currency payer used. Null when payment is created but currency is not yet known.
+    :param receiveAmount: Amount merchant receives after fees (in invoice priceCurrency). Null until payment is finalized.
+    :param receiveCurrency: Currency merchant receives (= invoice priceCurrency). Null until payment is finalized.
+    :param comment: Payer comment.
+    :param payer: Payer information.
+    :param createdAt: Payment creation time.
+    :param finalizedAt: When payment reached final state (null for in-progress payments).
+    :param type: Payment type.
+    :param tx: Blockchain-specific details. Present only for ``type=blockchain`` transactions.
+    """
+    def __init__(self):
+        self.id = None
+        self.status = None
+        self.payAmount = None
+        self.payCurrency = None
+        self.receiveAmount = None
+        self.receiveCurrency = None
+        self.comment = None
+        self.payer = None
+        self.createdAt = None
+        self.finalizedAt = None
+        self.type = None
+        self.tx = None
+
+    @classmethod
+    def de_json(cls, json_dict):
+        data = cls.check_json(json_dict)
+        instance = super(InvoiceBlockchainTransaction, cls).de_json(data, process_mode=2)
+        if instance.payAmount is not None:
+            instance.payAmount = float(instance.payAmount)
+        if instance.receiveAmount is not None:
+            instance.receiveAmount = float(instance.receiveAmount)
+        if instance.payer is not None:
+            instance.payer = InvoicePaymentPayer.de_json(instance.payer)
+        if instance.tx is not None:
+            instance.tx = InvoicePaymentTransactionBlockchainDetails.de_json(instance.tx)
+        return instance
+
+
 # noinspection method-overriding
 class InvoicePayment(xRocketObject):
     """A payment made for an invoice.
@@ -425,7 +854,7 @@ class InvoicePayment(xRocketObject):
     API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-get-invoice-payments
 
     :param id: Unique payment id. Use it to match webhook events with the invoice payments endpoint.
-    :param status: Invoice status. **WARNING**: This list may be extended in the future. Always use exact status comparison and handle unknown statuses gracefully.
+    :param status: Payment status. **WARNING**: This list may be extended in the future. Use exact string comparison and treat unknown statuses as "in progress".
     :param finalizedAt: When payment reached final state (null for in-progress payments).
     :param payAmount: Gross amount payer sent in total across all transactions of this payment (before fees).
     :param payCurrency: Currency payer used.
@@ -446,7 +875,22 @@ class InvoicePayment(xRocketObject):
     @classmethod
     def de_json(cls, json_dict):
         data = cls.check_json(json_dict)
-        return super(InvoicePayment, cls).de_json(data, process_mode=2)
+        instance = super(InvoicePayment, cls).de_json(data, process_mode=2)
+        if instance.payAmount is not None:
+            instance.payAmount = float(instance.payAmount)
+        if instance.receiveAmount is not None:
+            instance.receiveAmount = float(instance.receiveAmount)
+        transactions = []
+        for transaction in instance.transactions:
+            transaction_data = cls.check_json(transaction)
+            if transaction_data.get("type") == "internal":
+                transactions.append(InvoiceInternalTransaction.de_json(transaction_data))
+            elif transaction_data.get("type") == "blockchain":
+                transactions.append(InvoiceBlockchainTransaction.de_json(transaction_data))
+            else:
+                transactions.append(xRocketObject.de_json(transaction_data, process_mode=2))
+        instance.transactions = transactions
+        return instance
 
 
 # noinspection method-overriding
@@ -566,7 +1010,10 @@ class InvoicePaymentAddress(xRocketObject):
     @classmethod
     def de_json(cls, json_dict):
         data = cls.check_json(json_dict)
-        return super(InvoicePaymentAddress, cls).de_json(data, process_mode=2)
+        instance = super(InvoicePaymentAddress, cls).de_json(data, process_mode=2)
+        if instance.minAmount is not None:
+            instance.minAmount = float(instance.minAmount)
+        return instance
 
 
 # noinspection method-overriding
@@ -589,7 +1036,14 @@ class WithdrawalQuotas(xRocketObject):
     @classmethod
     def de_json(cls, json_dict):
         data = cls.check_json(json_dict)
-        return super(WithdrawalQuotas, cls).de_json(data, process_mode=2)
+        instance = super(WithdrawalQuotas, cls).de_json(data, process_mode=2)
+        if instance.withdrawMinSize is not None:
+            instance.withdrawMinSize = float(instance.withdrawMinSize)
+        if instance.withdrawFee is not None:
+            instance.withdrawFee = float(instance.withdrawFee)
+        if instance.precision is not None:
+            instance.precision = int(instance.precision)
+        return instance
 
 
 # noinspection method-overriding
@@ -613,6 +1067,42 @@ class WithdrawalLink(xRocketObject):
         return super(WithdrawalLink, cls).de_json(data, process_mode=2)
 
 
+# noinspection method-overriding
+class MassPayout(Dictionaryable, xRocketObject):
+    """One payout supplied to a mass-payout request.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/mass-payouts-controller-create-mass-payouts
+
+    :param target: Target.
+    :param targetType: Target type (only TelegramUserId is supported for mass payouts).
+    :param amount: Payout amount.
+    :param clientPayoutId: Unique payout ID in your system to prevent double spends.
+    :param description: Payout description.
+    :param callback: Webhook settings for payout status updates.
+    """
+    def __init__(self, target=None, targetType=None, amount=None, clientPayoutId=None,
+                 description=None, callback=None):
+        self.target = target
+        self.targetType = targetType
+        self.amount = amount
+        self.clientPayoutId = clientPayoutId
+        self.description = description
+        self.callback = callback
+
+    def to_dict(self):
+        if self.callback is not None and not isinstance(self.callback, PayoutCallback):
+            raise TypeError("callback must be an instance of PayoutCallback.")
+        data = {
+            "target": self.target,
+            "targetType": self.targetType,
+            "amount": self._number_as_string(self.amount),
+            "clientPayoutId": self.clientPayoutId,
+            "description": self.description,
+            "callback": self.callback.to_dict() if self.callback is not None else None,
+        }
+        return {key: value for key, value in data.items() if value is not None}
+
+
 # noinspection method-overriding
 class MassPayoutReason(xRocketObject):
     """Problem details for one failed mass payout.
@@ -665,6 +1155,8 @@ class MassPayoutError(xRocketObject):
     def de_json(cls, json_dict):
         data = cls.check_json(json_dict)
         instance = super(MassPayoutError, cls).de_json(data, process_mode=2)
+        if instance.amount is not None:
+            instance.amount = float(instance.amount)
         if instance.reason is not None:
             instance.reason = MassPayoutReason.de_json(instance.reason)
         return instance

pyXRocketAPI/version.py

@@ -1,3 +1,3 @@
 """Package version, read by the build configuration."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

pyXRocketAPI/webhooks.py

@@ -58,8 +58,6 @@ track invoice completion only when ``event`` is
 ``invoice_status_changed`` and ``event.data.invoice.status`` is ``paid``.
 Payment finality is indicated by ``event.data.payment.finalizedAt`` not being
 ``None``, rather than by relying on one fixed status value.
-
-AI generated. Manually validated.
 """
 
 import hashlib

{pyxrocketapi-0.2.0.dist-info → pyxrocketapi-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyXRocketAPI
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python client for the xRocket Pay API
 Author: Badiboy
 License-Expression: MIT
@@ -47,6 +47,40 @@ For integration testing, use the xRocket testnet instead of production:
 client = xRocketPayAPI(token="testnet-token", testnet=True)
 ```
 
+## Nested request models
+
+Known nested API objects are passed as model instances, not dictionaries. The
+same models deserialize API responses and implement `to_dict()` for request
+bodies.
+
+```python
+from pyXRocketAPI import InvoiceCallback, InvoiceCustomer, InvoiceUrl, xRocketPayAPI
+
+client = xRocketPayAPI(token="your-pay-api-token")
+invoice = client.create_invoice(
+    price_currency="USDT",
+    price_amount="10.00",
+    callback=InvoiceCallback(
+        callbackUrl="https://example.com/webhooks/invoice",
+        payload={"order_id": "123"},
+    ),
+    url=InvoiceUrl(
+        successUrl="https://example.com/success",
+        cancelUrl="https://example.com/cancel",
+    ),
+    customer=InvoiceCustomer(
+        id="customer-123",
+        email="customer@example.com",
+        telegramId="123456789",
+    ),
+    data={"internal_order_id": "123"},
+)
+```
+
+`payload` and `data` remain ordinary dictionaries because xRocket defines them
+as arbitrary JSON objects without a fixed schema. Use `MassPayout` instances
+for every item passed to `create_mass_payouts()`.
+
 ## Safety
 
 The token grants access to the application and must not be committed to source control. Financial POST operations are not retried automatically. Supply and retain the relevant client identifier (`client_invoice_id`, `client_payout_id`, `client_cheque_id`, or `client_withdrawal_id`) so that a timed-out operation can be reconciled safely.

pyxrocketapi-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pyXRocketAPI/__init__.py,sha256=3zwtjTkq3OUBFdzRbXDbPj7cw1T0FVEbq0ZpM9BBziE,105
+pyXRocketAPI/api.py,sha256=QZ7f3i-j1Ku9v74avHE8FIIpePfkbLgZz-lRA4hMVZw,28920
+pyXRocketAPI/exceptions.py,sha256=4In1-OCoLSzgw7O9XTvr7z3uLg7jtE31bvDijMcCeFg,1255
+pyXRocketAPI/models.py,sha256=jiQJlz3YYe0dHlMo61mf3UKCJqBlLXIl0uBdRnk4lkc,43563
+pyXRocketAPI/version.py,sha256=9qdh2HVo2HCzHUvRO0ud8rwcZZnchxg61QL5HU8HUSw,79
+pyXRocketAPI/webhooks.py,sha256=Q11biIxchjwnWehb3-216hx4n1ItBMtoj-W2vsSS_7U,19184
+pyxrocketapi-0.3.0.dist-info/licenses/LICENSE,sha256=iw-28FPO0DiYiTwy8rfgljZxjhA12F5hhqHe_BpYW-o,1064
+pyxrocketapi-0.3.0.dist-info/METADATA,sha256=X66veBTUkkp3MM9UTnC4LW60lqpLsQn2zZJCBWOTvZY,3451
+pyxrocketapi-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pyxrocketapi-0.3.0.dist-info/top_level.txt,sha256=33Ju2GBtWw8-eJeVkNtL7TR1g7SV-g9_3dw_Y56KvmU,13
+pyxrocketapi-0.3.0.dist-info/RECORD,,

pyxrocketapi-0.2.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-pyXRocketAPI/__init__.py,sha256=3zwtjTkq3OUBFdzRbXDbPj7cw1T0FVEbq0ZpM9BBziE,105
-pyXRocketAPI/api.py,sha256=5LJJf5q3o1xJS5uIRJrMQ-VQ_o-q5jWVtsnPqvkuW1M,26164
-pyXRocketAPI/exceptions.py,sha256=4In1-OCoLSzgw7O9XTvr7z3uLg7jtE31bvDijMcCeFg,1255
-pyXRocketAPI/models.py,sha256=8Fsw2fRsYJKIT6Sjqrvx-Zkm58TUaBgPshXZ54EtJxI,24154
-pyXRocketAPI/version.py,sha256=VvY0Say_zvbS0e6COcolPJITN1i-2rYEQsWDPBecsOs,79
-pyXRocketAPI/webhooks.py,sha256=wqACD1yQCaIPWHtwD1_HBcgqXdrKbpmAwtNCiOThZ84,19219
-pyxrocketapi-0.2.0.dist-info/licenses/LICENSE,sha256=iw-28FPO0DiYiTwy8rfgljZxjhA12F5hhqHe_BpYW-o,1064
-pyxrocketapi-0.2.0.dist-info/METADATA,sha256=zM421Y7nyXhFvXMFUMZ5QfZEVFpgn0kmQIbJhfi7ARE,2349
-pyxrocketapi-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-pyxrocketapi-0.2.0.dist-info/top_level.txt,sha256=33Ju2GBtWw8-eJeVkNtL7TR1g7SV-g9_3dw_Y56KvmU,13
-pyxrocketapi-0.2.0.dist-info/RECORD,,