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.
- sofizpay_python_sdk-1.1.0/CHANGELOG.md +64 -0
- sofizpay_python_sdk-1.1.0/LICENSE +21 -0
- sofizpay_python_sdk-1.1.0/MANIFEST.in +25 -0
- sofizpay_python_sdk-1.1.0/PKG-INFO +526 -0
- sofizpay_python_sdk-1.1.0/README.md +474 -0
- sofizpay_python_sdk-1.1.0/assets/sofizpay-logo.png +0 -0
- sofizpay_python_sdk-1.1.0/pyproject.toml +134 -0
- sofizpay_python_sdk-1.1.0/requirements-dev.txt +6 -0
- sofizpay_python_sdk-1.1.0/requirements.txt +6 -0
- sofizpay_python_sdk-1.1.0/setup.cfg +67 -0
- sofizpay_python_sdk-1.1.0/setup.py +46 -0
- sofizpay_python_sdk-1.1.0/sofizpay/__init__.py +67 -0
- sofizpay_python_sdk-1.1.0/sofizpay/client.py +737 -0
- sofizpay_python_sdk-1.1.0/sofizpay/exceptions.py +46 -0
- sofizpay_python_sdk-1.1.0/sofizpay/payments.py +202 -0
- sofizpay_python_sdk-1.1.0/sofizpay/transactions.py +389 -0
- sofizpay_python_sdk-1.1.0/sofizpay/utils.py +172 -0
- sofizpay_python_sdk-1.1.0/sofizpay_python_sdk.egg-info/PKG-INFO +526 -0
- sofizpay_python_sdk-1.1.0/sofizpay_python_sdk.egg-info/SOURCES.txt +23 -0
- sofizpay_python_sdk-1.1.0/sofizpay_python_sdk.egg-info/dependency_links.txt +1 -0
- sofizpay_python_sdk-1.1.0/sofizpay_python_sdk.egg-info/not-zip-safe +1 -0
- sofizpay_python_sdk-1.1.0/sofizpay_python_sdk.egg-info/requires.txt +16 -0
- sofizpay_python_sdk-1.1.0/sofizpay_python_sdk.egg-info/top_level.txt +1 -0
- sofizpay_python_sdk-1.1.0/tests/test_basic.py +10 -0
|
@@ -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
|
+
[](https://pypi.org/project/sofizpay-python-sdk/)
|
|
60
|
+
[](https://opensource.org/licenses/MIT)
|
|
61
|
+
[](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
|
+
|