sofizpay-python-sdk 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,64 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+
9
+
10
+
11
+
12
+ ## [1.0.2] - 2025-08-01
13
+ sd
14
+
15
+ ## [1.0.2] - 2025-08-01
16
+ sd
17
+
18
+ ## [1.0.2] - 2025-08-01
19
+ hello
20
+
21
+ ## [1.0.2] - 2025-08-01
22
+ hello
23
+
24
+ ## [1.0.1] - 2025-07-16
25
+
26
+ ### Added
27
+ - Initial release of SofizPay SDK for Python
28
+ - Payment operations using Stellar network
29
+ - DZT asset support with default issuer configuration
30
+ - Real-time transaction streaming and monitoring
31
+ - Balance checking for DZT and other assets
32
+ - Transaction history retrieval
33
+ - Transaction lookup by hash
34
+ - Comprehensive error handling and validation
35
+ - Async/await support for all operations
36
+ - Rate limiting for API calls
37
+ - Context manager support
38
+ - Extensive documentation and examples
39
+ - Full test suite with pytest
40
+
41
+ ### Features
42
+ - **Payment Management**: Send DZT payments with memo support
43
+ - **Transaction Monitoring**: Real-time transaction streaming
44
+ - **Balance Checking**: Get DZT balances and all account assets
45
+ - **Transaction History**: Retrieve transaction records with filtering
46
+ - **Error Handling**: Comprehensive exception hierarchy
47
+ - **Validation**: Input validation for all operations
48
+ - **Rate Limiting**: Built-in rate limiting for API stability
49
+ - **Examples**: Complete examples for all major operations
50
+
51
+ ### Technical Details
52
+ - Compatible with Python 3.8+
53
+ - Uses stellar-sdk 8.0+ for Stellar operations
54
+ - Async/await support throughout
55
+ - Comprehensive test coverage
56
+ - Type hints for better IDE support
57
+ - PEP 8 compliant code style
58
+
59
+ ### Documentation
60
+ - Complete API documentation
61
+ - Usage examples in Arabic and English
62
+ - Installation and setup instructions
63
+ - Error handling guidelines
64
+ - Development setup guide
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 SofizPay Team
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,25 @@
1
+ include README.md
2
+ include LICENSE
3
+ include CHANGELOG.md
4
+ include CONTRIBUTING.md
5
+ include requirements.txt
6
+ include requirements-dev.txt
7
+ include setup.cfg
8
+ recursive-include sofizpay *.py
9
+ recursive-include tests *.py
10
+ recursive-include examples *.py
11
+ exclude .gitignore
12
+ exclude .github/*
13
+ exclude .github/*/*
14
+ exclude *.pyc
15
+ exclude */__pycache__/*
16
+ exclude */.*
17
+ exclude .DS_Store
18
+ exclude Thumbs.db
19
+ exclude *~
20
+ exclude *.swp
21
+ exclude *.swo
22
+ global-exclude __pycache__
23
+ global-exclude *.py[co]
24
+ global-exclude *.so
25
+ global-exclude .DS_Store
@@ -0,0 +1,526 @@
1
+ Metadata-Version: 2.4
2
+ Name: sofizpay-python-sdk
3
+ Version: 1.1.0
4
+ Summary: Professional Python SDK for SofizPay payments using Stellar blockchain
5
+ Home-page: https://github.com/SofizPay/sofizpay-python-sdk
6
+ Author: SofizPay Team
7
+ Author-email: SofizPay Team <support@sofizpay.com>
8
+ Maintainer-email: SofizPay Team <support@sofizpay.com>
9
+ License: MIT
10
+ Project-URL: Homepage, https://sofizpay.com
11
+ Project-URL: Documentation, https://github.com/SofizPay/sofizpay-python-sdk#readme
12
+ Project-URL: Repository, https://github.com/SofizPay/sofizpay-python-sdk
13
+ Project-URL: Bug Reports, https://github.com/SofizPay/sofizpay-python-sdk/issues
14
+ Project-URL: Changelog, https://github.com/SofizPay/sofizpay-python-sdk/blob/main/CHANGELOG.md
15
+ Keywords: stellar,payment,blockchain,cryptocurrency,DZT,sofizpay,fintech
16
+ Classifier: Development Status :: 5 - Production/Stable
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: License :: OSI Approved :: MIT License
19
+ Classifier: Operating System :: OS Independent
20
+ Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3.8
22
+ Classifier: Programming Language :: Python :: 3.9
23
+ Classifier: Programming Language :: Python :: 3.10
24
+ Classifier: Programming Language :: Python :: 3.11
25
+ Classifier: Programming Language :: Python :: 3.12
26
+ Classifier: Topic :: Office/Business :: Financial
27
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
28
+ Classifier: Topic :: Internet :: WWW/HTTP
29
+ Classifier: Typing :: Typed
30
+ Requires-Python: >=3.8
31
+ Description-Content-Type: text/markdown
32
+ License-File: LICENSE
33
+ Requires-Dist: stellar-sdk>=8.0.0
34
+ Requires-Dist: requests>=2.25.0
35
+ Requires-Dist: asyncio-throttle>=1.0.0
36
+ Requires-Dist: websockets>=10.0
37
+ Requires-Dist: cryptography>=3.4.0
38
+ Requires-Dist: pycryptodome>=3.15.0
39
+ Provides-Extra: dev
40
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
41
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
42
+ Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
43
+ Requires-Dist: black>=23.0.0; extra == "dev"
44
+ Requires-Dist: flake8>=6.0.0; extra == "dev"
45
+ Requires-Dist: mypy>=1.0.0; extra == "dev"
46
+ Requires-Dist: isort>=5.12.0; extra == "dev"
47
+ Requires-Dist: coverage>=7.0.0; extra == "dev"
48
+ Dynamic: author
49
+ Dynamic: home-page
50
+ Dynamic: license-file
51
+ Dynamic: requires-python
52
+
53
+ <div align="center">
54
+ <img src="https://github.com/SofizPay/sofizpay-python-sdk/blob/main/assets/sofizpay-logo.png?raw=true" alt="SofizPay Logo" width="200" />
55
+
56
+ <h2>SofizPay Python SDK</h2>
57
+ <p><strong>The official Python SDK for secure digital payments on the SofizPay platform.</strong></p>
58
+
59
+ [![PyPI version](https://badge.fury.io/py/sofizpay-python-sdk.svg)](https://pypi.org/project/sofizpay-python-sdk/)
60
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
61
+ [![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](https://www.python.org/)
62
+ </div>
63
+
64
+ ---
65
+
66
+ ## 📋 Table of Contents
67
+
68
+ - [Overview](#overview)
69
+ - [Installation](#installation)
70
+ - [Quick Start](#quick-start)
71
+ - [Core Methods](#core-methods)
72
+ - [Digital Services (Missions)](#digital-services-missions)
73
+ - [Bank Integration (CIB)](#bank-integration-cib)
74
+ - [Real-time Transaction Streaming](#real-time-transaction-streaming)
75
+ - [Response Format](#response-format)
76
+ - [Security Best Practices](#security-best-practices)
77
+ - [Support](#support)
78
+
79
+ ---
80
+
81
+ ## 🌟 Overview
82
+
83
+ The SofizPay Python SDK provides a complete `async` interface for integrating **DZT digital payments** into Python applications, Django backends, and FastAPI services. It offers high-level abstractions for Stellar payments, transaction history, and digital service recharges.
84
+
85
+ **Key Benefits:**
86
+ - ⚡ **Fully Async:** Built on `aiohttp` for non-blocking I/O
87
+ - 🌍 **Framework Agnostic:** Works perfectly with Django, FastAPI, Flask, or CLI tools
88
+ - 📊 **Exhaustive History:** Captures Path Payments, Trustlines, and account events
89
+ - 🏦 **CIB/Dahabia:** Simple bank deposit link generation
90
+ - 📱 **Missions:** Phone, Internet, and Game top-ups via Mission APIs
91
+
92
+ ---
93
+
94
+ ## 📦 Installation
95
+
96
+ ### pip
97
+
98
+ ```bash
99
+ pip install sofizpay-python-sdk
100
+ ```
101
+
102
+ **Requirements:**
103
+ - Python `>= 3.8`
104
+ - Dependencies: `aiohttp`, `stellar-sdk`
105
+
106
+ ---
107
+
108
+ ## 🚀 Quick Start
109
+
110
+ ```python
111
+ import asyncio, os
112
+ from sofizpay.client import SofizPayClient
113
+
114
+ async def main():
115
+ # Initialize the async client
116
+ client = SofizPayClient()
117
+
118
+ # 1. Check DZT balance
119
+ balance = await client.get_balance('YOUR_PUBLIC_KEY')
120
+ if balance['success']:
121
+ print(f"💰 Balance: {balance['balance']} DZT")
122
+
123
+ # 2. Send a DZT payment
124
+ result = await client.send_payment(
125
+ source_secret='YOUR_SECRET_KEY', # 56-char Stellar seed starting with 'S'
126
+ destination_public_key='RECIPIENT_PUBLIC_KEY', # Recipient's public key
127
+ amount='100', # Amount as string
128
+ memo='Invoice #1234' # Optional memo (max 28 chars)
129
+ )
130
+
131
+ if result.get('success'):
132
+ print(f"✅ Payment sent! Hash: {result['transactionHash']}")
133
+ else:
134
+ print(f"❌ Error: {result.get('error')}")
135
+
136
+ if __name__ == "__main__":
137
+ # Run the async main function
138
+ asyncio.run(main())
139
+ ```
140
+
141
+ ---
142
+
143
+ ## 🔧 Core Methods
144
+
145
+ ### `get_balance(public_key)`
146
+
147
+ Returns the current **DZT** balance for a given Stellar account.
148
+
149
+ ```python
150
+ # Fetch balance for a specific public key
151
+ result = await client.get_balance('GCAZI...YOUR_PUBLIC_KEY')
152
+
153
+ # Response
154
+ {
155
+ 'success': True,
156
+ 'balance': '1500.0000000',
157
+ 'publicKey': 'GCAZI...',
158
+ 'asset_code': 'DZT',
159
+ 'asset_issuer': 'GCAZI7YBLIDJWIVEL7ETNAZGPP3LC24NO6KAOBWZHUERXQ7M5BC52DLV',
160
+ 'timestamp': '2025-07-28T10:30:00Z'
161
+ }
162
+ ```
163
+
164
+ ---
165
+
166
+ ### `send_payment(source_secret, destination_public_key, amount, memo?)`
167
+
168
+ Submits a DZT payment to the Stellar network.
169
+
170
+ ```python
171
+ result = await client.send_payment(
172
+ source_secret='SXXX...YOUR_SECRET', # 56-char Stellar seed starting with 'S'
173
+ destination_public_key='GXXX...RECIPIENT', # Recipient's public key
174
+ amount='250.50', # Amount in DZT
175
+ memo='Order #5567' # Optional memo (max 28 chars)
176
+ )
177
+
178
+ # Success Response
179
+ {
180
+ 'success': True,
181
+ 'transactionId': 'abc123...hash',
182
+ 'transactionHash': 'abc123...hash',
183
+ 'amount': '250.50',
184
+ 'memo': 'Order #5567',
185
+ 'destinationPublicKey': 'GXXX...',
186
+ 'timestamp': '2025-07-28T10:30:00Z'
187
+ }
188
+ ```
189
+
190
+ > ⚠️ **Memo Truncation:** Memos longer than 28 characters are automatically truncated.
191
+
192
+ ---
193
+
194
+ ### `get_transactions(public_key, limit?)`
195
+
196
+ Fetches **exhaustive transaction history** via Stellar. Includes payments, trustlines, and account creation.
197
+
198
+ ```python
199
+ # Fetch up to 100 recent transactions
200
+ transactions = await client.get_transactions('YOUR_PUBLIC_KEY', 100)
201
+
202
+ for tx in transactions:
203
+ # Print details for each captured operation
204
+ print(f"[{tx['created_at']}] {tx['type']} — {tx['amount']} DZT")
205
+ ```
206
+
207
+ ---
208
+
209
+ ### `search_transactions_by_memo(public_key, memo, limit?)`
210
+
211
+ Performs a case-insensitive search over recent transactions.
212
+
213
+ ```python
214
+ # Perform case-insensitive search over user's recent transactions
215
+ results = await client.search_transactions_by_memo('YOUR_PUBLIC_KEY', 'Order #1234', 10)
216
+ if results['success']:
217
+ print(f"Found {results['totalFound']} matches")
218
+ ```
219
+
220
+ ---
221
+
222
+ ## 📱 Digital Services (Missions)
223
+
224
+ Mission APIs allow users to spend DZT on real-world digital services. All calls require `encrypted_sk`.
225
+
226
+ ### Phone Recharge
227
+
228
+ ```python
229
+ result = await client.recharge_phone({
230
+ 'encrypted_sk': 'USER_ENCRYPTED_SECRET_KEY', # User's encrypted secret key
231
+ 'phone': '0661000000', # Recipient's phone number
232
+ 'operator': 'mobilis', # 'mobilis' | 'djezzy' | 'ooredoo'
233
+ 'amount': '100', # Recharge amount
234
+ 'offer': 'Top' # Offer type (e.g., 'Top', 'Pix')
235
+ })
236
+
237
+ if result['success']:
238
+ # Process successful recharge response
239
+ print('✅ Phone recharged:', result['data'])
240
+ ```
241
+
242
+ ### Internet Recharge (Idoom 4G)
243
+
244
+ ```python
245
+ result = await client.recharge_internet({
246
+ 'encrypted_sk': 'USER_ENCRYPTED_SECRET_KEY', # User's encrypted secret key
247
+ 'phone': '0661000000', # Account phone number
248
+ 'operator': 'algerie-telecom', # Network provider
249
+ 'amount': '2000', # Recharge amount
250
+ 'offer': 'prepaid' # Offer type (e.g., 'prepaid', 'postpaid')
251
+ })
252
+ ```
253
+
254
+ ### Game Top-up (FreeFire, PUBG)
255
+
256
+ ```python
257
+ result = await client.recharge_game({
258
+ 'encrypted_sk': 'USER_ENCRYPTED_SECRET_KEY',
259
+ 'operator': 'freefire', # e.g., 'freefire', 'pubg'
260
+ 'playerId': '123456789',
261
+ 'amount': '500', # 'amount' from getProducts()
262
+ 'offer': 'diamonds' # 'name' from getProducts()
263
+ })
264
+ ```
265
+
266
+ ### Bill Payment
267
+
268
+ ```python
269
+ result = await client.pay_bill({
270
+ 'encrypted_sk': 'USER_ENCRYPTED_SECRET_KEY',
271
+ 'operator': 'sonelgaz', # e.g., 'sonelgaz', 'ade'
272
+ 'bill_id': 'BILL_999',
273
+ 'amount': '1500'
274
+ })
275
+ ```
276
+
277
+ ### Get Available Products
278
+
279
+ Fetches the list of available services, operators, and their associated offers (products).
280
+
281
+ ```python
282
+ products = await client.get_products()
283
+ if products['success']:
284
+ # Use products['data'] to populate Missions 'offer' and 'amount'
285
+ print('Available services:', products['data'])
286
+ ```
287
+
288
+ > [!TIP]
289
+ > Each product in the `data` array usually contains `name` and `amount`. When calling recharge methods, use the product's `name` for the `offer` field and the product's `amount` for the `amount` field.
290
+
291
+ ### Operation History & Details
292
+
293
+ ```python
294
+ # Recent operations (paginated)
295
+ history = await client.get_operation_history('USER_ENCRYPTED_SK', limit=10, offset=0)
296
+ if history['success']:
297
+ print('Last 10 operations:', history['data'])
298
+
299
+ # Details of a specific operation
300
+ details = await client.get_operation_details('OPERATION_ID', 'USER_ENCRYPTED_SK')
301
+ ```
302
+
303
+ ### Get Available Products
304
+
305
+ ```python
306
+ # Fetch available charging services and products
307
+ products = await client.get_products()
308
+ if products.get('success'):
309
+ # Iterate through available products to find names and amounts
310
+ print('Available services:', products['data'])
311
+ ```
312
+
313
+ > [!TIP]
314
+ > Use the product `name` for the `offer` field and the product `amount` for the `amount` field.
315
+
316
+ ---
317
+
318
+ ## 🏦 Bank Integration (CIB & EDAHABIA)
319
+
320
+ Generate secure Dahabia/CIB bank payment links with optional real-time webhook callbacks.
321
+
322
+ ```python
323
+ result = await client.make_cib_transaction({
324
+ 'account': 'YOUR_STELLAR_PUBLIC_KEY', # Your merchant Stellar public key
325
+ 'amount': 2500, # Amount in DZD (Algerian Dinars)
326
+ 'full_name': 'Ahmed Benali', # Customer's full name
327
+ 'phone': '0661234567', # Customer's phone number
328
+ 'email': 'ahmed@example.com', # Customer's email
329
+ 'memo': 'Order #789', # Internal order reference
330
+ 'return_url': 'https://yoursite.com/callback', # Redirect after payment
331
+ 'webhook_url': 'https://yoursite.com/api/cib-webhook', # Asynchronous Webhook callback
332
+ 'language': 'ar', # 'ar', 'fr', or 'en'
333
+ 'redirect': 'no' # 'yes' for auto-redirect
334
+ })
335
+
336
+ if result.get('success'):
337
+ # Top-level direct properties
338
+ payment_url = result['payment_url']
339
+ order_id = result['cib_transaction_id']
340
+ print(f"Redirect customer to: {payment_url}")
341
+ ```
342
+
343
+ ---
344
+
345
+ ## 🧪 Sandbox Environment & Mock Cards
346
+
347
+ The SofizPay Sandbox simulates the SATIM CIB/EDAHABIA payment system without connecting to real bank accounts.
348
+
349
+ ```python
350
+ # Initialize client in Sandbox mode (or pass 'is_sandbox': True)
351
+ sandbox_client = SofizPayClient(sandbox=True)
352
+
353
+ result = await sandbox_client.make_sandbox_cib_transaction({
354
+ 'account': 'YOUR_PUBLIC_KEY',
355
+ 'amount': 150.0,
356
+ 'full_name': 'Sandbox Tester',
357
+ 'phone': '0555000000',
358
+ 'email': 'sandbox@example.com',
359
+ 'webhook_url': 'https://yoursite.com/api/cib-webhook',
360
+ 'return_url': 'https://yoursite.com/callback'
361
+ })
362
+
363
+ if result.get('success'):
364
+ print(f"Sandbox Payment URL: {result['payment_url']}")
365
+ cib_id = result['cib_transaction_id']
366
+
367
+ # Check sandbox order status
368
+ status = await sandbox_client.check_sandbox_cib_status(cib_id)
369
+ print("Order Status:", status.get('data'))
370
+ ```
371
+
372
+ ### Sandbox Test Cards
373
+
374
+ Use the following test credentials on the sandbox payment page:
375
+
376
+ | Card Number | Expiry | CVV | Cardholder Name | Result | Note |
377
+ |-------------|--------|-----|-----------------|--------|------|
378
+ | `6280581001234567` | `12/28` | `123` | `TEST SUCCESS` | ✅ Approved | Use OTP `123456` |
379
+ | `6280581009876543` | `12/29` | `456` | `TEST SUCCESS TWO` | ✅ Approved | Use OTP `123456` |
380
+ | `6280581005555555` | `06/28` | `999` | `TEST DECLINED` | ❌ Declined by issuer | Tests card refusal |
381
+ | `6280581004444444` | `09/28` | `444` | `TEST INSUFFICIENT` | ❌ Insufficient funds | Tests insufficient balance |
382
+ | `6280581003333333` | `03/21` | `333` | `TEST EXPIRED` | ❌ Expired card | Tests expired card |
383
+ | `6280581002222222` | `11/28` | `222` | `TEST TIMEOUT` | ❌ Timeout | Tests transaction timeout |
384
+
385
+ > [!TIP]
386
+ > **OTP Code:** Always enter `123456` on the OTP page for approved tests. Entering any other OTP triggers an `Invalid OTP` error.
387
+
388
+ ---
389
+
390
+ ## 🔔 Webhooks & Signature Verification
391
+
392
+ When a payment succeeds or fails, SofizPay delivers a server-to-server asynchronous HTTP `POST` event notification (`cib.payment.updated`) to your registered `webhook_url`.
393
+
394
+ ### Webhook Event Payload
395
+
396
+ ```json
397
+ {
398
+ "event": "cib.payment.updated",
399
+ "payment_status": "success",
400
+ "transaction_id": "bb979126-4e55-49dd-8ecc-a1d59867d2b0",
401
+ "cib_transaction_id": "5965287001",
402
+ "order_number": 5965287001,
403
+ "order_status": 2,
404
+ "amount": 150000,
405
+ "currency": "012",
406
+ "resp_code": "00",
407
+ "resp_code_desc": "Approved",
408
+ "message": "https://yoursite.com/api/cib-webhook/success1500005965287001",
409
+ "signature": "MEQCIFz8v982hfkjdsf983274hfkjsdf...=="
410
+ }
411
+ ```
412
+
413
+ ### Verifying Signatures (`verify_webhook_signature`)
414
+
415
+ Always verify the RSA SHA-256 signature before processing payments in your database:
416
+
417
+ ```python
418
+ from fastapi import FastAPI, Request, HTTPException
419
+ from sofizpay.client import SofizPayClient
420
+
421
+ app = FastAPI()
422
+ client = SofizPayClient()
423
+
424
+ @app.post("/api/cib-webhook")
425
+ async def handle_cib_webhook(request: Request):
426
+ payload = await request.json()
427
+
428
+ # 1. Validate official digital signature
429
+ if not client.verify_webhook_signature(payload):
430
+ raise HTTPException(status_code=400, detail="Invalid digital signature")
431
+
432
+ # 2. Process order upon confirmation
433
+ if payload.get("payment_status") == "success":
434
+ order_number = payload.get("order_number") or payload.get("cib_transaction_id")
435
+ amount_in_dzd = (payload.get("amount") or 0) / 100
436
+
437
+ # ✅ Mark order as PAID in your database:
438
+ # await db.orders.update({"order_id": order_number}, {"status": "PAID", "amount": amount_in_dzd})
439
+ print(f"Payment approved for order {order_number} ({amount_in_dzd} DZD)")
440
+
441
+ return {"status": "OK"}
442
+ ```
443
+
444
+ ---
445
+
446
+ ## 🔄 Return URL vs. Webhook Notifications
447
+
448
+ | Feature | Return URL (`return_url`) | Webhook (`webhook_url`) |
449
+ | :--- | :--- | :--- |
450
+ | **Trigger mechanism** | Client browser redirect | Server-to-server direct HTTP POST |
451
+ | **Reliability** | Can fail if user closes browser / network drops | Guaranteed server delivery |
452
+ | **Security** | Susceptible to tampering | Cryptographically signed (RSA-2048) |
453
+ | **Recommended use** | Display "Thank you" screen | Update database, activate subscriptions |
454
+
455
+ ---
456
+
457
+ ## 🔴 Real-time Transaction Streaming
458
+
459
+ The Python SDK uses polling to monitor accounts for new transactions.
460
+
461
+ ### `setup_transaction_stream(public_key, callback, from_now?, check_interval?)`
462
+
463
+ | Parameter | Type | Default | Description |
464
+ |-----------|------|---------|-------------|
465
+ | `public_key` | `str` | required | Stellar account to monitor |
466
+ | `callback` | `async function` | required | Called for each new transaction |
467
+ | `from_now` | `bool` | `True` | `True`: new txs only; `False`: load history first |
468
+ | `check_interval` | `int` | `30` | Polling interval in seconds |
469
+
470
+ ```python
471
+ async def on_tx(tx):
472
+ print(f"New {tx['type']}: {tx['amount']} DZT — memo: {tx['memo']}")
473
+
474
+ stream_id = await client.setup_transaction_stream(
475
+ 'YOUR_PUBLIC_KEY', on_tx, from_now=True, check_interval=15
476
+ )
477
+ ```
478
+
479
+ ---
480
+
481
+ ## 📤 Response Format
482
+
483
+ All async methods return a dictionary with a `success` flag:
484
+
485
+ ```python
486
+ # ✅ Success
487
+ {
488
+ 'success': True,
489
+ 'data': {...}, # method-specific
490
+ 'timestamp': '2025-07-28T10:30:00Z'
491
+ }
492
+
493
+ # ❌ Failure
494
+ {
495
+ 'success': False,
496
+ 'error': 'Error message',
497
+ 'timestamp': '2025-07-28T10:30:00Z'
498
+ }
499
+ ```
500
+
501
+ ---
502
+
503
+ ## 🛡️ Security Best Practices
504
+
505
+ - ❌ Never expose secret keys in public repositories or client-side code.
506
+ - ✅ Use environment variables (`os.getenv('SOFIZPAY_SECRET')`).
507
+ - ✅ Keep `encrypted_sk` secure in your backend database.
508
+ - ✅ Use `encrypted_sk` for all Mission API calls (never the raw secret).
509
+ - ✅ Run payment logic on backend only.
510
+
511
+ ---
512
+
513
+ ## 📞 Support
514
+
515
+ - 🌐 **Website**: [SofizPay.com](https://sofizpay.com)
516
+ - 📚 **Full Docs**: [docs.sofizpay.com](https://docs.sofizpay.com)
517
+ - 🐛 **Bug Reports**: [GitHub Issues](https://github.com/kenandarabeh/sofizpay-python-sdk/issues)
518
+
519
+ ---
520
+
521
+ ## License
522
+
523
+ MIT © [SofizPay Team](https://github.com/kenandarabeh)
524
+
525
+ **Built with ❤️ for Python developers | Version `1.1.0`**
526
+