sunbay-nexus-sdk 1.0.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.
- sunbay_nexus_sdk-1.0.0/PKG-INFO +207 -0
- sunbay_nexus_sdk-1.0.0/README.md +184 -0
- sunbay_nexus_sdk-1.0.0/pyproject.toml +36 -0
- sunbay_nexus_sdk-1.0.0/setup.cfg +4 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/__init__.py +27 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/client.py +159 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/constant/__init__.py +9 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/constant/api_constants.py +55 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/enums/__init__.py +60 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/exception/__init__.py +44 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/http/__init__.py +362 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/model/base.py +27 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/model/common.py +103 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/model/request.py +198 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/model/response.py +157 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/util/__init__.py +5 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk/util/id_generator.py +20 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk.egg-info/PKG-INFO +207 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk.egg-info/SOURCES.txt +21 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk.egg-info/dependency_links.txt +1 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk.egg-info/requires.txt +1 -0
- sunbay_nexus_sdk-1.0.0/src/sunbay_nexus_sdk.egg-info/top_level.txt +1 -0
- sunbay_nexus_sdk-1.0.0/tests/test_nexus_client_integration.py +133 -0
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sunbay-nexus-sdk
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Official Sunbay Nexus Python SDK
|
|
5
|
+
Author-email: Sunbay <support@sunbay.example>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://open.sunbay.us
|
|
8
|
+
Project-URL: Source, https://example.com/sunbay-nexus-sdk-python
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.7
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
18
|
+
Classifier: Intended Audience :: Developers
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
20
|
+
Requires-Python: >=3.7
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
Requires-Dist: requests<3.0,>=2.28
|
|
23
|
+
|
|
24
|
+
## Sunbay Nexus Python SDK
|
|
25
|
+
|
|
26
|
+
Official Python SDK for the Sunbay Nexus payment platform.
|
|
27
|
+
|
|
28
|
+
This SDK provides a simple and professional way to integrate with Sunbay Nexus
|
|
29
|
+
from Python applications, following the same semantics as the official Java SDK.
|
|
30
|
+
|
|
31
|
+
### Features
|
|
32
|
+
|
|
33
|
+
- **Simple and intuitive API**
|
|
34
|
+
- **Thread-safe client with connection pooling**
|
|
35
|
+
- **Clear separation between network errors and business errors**
|
|
36
|
+
- **Automatic authentication via API key**
|
|
37
|
+
- **Configurable timeouts and retries for GET requests**
|
|
38
|
+
- **Python 3.7+ support**
|
|
39
|
+
|
|
40
|
+
### Installation
|
|
41
|
+
|
|
42
|
+
Once published to PyPI:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pip install sunbay-nexus-sdk
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Supported Python versions
|
|
49
|
+
|
|
50
|
+
- Officially supported: **Python 3.7 and above**
|
|
51
|
+
- Python 2 is **not supported**.
|
|
52
|
+
|
|
53
|
+
### Quick Start
|
|
54
|
+
|
|
55
|
+
#### 1. Initialize client
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
from sunbay_nexus_sdk import NexusClient
|
|
59
|
+
|
|
60
|
+
# Option 1: pass api_key explicitly
|
|
61
|
+
client = NexusClient(api_key="sk_test_xxx")
|
|
62
|
+
|
|
63
|
+
# Option 2: read api_key from environment variable SUNBAY_API_KEY
|
|
64
|
+
# client = NexusClient()
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The `NexusClient` is thread-safe and can be reused across multiple threads.
|
|
68
|
+
Create it once and reuse it in your application.
|
|
69
|
+
|
|
70
|
+
#### 2. Sale transaction
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
from sunbay_nexus_sdk import NexusClient, SunbayBusinessError, SunbayNetworkError
|
|
74
|
+
from sunbay_nexus_sdk.model.common import SaleAmount
|
|
75
|
+
from sunbay_nexus_sdk.model.request import SaleRequest
|
|
76
|
+
|
|
77
|
+
client = NexusClient(api_key="sk_test_xxx")
|
|
78
|
+
|
|
79
|
+
amount = SaleAmount(order_amount=100.0, pricing_currency="USD")
|
|
80
|
+
|
|
81
|
+
request = SaleRequest(
|
|
82
|
+
app_id="app_123456",
|
|
83
|
+
merchant_id="mch_789012",
|
|
84
|
+
reference_order_id="ORDER20231119001",
|
|
85
|
+
transaction_request_id="PAY_REQ_1234567890",
|
|
86
|
+
amount=amount,
|
|
87
|
+
description="Product purchase",
|
|
88
|
+
terminal_sn="T1234567890",
|
|
89
|
+
)
|
|
90
|
+
|
|
91
|
+
try:
|
|
92
|
+
response = client.sale(request)
|
|
93
|
+
if response.is_success():
|
|
94
|
+
print("Transaction ID:", response.transaction_id)
|
|
95
|
+
else:
|
|
96
|
+
print("Error:", response.code, response.msg)
|
|
97
|
+
except SunbayNetworkError as e:
|
|
98
|
+
print("Network Error:", e)
|
|
99
|
+
except SunbayBusinessError as e:
|
|
100
|
+
print("API Error:", e.code, "-", e)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
#### 3. Query transaction
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
from sunbay_nexus_sdk import NexusClient
|
|
107
|
+
from sunbay_nexus_sdk.model.request import QueryRequest
|
|
108
|
+
|
|
109
|
+
client = NexusClient(api_key="sk_test_xxx")
|
|
110
|
+
|
|
111
|
+
request = QueryRequest(
|
|
112
|
+
app_id="app_123456",
|
|
113
|
+
merchant_id="mch_789012",
|
|
114
|
+
transaction_id="TXN20231119001",
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
response = client.query(request)
|
|
118
|
+
|
|
119
|
+
if response.is_success():
|
|
120
|
+
print("Status:", response.transaction_status)
|
|
121
|
+
else:
|
|
122
|
+
print("Error:", response.code, response.msg)
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### API Overview
|
|
126
|
+
|
|
127
|
+
The Python SDK exposes a `NexusClient` with methods that correspond to the Java SDK:
|
|
128
|
+
|
|
129
|
+
- Transaction APIs:
|
|
130
|
+
- `sale(request: SaleRequest) -> SaleResponse`
|
|
131
|
+
- `auth(request: AuthRequest) -> AuthResponse`
|
|
132
|
+
- `forced_auth(request: ForcedAuthRequest) -> ForcedAuthResponse`
|
|
133
|
+
- `incremental_auth(request: IncrementalAuthRequest) -> IncrementalAuthResponse`
|
|
134
|
+
- `post_auth(request: PostAuthRequest) -> PostAuthResponse`
|
|
135
|
+
- `refund(request: RefundRequest) -> RefundResponse`
|
|
136
|
+
- `void_transaction(request: VoidRequest) -> VoidResponse`
|
|
137
|
+
- `abort(request: AbortRequest) -> AbortResponse`
|
|
138
|
+
- `tip_adjust(request: TipAdjustRequest) -> TipAdjustResponse`
|
|
139
|
+
- Query APIs:
|
|
140
|
+
- `query(request: QueryRequest) -> QueryResponse`
|
|
141
|
+
- Settlement APIs:
|
|
142
|
+
- `batch_close(request: BatchCloseRequest) -> BatchCloseResponse`
|
|
143
|
+
|
|
144
|
+
### Exceptions
|
|
145
|
+
|
|
146
|
+
The SDK differentiates between network-level and business-level errors:
|
|
147
|
+
|
|
148
|
+
- `SunbayNetworkError`
|
|
149
|
+
- Thrown for network errors, timeouts, or HTTP non-2xx responses.
|
|
150
|
+
- Has a `retryable` flag to indicate whether the request may be retried safely.
|
|
151
|
+
- `SunbayBusinessError`
|
|
152
|
+
- Thrown for API business errors (e.g. `code != "0"`) and local parameter validation failures.
|
|
153
|
+
- Contains `code` and `trace_id` fields when available.
|
|
154
|
+
|
|
155
|
+
Always catch `SunbayNetworkError` before `SunbayBusinessError` if you need to
|
|
156
|
+
distinguish between them.
|
|
157
|
+
|
|
158
|
+
### Configuration
|
|
159
|
+
|
|
160
|
+
You can configure the client using constructor arguments:
|
|
161
|
+
|
|
162
|
+
```python
|
|
163
|
+
from sunbay_nexus_sdk import NexusClient
|
|
164
|
+
|
|
165
|
+
client = NexusClient(
|
|
166
|
+
api_key="sk_test_xxx",
|
|
167
|
+
base_url="https://open.sunbay.us", # default
|
|
168
|
+
connect_timeout=30.0, # seconds, default 30.0
|
|
169
|
+
read_timeout=60.0, # seconds, default 60.0
|
|
170
|
+
max_retries=3, # default 3 for GET requests
|
|
171
|
+
max_connections=200, # default 200
|
|
172
|
+
)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Using enums
|
|
176
|
+
|
|
177
|
+
For some fields (such as transaction status and card network type), the SDK
|
|
178
|
+
provides enums to make the code more self-documenting:
|
|
179
|
+
|
|
180
|
+
```python
|
|
181
|
+
from sunbay_nexus_sdk import TransactionStatus
|
|
182
|
+
|
|
183
|
+
if response.is_success() and response.transaction_status == TransactionStatus.SUCCESS:
|
|
184
|
+
print("Transaction succeeded")
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Integration in web frameworks
|
|
188
|
+
|
|
189
|
+
In web frameworks (such as FastAPI or Django), it is recommended to create a
|
|
190
|
+
single `NexusClient` instance at startup and reuse it:
|
|
191
|
+
|
|
192
|
+
```python
|
|
193
|
+
from sunbay_nexus_sdk import NexusClient
|
|
194
|
+
|
|
195
|
+
client = NexusClient(api_key="sk_live_xxx")
|
|
196
|
+
|
|
197
|
+
def process_payment(request_data):
|
|
198
|
+
# build SaleRequest here...
|
|
199
|
+
response = client.sale(request_data)
|
|
200
|
+
...
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### License
|
|
204
|
+
|
|
205
|
+
MIT License
|
|
206
|
+
|
|
207
|
+
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
## Sunbay Nexus Python SDK
|
|
2
|
+
|
|
3
|
+
Official Python SDK for the Sunbay Nexus payment platform.
|
|
4
|
+
|
|
5
|
+
This SDK provides a simple and professional way to integrate with Sunbay Nexus
|
|
6
|
+
from Python applications, following the same semantics as the official Java SDK.
|
|
7
|
+
|
|
8
|
+
### Features
|
|
9
|
+
|
|
10
|
+
- **Simple and intuitive API**
|
|
11
|
+
- **Thread-safe client with connection pooling**
|
|
12
|
+
- **Clear separation between network errors and business errors**
|
|
13
|
+
- **Automatic authentication via API key**
|
|
14
|
+
- **Configurable timeouts and retries for GET requests**
|
|
15
|
+
- **Python 3.7+ support**
|
|
16
|
+
|
|
17
|
+
### Installation
|
|
18
|
+
|
|
19
|
+
Once published to PyPI:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pip install sunbay-nexus-sdk
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### Supported Python versions
|
|
26
|
+
|
|
27
|
+
- Officially supported: **Python 3.7 and above**
|
|
28
|
+
- Python 2 is **not supported**.
|
|
29
|
+
|
|
30
|
+
### Quick Start
|
|
31
|
+
|
|
32
|
+
#### 1. Initialize client
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
from sunbay_nexus_sdk import NexusClient
|
|
36
|
+
|
|
37
|
+
# Option 1: pass api_key explicitly
|
|
38
|
+
client = NexusClient(api_key="sk_test_xxx")
|
|
39
|
+
|
|
40
|
+
# Option 2: read api_key from environment variable SUNBAY_API_KEY
|
|
41
|
+
# client = NexusClient()
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The `NexusClient` is thread-safe and can be reused across multiple threads.
|
|
45
|
+
Create it once and reuse it in your application.
|
|
46
|
+
|
|
47
|
+
#### 2. Sale transaction
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
from sunbay_nexus_sdk import NexusClient, SunbayBusinessError, SunbayNetworkError
|
|
51
|
+
from sunbay_nexus_sdk.model.common import SaleAmount
|
|
52
|
+
from sunbay_nexus_sdk.model.request import SaleRequest
|
|
53
|
+
|
|
54
|
+
client = NexusClient(api_key="sk_test_xxx")
|
|
55
|
+
|
|
56
|
+
amount = SaleAmount(order_amount=100.0, pricing_currency="USD")
|
|
57
|
+
|
|
58
|
+
request = SaleRequest(
|
|
59
|
+
app_id="app_123456",
|
|
60
|
+
merchant_id="mch_789012",
|
|
61
|
+
reference_order_id="ORDER20231119001",
|
|
62
|
+
transaction_request_id="PAY_REQ_1234567890",
|
|
63
|
+
amount=amount,
|
|
64
|
+
description="Product purchase",
|
|
65
|
+
terminal_sn="T1234567890",
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
try:
|
|
69
|
+
response = client.sale(request)
|
|
70
|
+
if response.is_success():
|
|
71
|
+
print("Transaction ID:", response.transaction_id)
|
|
72
|
+
else:
|
|
73
|
+
print("Error:", response.code, response.msg)
|
|
74
|
+
except SunbayNetworkError as e:
|
|
75
|
+
print("Network Error:", e)
|
|
76
|
+
except SunbayBusinessError as e:
|
|
77
|
+
print("API Error:", e.code, "-", e)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
#### 3. Query transaction
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from sunbay_nexus_sdk import NexusClient
|
|
84
|
+
from sunbay_nexus_sdk.model.request import QueryRequest
|
|
85
|
+
|
|
86
|
+
client = NexusClient(api_key="sk_test_xxx")
|
|
87
|
+
|
|
88
|
+
request = QueryRequest(
|
|
89
|
+
app_id="app_123456",
|
|
90
|
+
merchant_id="mch_789012",
|
|
91
|
+
transaction_id="TXN20231119001",
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
response = client.query(request)
|
|
95
|
+
|
|
96
|
+
if response.is_success():
|
|
97
|
+
print("Status:", response.transaction_status)
|
|
98
|
+
else:
|
|
99
|
+
print("Error:", response.code, response.msg)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### API Overview
|
|
103
|
+
|
|
104
|
+
The Python SDK exposes a `NexusClient` with methods that correspond to the Java SDK:
|
|
105
|
+
|
|
106
|
+
- Transaction APIs:
|
|
107
|
+
- `sale(request: SaleRequest) -> SaleResponse`
|
|
108
|
+
- `auth(request: AuthRequest) -> AuthResponse`
|
|
109
|
+
- `forced_auth(request: ForcedAuthRequest) -> ForcedAuthResponse`
|
|
110
|
+
- `incremental_auth(request: IncrementalAuthRequest) -> IncrementalAuthResponse`
|
|
111
|
+
- `post_auth(request: PostAuthRequest) -> PostAuthResponse`
|
|
112
|
+
- `refund(request: RefundRequest) -> RefundResponse`
|
|
113
|
+
- `void_transaction(request: VoidRequest) -> VoidResponse`
|
|
114
|
+
- `abort(request: AbortRequest) -> AbortResponse`
|
|
115
|
+
- `tip_adjust(request: TipAdjustRequest) -> TipAdjustResponse`
|
|
116
|
+
- Query APIs:
|
|
117
|
+
- `query(request: QueryRequest) -> QueryResponse`
|
|
118
|
+
- Settlement APIs:
|
|
119
|
+
- `batch_close(request: BatchCloseRequest) -> BatchCloseResponse`
|
|
120
|
+
|
|
121
|
+
### Exceptions
|
|
122
|
+
|
|
123
|
+
The SDK differentiates between network-level and business-level errors:
|
|
124
|
+
|
|
125
|
+
- `SunbayNetworkError`
|
|
126
|
+
- Thrown for network errors, timeouts, or HTTP non-2xx responses.
|
|
127
|
+
- Has a `retryable` flag to indicate whether the request may be retried safely.
|
|
128
|
+
- `SunbayBusinessError`
|
|
129
|
+
- Thrown for API business errors (e.g. `code != "0"`) and local parameter validation failures.
|
|
130
|
+
- Contains `code` and `trace_id` fields when available.
|
|
131
|
+
|
|
132
|
+
Always catch `SunbayNetworkError` before `SunbayBusinessError` if you need to
|
|
133
|
+
distinguish between them.
|
|
134
|
+
|
|
135
|
+
### Configuration
|
|
136
|
+
|
|
137
|
+
You can configure the client using constructor arguments:
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
from sunbay_nexus_sdk import NexusClient
|
|
141
|
+
|
|
142
|
+
client = NexusClient(
|
|
143
|
+
api_key="sk_test_xxx",
|
|
144
|
+
base_url="https://open.sunbay.us", # default
|
|
145
|
+
connect_timeout=30.0, # seconds, default 30.0
|
|
146
|
+
read_timeout=60.0, # seconds, default 60.0
|
|
147
|
+
max_retries=3, # default 3 for GET requests
|
|
148
|
+
max_connections=200, # default 200
|
|
149
|
+
)
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### Using enums
|
|
153
|
+
|
|
154
|
+
For some fields (such as transaction status and card network type), the SDK
|
|
155
|
+
provides enums to make the code more self-documenting:
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
from sunbay_nexus_sdk import TransactionStatus
|
|
159
|
+
|
|
160
|
+
if response.is_success() and response.transaction_status == TransactionStatus.SUCCESS:
|
|
161
|
+
print("Transaction succeeded")
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Integration in web frameworks
|
|
165
|
+
|
|
166
|
+
In web frameworks (such as FastAPI or Django), it is recommended to create a
|
|
167
|
+
single `NexusClient` instance at startup and reuse it:
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
from sunbay_nexus_sdk import NexusClient
|
|
171
|
+
|
|
172
|
+
client = NexusClient(api_key="sk_live_xxx")
|
|
173
|
+
|
|
174
|
+
def process_payment(request_data):
|
|
175
|
+
# build SaleRequest here...
|
|
176
|
+
response = client.sale(request_data)
|
|
177
|
+
...
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### License
|
|
181
|
+
|
|
182
|
+
MIT License
|
|
183
|
+
|
|
184
|
+
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "sunbay-nexus-sdk"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Official Sunbay Nexus Python SDK"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.7"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "Sunbay", email = "support@sunbay.example" }
|
|
14
|
+
]
|
|
15
|
+
dependencies = [
|
|
16
|
+
"requests>=2.28,<3.0",
|
|
17
|
+
]
|
|
18
|
+
classifiers = [
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
21
|
+
"Programming Language :: Python :: 3.7",
|
|
22
|
+
"Programming Language :: Python :: 3.8",
|
|
23
|
+
"Programming Language :: Python :: 3.9",
|
|
24
|
+
"Programming Language :: Python :: 3.10",
|
|
25
|
+
"Programming Language :: Python :: 3.11",
|
|
26
|
+
"Programming Language :: Python :: 3.12",
|
|
27
|
+
"License :: OSI Approved :: MIT License",
|
|
28
|
+
"Intended Audience :: Developers",
|
|
29
|
+
"Topic :: Software Development :: Libraries",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.urls]
|
|
33
|
+
Homepage = "https://open.sunbay.us"
|
|
34
|
+
Source = "https://example.com/sunbay-nexus-sdk-python"
|
|
35
|
+
|
|
36
|
+
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""Sunbay Nexus Python SDK public exports."""
|
|
2
|
+
|
|
3
|
+
from .client import NexusClient
|
|
4
|
+
from .exception import SunbayBusinessError, SunbayNetworkError
|
|
5
|
+
from .enums import (
|
|
6
|
+
AuthenticationMethod,
|
|
7
|
+
CardNetworkType,
|
|
8
|
+
EntryMode,
|
|
9
|
+
PaymentCategory,
|
|
10
|
+
TransactionStatus,
|
|
11
|
+
TransactionType,
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
__all__ = (
|
|
15
|
+
"NexusClient",
|
|
16
|
+
"SunbayBusinessError",
|
|
17
|
+
"SunbayNetworkError",
|
|
18
|
+
"TransactionStatus",
|
|
19
|
+
"TransactionType",
|
|
20
|
+
"CardNetworkType",
|
|
21
|
+
"EntryMode",
|
|
22
|
+
"PaymentCategory",
|
|
23
|
+
"AuthenticationMethod",
|
|
24
|
+
)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Public NexusClient for Sunbay Nexus Python SDK.
|
|
3
|
+
|
|
4
|
+
This client mirrors the Java SDK entry point and is intended to be the main
|
|
5
|
+
interface used by integrators.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import logging
|
|
9
|
+
import os
|
|
10
|
+
from typing import Optional
|
|
11
|
+
|
|
12
|
+
from .constant import (
|
|
13
|
+
DEFAULT_BASE_URL,
|
|
14
|
+
DEFAULT_CONNECT_TIMEOUT,
|
|
15
|
+
DEFAULT_MAX_CONNECTIONS,
|
|
16
|
+
DEFAULT_MAX_RETRIES,
|
|
17
|
+
DEFAULT_READ_TIMEOUT,
|
|
18
|
+
PATH_BATCH_CLOSE,
|
|
19
|
+
PATH_QUERY,
|
|
20
|
+
PATH_SALE,
|
|
21
|
+
)
|
|
22
|
+
from .exception import SunbayBusinessError
|
|
23
|
+
from .http import HttpClient
|
|
24
|
+
from .model.request import (
|
|
25
|
+
AbortRequest,
|
|
26
|
+
AuthRequest,
|
|
27
|
+
BatchCloseRequest,
|
|
28
|
+
ForcedAuthRequest,
|
|
29
|
+
IncrementalAuthRequest,
|
|
30
|
+
PostAuthRequest,
|
|
31
|
+
QueryRequest,
|
|
32
|
+
RefundRequest,
|
|
33
|
+
SaleRequest,
|
|
34
|
+
TipAdjustRequest,
|
|
35
|
+
VoidRequest,
|
|
36
|
+
)
|
|
37
|
+
from .model.response import (
|
|
38
|
+
AbortResponse,
|
|
39
|
+
AuthResponse,
|
|
40
|
+
BatchCloseResponse,
|
|
41
|
+
ForcedAuthResponse,
|
|
42
|
+
IncrementalAuthResponse,
|
|
43
|
+
PostAuthResponse,
|
|
44
|
+
QueryResponse,
|
|
45
|
+
RefundResponse,
|
|
46
|
+
SaleResponse,
|
|
47
|
+
TipAdjustResponse,
|
|
48
|
+
VoidResponse,
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class NexusClient:
|
|
53
|
+
"""
|
|
54
|
+
Main client for interacting with Sunbay Nexus APIs.
|
|
55
|
+
|
|
56
|
+
This client is designed to be thread-safe and reused across threads.
|
|
57
|
+
"""
|
|
58
|
+
|
|
59
|
+
def __init__(
|
|
60
|
+
self,
|
|
61
|
+
api_key: Optional[str] = None,
|
|
62
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
63
|
+
connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
|
|
64
|
+
read_timeout: float = DEFAULT_READ_TIMEOUT,
|
|
65
|
+
max_retries: int = DEFAULT_MAX_RETRIES,
|
|
66
|
+
max_connections: int = DEFAULT_MAX_CONNECTIONS,
|
|
67
|
+
logger: Optional[logging.Logger] = None,
|
|
68
|
+
) -> None:
|
|
69
|
+
if api_key is None:
|
|
70
|
+
api_key = os.getenv("SUNBAY_API_KEY")
|
|
71
|
+
if not api_key:
|
|
72
|
+
raise SunbayBusinessError("API key cannot be null or empty")
|
|
73
|
+
|
|
74
|
+
# Allow overriding base_url via environment for different environments
|
|
75
|
+
# (e.g. dev / uat / prod) while keeping a sensible default.
|
|
76
|
+
env_base_url = os.getenv("SUNBAY_BASE_URL")
|
|
77
|
+
if env_base_url:
|
|
78
|
+
base_url = env_base_url
|
|
79
|
+
|
|
80
|
+
self._http_client = HttpClient(
|
|
81
|
+
api_key=api_key,
|
|
82
|
+
base_url=base_url,
|
|
83
|
+
connect_timeout=connect_timeout,
|
|
84
|
+
read_timeout=read_timeout,
|
|
85
|
+
max_retries=max_retries,
|
|
86
|
+
max_connections=max_connections,
|
|
87
|
+
logger=logger,
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
# --- Transaction APIs ---
|
|
91
|
+
|
|
92
|
+
def sale(self, request: SaleRequest) -> SaleResponse:
|
|
93
|
+
if request is None:
|
|
94
|
+
raise SunbayBusinessError("SaleRequest cannot be null")
|
|
95
|
+
return self._http_client.post(PATH_SALE, request, SaleResponse)
|
|
96
|
+
|
|
97
|
+
def auth(self, request: AuthRequest) -> AuthResponse:
|
|
98
|
+
if request is None:
|
|
99
|
+
raise SunbayBusinessError("AuthRequest cannot be null")
|
|
100
|
+
return self._http_client.post(PATH_AUTH, request, AuthResponse)
|
|
101
|
+
|
|
102
|
+
def forced_auth(self, request: ForcedAuthRequest) -> ForcedAuthResponse:
|
|
103
|
+
if request is None:
|
|
104
|
+
raise SunbayBusinessError("ForcedAuthRequest cannot be null")
|
|
105
|
+
return self._http_client.post(PATH_FORCED_AUTH, request, ForcedAuthResponse)
|
|
106
|
+
|
|
107
|
+
def incremental_auth(self, request: IncrementalAuthRequest) -> IncrementalAuthResponse:
|
|
108
|
+
if request is None:
|
|
109
|
+
raise SunbayBusinessError("IncrementalAuthRequest cannot be null")
|
|
110
|
+
return self._http_client.post(PATH_INCREMENTAL_AUTH, request, IncrementalAuthResponse)
|
|
111
|
+
|
|
112
|
+
def post_auth(self, request: PostAuthRequest) -> PostAuthResponse:
|
|
113
|
+
if request is None:
|
|
114
|
+
raise SunbayBusinessError("PostAuthRequest cannot be null")
|
|
115
|
+
return self._http_client.post(PATH_POST_AUTH, request, PostAuthResponse)
|
|
116
|
+
|
|
117
|
+
def refund(self, request: RefundRequest) -> RefundResponse:
|
|
118
|
+
if request is None:
|
|
119
|
+
raise SunbayBusinessError("RefundRequest cannot be null")
|
|
120
|
+
return self._http_client.post(PATH_REFUND, request, RefundResponse)
|
|
121
|
+
|
|
122
|
+
def void_transaction(self, request: VoidRequest) -> VoidResponse:
|
|
123
|
+
if request is None:
|
|
124
|
+
raise SunbayBusinessError("VoidRequest cannot be null")
|
|
125
|
+
return self._http_client.post(PATH_VOID, request, VoidResponse)
|
|
126
|
+
|
|
127
|
+
def abort(self, request: AbortRequest) -> AbortResponse:
|
|
128
|
+
if request is None:
|
|
129
|
+
raise SunbayBusinessError("AbortRequest cannot be null")
|
|
130
|
+
return self._http_client.post(PATH_ABORT, request, AbortResponse)
|
|
131
|
+
|
|
132
|
+
def tip_adjust(self, request: TipAdjustRequest) -> TipAdjustResponse:
|
|
133
|
+
if request is None:
|
|
134
|
+
raise SunbayBusinessError("TipAdjustRequest cannot be null")
|
|
135
|
+
return self._http_client.post(PATH_TIP_ADJUST, request, TipAdjustResponse)
|
|
136
|
+
|
|
137
|
+
# --- Query APIs ---
|
|
138
|
+
|
|
139
|
+
def query(self, request: QueryRequest) -> QueryResponse:
|
|
140
|
+
if request is None:
|
|
141
|
+
raise SunbayBusinessError("QueryRequest cannot be null")
|
|
142
|
+
return self._http_client.get(PATH_QUERY, request, QueryResponse)
|
|
143
|
+
|
|
144
|
+
# --- Settlement APIs ---
|
|
145
|
+
|
|
146
|
+
def batch_close(self, request: BatchCloseRequest) -> BatchCloseResponse:
|
|
147
|
+
if request is None:
|
|
148
|
+
raise SunbayBusinessError("BatchCloseRequest cannot be null")
|
|
149
|
+
return self._http_client.post(PATH_BATCH_CLOSE, request, BatchCloseResponse)
|
|
150
|
+
|
|
151
|
+
# --- Lifecycle ---
|
|
152
|
+
|
|
153
|
+
def close(self) -> None:
|
|
154
|
+
"""
|
|
155
|
+
Close underlying HTTP resources.
|
|
156
|
+
"""
|
|
157
|
+
self._http_client.close()
|
|
158
|
+
|
|
159
|
+
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"""
|
|
2
|
+
API-related constants for Sunbay Nexus SDK.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
DEFAULT_BASE_URL: str = "https://open.sunbay.us"
|
|
6
|
+
|
|
7
|
+
# Timeouts are expressed in seconds for the requests library.
|
|
8
|
+
DEFAULT_CONNECT_TIMEOUT: float = 30.0
|
|
9
|
+
DEFAULT_READ_TIMEOUT: float = 60.0
|
|
10
|
+
|
|
11
|
+
# Maximum retry attempts for idempotent GET requests.
|
|
12
|
+
DEFAULT_MAX_RETRIES: int = 3
|
|
13
|
+
|
|
14
|
+
# Connection pool related settings (approximate mapping from Java defaults).
|
|
15
|
+
DEFAULT_MAX_CONNECTIONS: int = 200
|
|
16
|
+
|
|
17
|
+
# API response success code.
|
|
18
|
+
RESPONSE_SUCCESS_CODE: str = "0"
|
|
19
|
+
|
|
20
|
+
# HTTP status ranges.
|
|
21
|
+
HTTP_STATUS_OK_START: int = 200
|
|
22
|
+
HTTP_STATUS_OK_END: int = 300
|
|
23
|
+
HTTP_STATUS_CLIENT_ERROR_START: int = 400
|
|
24
|
+
HTTP_STATUS_CLIENT_ERROR_END: int = 500
|
|
25
|
+
HTTP_STATUS_SERVER_ERROR_START: int = 500
|
|
26
|
+
|
|
27
|
+
# Header names.
|
|
28
|
+
HEADER_AUTHORIZATION: str = "Authorization"
|
|
29
|
+
HEADER_REQUEST_ID: str = "X-Client-Request-Id"
|
|
30
|
+
HEADER_TIMESTAMP: str = "X-Timestamp"
|
|
31
|
+
HEADER_CONTENT_TYPE: str = "Content-Type"
|
|
32
|
+
|
|
33
|
+
AUTHORIZATION_BEARER_PREFIX: str = "Bearer "
|
|
34
|
+
CONTENT_TYPE_JSON: str = "application/json"
|
|
35
|
+
|
|
36
|
+
# API path prefixes.
|
|
37
|
+
SEMI_INTEGRATION_PREFIX: str = "/v1/semi-integration"
|
|
38
|
+
COMMON_PREFIX: str = "/v1"
|
|
39
|
+
|
|
40
|
+
# Semi-integration transaction API paths.
|
|
41
|
+
PATH_SALE: str = f"{SEMI_INTEGRATION_PREFIX}/transaction/sale"
|
|
42
|
+
PATH_AUTH: str = f"{SEMI_INTEGRATION_PREFIX}/transaction/auth"
|
|
43
|
+
PATH_FORCED_AUTH: str = f"{SEMI_INTEGRATION_PREFIX}/transaction/forced-auth"
|
|
44
|
+
PATH_INCREMENTAL_AUTH: str = f"{SEMI_INTEGRATION_PREFIX}/transaction/incremental-auth"
|
|
45
|
+
PATH_POST_AUTH: str = f"{SEMI_INTEGRATION_PREFIX}/transaction/post-auth"
|
|
46
|
+
PATH_REFUND: str = f"{SEMI_INTEGRATION_PREFIX}/transaction/refund"
|
|
47
|
+
PATH_VOID: str = f"{SEMI_INTEGRATION_PREFIX}/transaction/void"
|
|
48
|
+
PATH_ABORT: str = f"{SEMI_INTEGRATION_PREFIX}/transaction/abort"
|
|
49
|
+
PATH_TIP_ADJUST: str = f"{SEMI_INTEGRATION_PREFIX}/transaction/tip-adjust"
|
|
50
|
+
PATH_QUERY: str = f"{COMMON_PREFIX}/transaction/query"
|
|
51
|
+
|
|
52
|
+
# Semi-integration settlement API paths.
|
|
53
|
+
PATH_BATCH_CLOSE: str = f"{SEMI_INTEGRATION_PREFIX}/settlement/batch-close"
|
|
54
|
+
|
|
55
|
+
|