payra-sdk 1.2.3__py3-none-any.whl → 1.2.5__py3-none-any.whl

payra_sdk/order_verification.py

@@ -66,37 +66,84 @@ class PayraOrderVerification:
 
         return random.choice(urls)
 
+
     def is_order_paid(self, order_id: str) -> dict:
         """
         Calls the Payra Forward contract to check if an order is paid.
         """
         try:
-            # encode isOrderPaid call manually
-            core_fn_selector = PayraUtils.function_selector(self.core_fn)
-            encoded_params = self.web3.codec.encode(
-                [inp["type"] for inp in self.core_fn["inputs"]],
+            raw = self._call_core_function(
+                "isOrderPaid",
                 [int(self.merchant_id), order_id]
             )
-            data = core_fn_selector + encoded_params.hex()
 
-            # call forward()
-            result = self.forward_contract.functions.forward("0x" + data).call()
+            decoded = self.web3.codec.decode(["bool"], raw)
+
+            return {
+                "success": True,
+                "paid": bool(decoded[0]),
+                "error": None
+            }
+
+        except Exception as e:
+            return {
+                "success": False,
+                "paid": None,
+                "error": str(e)
+            }
+
+
+    def get_order_status(self, order_id: str) -> dict:
+        """
+        Calls the Payra Forward contract to get order status.
+        """
+        try:
+            raw = self._call_core_function(
+                "getOrderStatus",
+                [int(self.merchant_id), order_id]
+            )
 
-            # decode result
             decoded = self.web3.codec.decode(
-                [out["type"] for out in self.core_fn["outputs"]],
-                result
+                ["bool", "address", "uint256", "uint256", "uint256"],
+                raw
             )
 
             return {
                 "success": True,
+                "error": None,
                 "paid": bool(decoded[0]),
-                "error": None
+                "token": decoded[1],
+                "amount": int(decoded[2]),
+                "fee": int(decoded[3]),
+                "timestamp": int(decoded[4]),
             }
 
         except Exception as e:
             return {
                 "success": False,
+                "error": str(e),
                 "paid": None,
-                "error": str(e)
+                "token": None,
+                "amount": None,
+                "fee": None,
+                "timestamp": None,
             }
+
+    def _call_core_function(self, function_name: str, params: list) -> bytes:
+        """
+        Calls Payra Core contract via Forward and returns raw bytes.
+        """
+        core_fn = PayraUtils.find_function(self.abi, function_name)
+
+        selector = PayraUtils.function_selector(core_fn)
+
+        encoded_params = self.web3.codec.encode(
+            [inp["type"] for inp in core_fn["inputs"]],
+            params
+        )
+
+        data = selector + encoded_params.hex()
+
+        return self.forward_contract.functions.forward(
+            "0x" + data
+        ).call()

payra_sdk/utils.py

@@ -84,11 +84,11 @@ class PayraUtils:
         Default cache time: 720 minutes (12 hours).
         """
 
-        api_key = os.getenv("EXCHANGE_RATE_API_KEY")
+        api_key = os.getenv("PAYRA_EXCHANGE_RATE_API_KEY")
         if not api_key:
-            raise InvalidArgumentError("EXCHANGE_RATE_API_KEY is not set in .env")
+            raise InvalidArgumentError("PAYRA_EXCHANGE_RATE_API_KEY is not set in .env")
 
-        cache_minutes = int(os.getenv("EXCHANGE_RATE_CACHE_TIME", 720))
+        cache_minutes = int(os.getenv("PAYRA_EXCHANGE_RATE_CACHE_TIME", 720))
         cache_ttl = cache_minutes * 60
 
         api_url = f"https://v6.exchangerate-api.com/v6/{api_key}/latest/USD"

{payra_sdk-1.2.3.dist-info → payra_sdk-1.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: payra_sdk
-Version: 1.2.3
+Version: 1.2.5
 Summary: Python SDK for Payra payment signature generation (backend)
 Author: Your Name
 Author-email: Wraith <contact@payra.cash>
@@ -26,7 +26,7 @@ Dynamic: license-file
 
 # Payra Python SDK
 
-Official Python SDK for integrating **Payra's on-chain payment system** into your backend applications.
+Official **Python SDK** for integrating **Payra's on-chain payment system** into your backend applications.
 
 This SDK provides:
 - Secure generation of **ECDSA signatures** compatible with the Payra smart contract — used for order payment verification.
@@ -36,40 +36,40 @@ This SDK provides:
 
 The typical flow for signing and verifying a Payra transaction:
 
-1. The **frontend** prepares all required payment parameters:
-   - **Network** – blockchain name (e.g. Polygon, Linea)
-   - **Token address** – ERC-20 token contract address
-   - **Order ID** – unique order identifier
-   - **AmountWei** – already converted to the smallest unit (e.g. wei, 10⁶)
-   - **Timestamp** – Unix timestamp of the order
-   - **Payer wallet address**
-
-2. The frontend sends these parameters to your **backend**.
-3. The **backend** uses this SDK to generate a cryptographic **ECDSA signature** with its private key (performed **offline**).
-4. The backend returns the generated signature to the frontend.
-5. The **frontend** calls the Payra smart contract (`payOrder`) with all parameters **plus** the signature.
+1.  The  **frontend**  prepares all required payment parameters:
+    -   **Network**  – blockchain name (e.g. Polygon, Linea)
+    -   **Token address**  – ERC-20 token contract address
+    -   **Order ID**  – unique order identifier
+    -   **Amount Wei**  – already converted to the smallest unit (e.g. wei, 10⁶)
+    -   **Timestamp**  – Unix timestamp of the order
+    -   **Payer wallet address**  – the wallet address from which the user will make the on-chain payment
+2.  The frontend sends these parameters to your  **backend**.
+3.  The  **backend**  uses this SDK to generate a cryptographic  **ECDSA signature**  with its private key (performed  **offline**).
+4.  The backend returns the generated signature to the frontend.
+5.  The  **frontend**  calls the Payra smart contract (`payOrder`) with all parameters  **plus**  the signature.
 
 This process ensures full compatibility between your backend and Payra’s on-chain verification logic.
 
 ## Features
 
-- Generates **Ethereum ECDSA signatures** using the `secp256k1` curve.  
+- Generates **Ethereum ECDSA signatures** using the `secp256k1` curve.
 - Fully compatible with **Payra's Solidity smart contracts** (`ERC-1155` payment verification).  
-- Includes built-in **ABI encoding and decoding** via [`web3.py`](https://github.com/ethereum/web3.py).  
-- Supports environment-based configuration (`.env`) for managing multiple blockchain networks.  
+- Includes built-in **ABI encoding and decoding** via `web3.php`.
+- Supports `.env` and  `config/payra.php` configuration for multiple blockchain networks.  
+- Laravel IoC container integration (easy dependency injection)
 - Verifies **order payment status directly on-chain** via RPC or blockchain explorer API.  
-- Provides **secure backend integration** using merchant private keys.  
+- Provides **secure backend integration** for signing and verifying transactions.
 - Includes optional utility helpers for:
-  - **Currency conversion** (via [ExchangeRate API](https://www.exchangerate-api.com/))  
-  - **USD ⇄ WEI** conversion for token precision handling.  
+  - **Currency conversion** (via [ExchangeRate API](https://www.exchangerate-api.com/))
+  - **USD ⇄ WEI** conversion for token precision handling.
 
 ## Setup
 
 Before installing this package, make sure you have an active **Payra** account:
 
-👉 [https://payra.cash](https://payra.cash)
+[https://payra.cash/products/on-chain-payments/merchant-registration](https://payra.cash/products/on-chain-payments/merchant-registration)
 
-You will need:
+Before installing this package, make sure you have a **MerchantID**
 
 - Your **Merchant ID** (unique for each blockchain network)  
 - Your **Private Key** (used to sign Payra transactions securely)
@@ -118,13 +118,13 @@ This SDK requires:
 
 ## Environment Configuration
 
-Create a (`.env`) file in your project root (you can copy from example):
+Create a `.env` file in your project root (you can copy from example):
 
 ```bash
 cp .env.example .env
 ```
 
-This file stores your **private configuration** and connection settings for all supported networks.  Never commit  (`.env`)  to version control.
+This file stores your **private configuration** and connection settings for all supported networks.  Never commit `.env` to version control.
 
 ### Required Variables
 
@@ -133,8 +133,9 @@ This file stores your **private configuration** and connection settings for all
 Used for automatic fiat → USD conversions via the built-in Payra utilities.
 
 ```bash
-EXCHANGE_RATE_API_KEY=         # Your ExchangeRate API key (from exchangerate-api.com)
-EXCHANGE_RATE_CACHE_TIME=720   # Cache duration in minutes (default: 720 = 12h)
+# Optional — only needed if you want to use the built-in currency conversion helper
+PAYRA_EXCHANGE_RATE_API_KEY=         # Your ExchangeRate API key (from exchangerate-api.com)
+PAYRA_EXCHANGE_RATE_CACHE_TIME=720   # Cache duration in minutes (default: 720 = 12h)
 
 PAYRA_POLYGON_CORE_FORWARD_CONTRACT_ADDRESS=0xf30070da76B55E5cB5750517E4DECBD6Cc5ce5a8
 PAYRA_POLYGON_PRIVATE_KEY=
@@ -158,7 +159,7 @@ PAYRA_LINEA_RPC_URL_2=
 #### Important Notes
 
 -   The cache automatically refreshes when it expires.    
--   You can adjust the cache duration by setting  `EXCHANGE_RATE_CACHE_TIME`:
+-   You can adjust the cache duration by setting  `PAYRA_EXCHANGE_RATE_CACHE_TIME`:
     -   `5`  → cache for 5 minutes
     -   `60`  → cache for 1 hour
     -   `720`  → cache for 12 hours (default)
@@ -208,24 +209,89 @@ except Exception as e:
     print(f"Unexpected error: {e}")
 ```
 
+#### Input Parameters
+
+| Field         | Type     | Description                                  |
+|--------------|----------|----------------------------------------------|
+| **`network`**    | `string` | Selected network name                        |
+| **`tokenAddress`** | `string` | ERC20 token contract address                 |
+| **`orderId`**     | `string` | Unique order reference (e.g. ORDER-123)      |
+| **`amountWei`**      | `string` or `integer` | Token amount in smallest unit (e.g. wei)     |
+| **`timestamp`**   | `number` | Unix timestamp of signature creation         |
+| **`payerAddress`**   | `string` | Payer Wallet Address      
+
 #### Behind the Scenes
 
 1.  The backend converts the amount to the smallest blockchain unit (e.g. wei).
-3.  A  `PayraSignatureGenerator`  instance is created using your private key from  (`.env`).
+3.  A  `PayraSignatureGenerator`  instance is created using your private key from `.env`
 4.  It generates an ECDSA signature that is fully verifiable on-chain by the Payra smart contract.
 5.  The resulting signature should be sent to the **frontend**, which must call `payOrder(...)` using the same parameters (`timestamp`, `orderId`, `amount`, `tokenAddress`, etc.) that were used to generate the signature.
 
 ---
 
-### Checking On-Chain Order Status
+### Get Order Status
+
+Retrieve **full payment details** for a specific order from the Payra smart contract. This method returns the complete on-chain payment data associated with the order, including:
+
+-   whether the order has been paid,
+-   the payment token address,
+-   the paid amount,
+-   the fee amount,
+-   and the payment timestamp.
+
+Use this method when you need  **detailed information**  about the payment or want to display full transaction data.
+
+```python
+from payra_sdk import PayraOrderVerification, PayraSDKException
+
+try:
+    ORDER_ID = "ORDER-1765138911744-126-5"
+
+    # Initialize verifier for a specific network
+    verifier = PayraOrderVerification("polygon")
+
+    print("\nGet order status...")
+    result = verifier.get_order_status(ORDER_ID)
+
+    print("Order ID:", ORDER_ID)
+    print("Result:", result)
+
+except PayraSDKException as e:
+    print(f"Payra SDK error: {e}")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+#### Behind the Scenes
+
+1. The backend initializes a  `PayraOrderVerification`  object for the desired blockchain network.
+3. It calls  `get_order_status(order_id)`  to check if the order transaction exists and is confirmed on-chain.
+4. The function returns a dictionary with:
+    ```python
+    {
+	    "success": True,
+	    "paid": True,
+	    "error": None.
+	    "toke": '0xc2132d05d31c914a87c6611c10748aeb04b58e8f',
+	    "amount": 400000,
+	    "fee": 3600,
+	    "timestamp": 1765138941
+	}
+	```
+
+---
+
+### Check Order Paid Status
+
+Perform a **simple payment check** for a specific order. This method only verifies whether the order has been paid (`true`  or  `false`) and does **not** return any additional payment details.
 
-You can verify whether a Payra order has been successfully paid on-chain:
+Use this method when you only need a **quick boolean confirmation** of the payment status.
 
 ```python
 from payra_sdk import PayraOrderVerification, PayraSDKException
 
 try:
-    ORDER_ID = "ORDER-1753824905006-301-322"
+    ORDER_ID = "ORDER-1765138911744-126-5"
 
     # Initialize verifier for a specific network
     verifier = PayraOrderVerification("polygon")
@@ -251,9 +317,9 @@ except Exception as e:
 
 #### Behind the Scenes
 
-1.  The backend initializes a  `PayraOrderVerification`  object for the desired blockchain network.
-3.  It calls  `is_order_paid(order_id)`  to check if the order transaction exists and is confirmed on-chain.
-4.  The function returns a dictionary with:
+1. The backend initializes a  `PayraOrderVerification`  object for the desired blockchain network.
+3. It calls  `is_order_paid(order_id)`  to check if the order transaction exists and is confirmed on-chain.
+4. The function returns a dictionary with:
     ```python
     {
 	    "success": True,
@@ -261,7 +327,7 @@ except Exception as e:
 	    "error": None
 	}
 	```
-5.  If  `paid`  is  `True`, the order has been successfully processed and confirmed by the Payra smart contract.
+5. If  `paid`  is  `True`, the order has been successfully processed and confirmed by the Payra smart contract.
 
 ---
 
@@ -272,29 +338,29 @@ The `PayraUtils` module provides convenient helpers for token conversion, precis
 ```python
 from payra_sdk import PayraUtils
 
-# 🔹 Convert USD/token amount to smallest unit (Wei or token decimals)
+# Convert USD/token amount to smallest unit (Wei or token decimals)
 amount_wei = PayraUtils.to_wei(3.34, 'polygon', 'usdt')
 print("Amount in Wei:", amount_wei)  # 3340000
 
-# 🔹 Convert from Wei back to readable token amount
+# Convert from Wei back to readable token amount
 amount = PayraUtils.from_wei(3340000, 'polygon', 'usdt', precision=2)
 print("Readable amount:", amount)  # "3.34"
 
-# 🔹 Get token decimals for any supported network
+# Get token decimals for any supported network
 print("USDT decimals on Polygon:", PayraUtils.get_decimals("polygon", "usdt"))
 print("POL decimals on Polygon:", PayraUtils.get_decimals("polygon", "pol"))
 
-# 🔹 Convert fiat currency to USD using the built-in ExchangeRate API
+# Convert fiat currency to USD using the built-in ExchangeRate API
 usd_value = PayraUtils.convert_to_usd(100, "EUR")
 print(f"100 EUR = {usd_value} USD")
 ```
 
 #### Behind the Scenes
 
--   `to_wei(amount, network, token)`  – Converts a human-readable token amount into the smallest unit (used on-chain).
--   `from_wei(amount, network, token, precision)`  – Converts back from smallest unit to a formatted amount.
--   `get_decimals(network, token)`  – Returns the number of decimals for the given token on that network.
--   `convert_to_usd(amount, currency)`  – Converts fiat amounts (e.g. EUR, GBP) to USD using your ExchangeRate API key.
+- `to_wei(amount, network, token)`  – Converts a human-readable token amount into the smallest unit (used on-chain).
+- `from_wei(amount, network, token, precision)`  – Converts back from smallest unit to a formatted amount.
+- `get_decimals(network, token)`  – Returns the number of decimals for the given token on that network.
+- `convert_to_usd(amount, currency)`  – Converts fiat amounts (e.g. EUR, GBP) to USD using your ExchangeRate API key.
 
 ## Testing
 You can run the included `examples` to test signing and verification:
@@ -305,34 +371,34 @@ python3 example_order_verification.py
 python3 example_utils.py
 ```
 
-Make sure your (`.env`) file contains correct values for the `network` being used.
+Make sure your `.env` file contains correct values for the `network` being used.
 
 ### Tips
 
-- Always verify your  (`.env`)  configuration before running any signing or on-chain verification examples.
+- Always verify your `.env` configuration before running any signing or on-chain verification examples.
 - The SDK examples are safe to run — they use  **read-only RPC calls**  (no real transactions are broadcast).
 - You can modify  `example_signature.py`  to test custom token addresses or order parameters.
 
 ## Projects
 
--   [GitHub / Home](https://github.com/payracash)
--   [GitHub / Source](https://github.com/payracash/payra-sdk-python)
--   [GitHub / Issues](https://github.com/payracash/payra-sdk-python/issues)
+- [GitHub/Home](https://github.com/payracash)
+- [GitHub/Source](https://github.com/payracash/payra-sdk-python)
+- [GitHub/Issues](https://github.com/payracash/payra-sdk-python/issues)
 
 ## Project
 
--   [https://payra.cash](https://payra.cash)
--   [https://payra.tech](https://payra.tech)
--   [https://payra.xyz](https://payra.xyz)
--   [https://payra.eth](https://payra.eth)
+- [https://payra.cash](https://payra.cash)
+- [https://payra.tech](https://payra.tech)
+- [https://payra.xyz](https://payra.xyz)
+- [https://payra.eth](https://payra.eth.limo) - suporrted by Brave Browser or .limo
 
 ## Social Media
 
 - [Telegram Payra Group](https://t.me/+GhTyJJrd4SMyMDA0)
 - [Telegram Announcements](https://t.me/payracash)
 - [Twix (X)](https://x.com/PayraCash)
-- [Hashnode](https://payra.hashnode.dev)
+- [Dev.to](https://dev.to/payracash)
 
 ##  License
 
-MIT © [Payra](https://github.com/payracash)
+MIT © [Payra](https://payra.cash)

payra_sdk-1.2.5.dist-info/RECORD

@@ -0,0 +1,10 @@
+payra_sdk/__init__.py,sha256=VMmHadXy0RLCjEPZhW_hCc3hg34pkmrL4VhTjqmVBiI,422
+payra_sdk/exceptions.py,sha256=Dr8dy0RohAYII_-YeSu_doPJSr0EsJPcp6Oj02sio9Q,425
+payra_sdk/order_verification.py,sha256=wS43tz6yfGSoHGj_B_vr60d0Z2UhXwy4RxZRX3OfvKo,4556
+payra_sdk/signature.py,sha256=Vn85w4DAGzHK1y9h3hMETij_-Qa4aSNz0KwnzwCyFQw,8613
+payra_sdk/utils.py,sha256=gIQZX9N97Eneh5ScJ-YWY8_8wRqxBe0h5lDAVFYV8CE,4854
+payra_sdk-1.2.5.dist-info/licenses/LICENSE,sha256=mnnujAcvHr1ULEDD2l0ZT6lrpeTv_9bG3n8sngv7ew8,120
+payra_sdk-1.2.5.dist-info/METADATA,sha256=GljMlwKvvai4_jzlyTehLzBT6Qb7s3okV8NVZLC9nvY,14367
+payra_sdk-1.2.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+payra_sdk-1.2.5.dist-info/top_level.txt,sha256=oC4dhGzjcpDRRwyU9JjtLu56Uc5moaa76utQGYsPL-g,10
+payra_sdk-1.2.5.dist-info/RECORD,,

payra_sdk-1.2.3.dist-info/RECORD

@@ -1,10 +0,0 @@
-payra_sdk/__init__.py,sha256=VMmHadXy0RLCjEPZhW_hCc3hg34pkmrL4VhTjqmVBiI,422
-payra_sdk/exceptions.py,sha256=Dr8dy0RohAYII_-YeSu_doPJSr0EsJPcp6Oj02sio9Q,425
-payra_sdk/order_verification.py,sha256=IWKV4V6gZRyrtJtXsDRPflUcSsuN5D1kFZn5QVTPi5Q,3379
-payra_sdk/signature.py,sha256=Vn85w4DAGzHK1y9h3hMETij_-Qa4aSNz0KwnzwCyFQw,8613
-payra_sdk/utils.py,sha256=SSh_3AfPpceEoGL3tO7ydXJz17Kl3k7D-mM0wiv-h-c,4836
-payra_sdk-1.2.3.dist-info/licenses/LICENSE,sha256=mnnujAcvHr1ULEDD2l0ZT6lrpeTv_9bG3n8sngv7ew8,120
-payra_sdk-1.2.3.dist-info/METADATA,sha256=GY6VfwviC9LRXYiHb1IY1vpMvoqKcSvmbAvYeNgl-18,11696
-payra_sdk-1.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-payra_sdk-1.2.3.dist-info/top_level.txt,sha256=oC4dhGzjcpDRRwyU9JjtLu56Uc5moaa76utQGYsPL-g,10
-payra_sdk-1.2.3.dist-info/RECORD,,