taiwan-payment-skill 1.3.0 → 1.3.2

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.
@@ -1,337 +1,337 @@
1
- #!/usr/bin/env python3
2
- """
3
- TapPay Python 範例 (後端部分)
4
-
5
- 依照 taiwan-payment-skill 規範撰寫。
6
- TapPay 採兩段式架構:
7
- 1. 前端 SDK 取得 Prime (60 秒 TTL,single-use)
8
- 2. 後端用 Prime 呼叫 pay-by-prime
9
-
10
- 支援:
11
- - pay-by-prime 一般付款
12
- - pay-by-card-token 重複扣款(訂閱、回購快速結帳)
13
- - refund 退款
14
- - query 查詢交易
15
-
16
- API 文件: 參見 references/tappay-payment-api.md
17
-
18
- 依賴:
19
- pip install requests
20
- """
21
-
22
- import json
23
- import time
24
- from dataclasses import dataclass, field
25
- from typing import Dict, List, Literal, Optional
26
-
27
- import requests
28
-
29
-
30
- # ============================================================================
31
- # Data classes
32
- # ============================================================================
33
-
34
- @dataclass
35
- class CardholderInfo:
36
- """TapPay cardholder 資料"""
37
- phone_number: str
38
- name: str
39
- email: str
40
- zip_code: str = ''
41
- address: str = ''
42
- national_id: str = ''
43
-
44
-
45
- @dataclass
46
- class TapPayResponse:
47
- success: bool
48
- status: int = 0 # 0 = 成功
49
- msg: str = ''
50
- rec_trade_id: str = ''
51
- bank_transaction_id: str = ''
52
- auth_code: str = ''
53
- card_secret: Optional[Dict[str, str]] = None # 含 card_key + card_token (記憶卡片時)
54
- payment_url: str = '' # 行動錢包付款導轉 URL
55
- raw: Dict[str, any] = field(default_factory=dict)
56
-
57
-
58
- # ============================================================================
59
- # Service
60
- # ============================================================================
61
-
62
- class TapPayService:
63
- """
64
- TapPay (CherryTech) 服務.
65
-
66
- 認證金鑰:
67
- - Partner Key: 後端密鑰,用於認證後端 API 呼叫
68
- - App Key: 前端 SDK 公鑰,用於取 Prime(不放後端)
69
- - Merchant ID: 商家識別
70
-
71
- 端點:
72
- - POST /tpc/payment/pay-by-prime Prime 付款
73
- - POST /tpc/payment/pay-by-card-token 重複扣款
74
- - POST /tpc/transaction/refund 退款
75
- - POST /tpc/transaction/query 查詢
76
- - POST /tpc/transaction/cap-refund 延遲請款後退款
77
- - POST /tpc/card/remove 解除綁卡
78
-
79
- Status code 對照(部分):
80
- 0 成功
81
- 1 付款失敗
82
- 2 參數錯誤
83
- 3 Prime 錯誤(過期/已用)
84
- 4 卡片資訊錯誤
85
- 5 銀行風控
86
- 7 卡片過期
87
- 10003 Partner Key 錯誤
88
- 10005 Merchant ID 錯誤
89
- 88001 3DS 驗證失敗
90
- """
91
-
92
- SANDBOX_BASE = 'https://sandbox.tappaysdk.com'
93
- PROD_BASE = 'https://prod.tappayapis.com'
94
-
95
- def __init__(self, partner_key: str, merchant_id: str, is_test: bool = True):
96
- if not partner_key or not merchant_id:
97
- raise ValueError('TapPay 需要 Partner Key 與 Merchant ID')
98
- self.partner_key = partner_key
99
- self.merchant_id = merchant_id
100
- self.base_url = self.SANDBOX_BASE if is_test else self.PROD_BASE
101
- self.is_test = is_test
102
-
103
- @property
104
- def headers(self) -> Dict[str, str]:
105
- return {
106
- 'x-api-key': self.partner_key,
107
- 'Content-Type': 'application/json',
108
- 'Accept': 'application/json',
109
- }
110
-
111
- # -- Operations -----------------------------------------------------------
112
-
113
- def pay_by_prime(
114
- self,
115
- prime: str,
116
- amount: int,
117
- order_number: str,
118
- cardholder: CardholderInfo,
119
- details: str = '',
120
- currency: str = 'TWD',
121
- remember: bool = False,
122
- result_url: Optional[Dict[str, str]] = None,
123
- delay_capture_in_days: int = 0,
124
- three_domain_secure: bool = False,
125
- ) -> TapPayResponse:
126
- """
127
- Prime 付款(單次).
128
-
129
- Args:
130
- prime: 前端 SDK 取得的 prime token (60 秒過期)
131
- amount: 金額(TWD 整數)
132
- order_number: 商家訂單號(唯一)
133
- cardholder: 持卡人資料
134
- remember: True 會在回應內帶 card_secret (card_key + card_token),可用於 pay-by-token
135
- result_url: {'frontend_redirect_url': '', 'backend_notify_url': '', 'go_back_url': ''}
136
- delay_capture_in_days: > 0 表示延遲請款(auth + capture)
137
- three_domain_secure: True 啟用 3DS
138
- """
139
- body = {
140
- 'partner_key': self.partner_key,
141
- 'prime': prime,
142
- 'merchant_id': self.merchant_id,
143
- 'details': details or order_number,
144
- 'amount': amount,
145
- 'currency': currency,
146
- 'order_number': order_number,
147
- 'cardholder': {
148
- 'phone_number': cardholder.phone_number,
149
- 'name': cardholder.name,
150
- 'email': cardholder.email,
151
- 'zip_code': cardholder.zip_code,
152
- 'address': cardholder.address,
153
- 'national_id': cardholder.national_id,
154
- },
155
- 'remember': remember,
156
- 'three_domain_secure': three_domain_secure,
157
- }
158
- if delay_capture_in_days > 0:
159
- body['delay_capture_in_days'] = delay_capture_in_days
160
- if result_url:
161
- body['result_url'] = result_url
162
- return self._submit('/tpc/payment/pay-by-prime', body)
163
-
164
- def pay_by_token(
165
- self,
166
- card_key: str,
167
- card_token: str,
168
- amount: int,
169
- order_number: str,
170
- details: str = '',
171
- currency: str = 'TWD',
172
- ) -> TapPayResponse:
173
- """重複扣款(訂閱、自動續訂)— 使用 pay-by-prime remember=True 取得的 card_key/card_token"""
174
- body = {
175
- 'card_key': card_key,
176
- 'card_token': card_token,
177
- 'partner_key': self.partner_key,
178
- 'merchant_id': self.merchant_id,
179
- 'amount': amount,
180
- 'currency': currency,
181
- 'details': details or order_number,
182
- 'order_number': order_number,
183
- }
184
- return self._submit('/tpc/payment/pay-by-card-token', body)
185
-
186
- def refund(self, rec_trade_id: str, amount: Optional[int] = None) -> TapPayResponse:
187
- """退款(amount 為 None 表示全額退)"""
188
- body = {
189
- 'partner_key': self.partner_key,
190
- 'rec_trade_id': rec_trade_id,
191
- }
192
- if amount is not None:
193
- body['amount'] = amount
194
- return self._submit('/tpc/transaction/refund', body)
195
-
196
- def query_transaction(
197
- self,
198
- rec_trade_id: Optional[str] = None,
199
- order_number: Optional[str] = None,
200
- bank_transaction_id: Optional[str] = None,
201
- ) -> TapPayResponse:
202
- """查詢交易"""
203
- filters: Dict[str, any] = {}
204
- if rec_trade_id:
205
- filters['rec_trade_id'] = rec_trade_id
206
- if order_number:
207
- filters['order_number'] = order_number
208
- if bank_transaction_id:
209
- filters['bank_transaction_id'] = bank_transaction_id
210
- body = {
211
- 'partner_key': self.partner_key,
212
- 'records_per_page': 50,
213
- 'page': 0,
214
- 'filters': filters,
215
- 'order_by': {'attribute': 'time', 'is_descending': True},
216
- }
217
- return self._submit('/tpc/transaction/query', body)
218
-
219
- def remove_card(self, card_key: str, card_token: str) -> TapPayResponse:
220
- """解除綁卡"""
221
- body = {
222
- 'partner_key': self.partner_key,
223
- 'card_key': card_key,
224
- 'card_token': card_token,
225
- }
226
- return self._submit('/tpc/card/remove', body)
227
-
228
- # -- HTTP submit ----------------------------------------------------------
229
-
230
- def _submit(self, path: str, body: Dict[str, any]) -> TapPayResponse:
231
- url = self.base_url + path
232
- try:
233
- r = requests.post(url, headers=self.headers, json=body, timeout=30)
234
- except requests.exceptions.RequestException as e:
235
- raise ConnectionError(f'TapPay API 連線失敗: {e}')
236
-
237
- try:
238
- resp = r.json()
239
- except ValueError:
240
- return TapPayResponse(
241
- success=False,
242
- status=r.status_code,
243
- msg=f'回應非 JSON: {r.text[:200]}',
244
- )
245
-
246
- status = int(resp.get('status', -1))
247
- is_success = (status == 0) and r.status_code < 400
248
-
249
- return TapPayResponse(
250
- success=is_success,
251
- status=status,
252
- msg=resp.get('msg', ''),
253
- rec_trade_id=resp.get('rec_trade_id', ''),
254
- bank_transaction_id=resp.get('bank_transaction_id', ''),
255
- auth_code=resp.get('auth_code', ''),
256
- card_secret=resp.get('card_secret') or None,
257
- payment_url=resp.get('payment_url', ''),
258
- raw=resp,
259
- )
260
-
261
-
262
- # ============================================================================
263
- # Examples
264
- # ============================================================================
265
-
266
- def example_pay_by_prime():
267
- print('=== TapPay Prime 付款 ===\n')
268
- svc = TapPayService(
269
- partner_key='YOUR_PARTNER_KEY', # 後端密鑰
270
- merchant_id='YOUR_MERCHANT_ID',
271
- is_test=True,
272
- )
273
- # prime 是前端 SDK (Direct Pay / TapPay Fields / Apple Pay 等) 取得的 token
274
- prime = 'PRIME_FROM_FRONTEND_SDK' # 60 秒過期
275
- cardholder = CardholderInfo(
276
- phone_number='+886912345678',
277
- name='王小明',
278
- email='test@example.com',
279
- )
280
- resp = svc.pay_by_prime(
281
- prime=prime,
282
- amount=1050,
283
- order_number=f'ORD{int(time.time())}',
284
- cardholder=cardholder,
285
- details='測試訂單',
286
- remember=True, # 拿 card_key + card_token 用於後續 pay-by-token
287
- )
288
- if resp.success:
289
- print(f'[OK] 付款成功')
290
- print(f' rec_trade_id: {resp.rec_trade_id}')
291
- print(f' auth_code: {resp.auth_code}')
292
- if resp.card_secret:
293
- print(f' card_key: {resp.card_secret.get("card_key")}')
294
- print(f' card_token: {resp.card_secret.get("card_token")}')
295
- else:
296
- print(f'[FAIL] status={resp.status} msg={resp.msg}')
297
-
298
-
299
- def example_pay_by_token():
300
- print('\n=== TapPay 重複扣款 (Token) ===\n')
301
- svc = TapPayService('YOUR_PARTNER_KEY', 'YOUR_MERCHANT_ID', is_test=True)
302
- # card_key / card_token 來自先前 pay_by_prime(remember=True) 的回應
303
- resp = svc.pay_by_token(
304
- card_key='SAVED_CARD_KEY',
305
- card_token='SAVED_CARD_TOKEN',
306
- amount=199,
307
- order_number=f'SUB{int(time.time())}',
308
- details='月費訂閱',
309
- )
310
- if resp.success:
311
- print(f'[OK] 訂閱扣款成功: rec_trade_id={resp.rec_trade_id}')
312
- else:
313
- print(f'[FAIL] status={resp.status} msg={resp.msg}')
314
-
315
-
316
- def example_refund():
317
- print('\n=== TapPay 退款 ===\n')
318
- svc = TapPayService('YOUR_PARTNER_KEY', 'YOUR_MERCHANT_ID', is_test=True)
319
- resp = svc.refund(rec_trade_id='ABC123', amount=500) # 部分退款 NT$500
320
- if resp.success:
321
- print('[OK] 退款成功')
322
- else:
323
- print(f'[FAIL] status={resp.status} msg={resp.msg}')
324
-
325
-
326
- def example_query_transaction():
327
- print('\n=== TapPay 查詢交易 ===\n')
328
- svc = TapPayService('YOUR_PARTNER_KEY', 'YOUR_MERCHANT_ID', is_test=True)
329
- resp = svc.query_transaction(order_number='ORD123456')
330
- print(json.dumps(resp.raw, ensure_ascii=False, indent=2))
331
-
332
-
333
- if __name__ == '__main__':
334
- example_pay_by_prime()
335
- example_pay_by_token()
336
- example_refund()
337
- example_query_transaction()
1
+ #!/usr/bin/env python3
2
+ """
3
+ TapPay Python 範例 (後端部分)
4
+
5
+ 依照 taiwan-payment-skill 規範撰寫。
6
+ TapPay 採兩段式架構:
7
+ 1. 前端 SDK 取得 Prime (60 秒 TTL,single-use)
8
+ 2. 後端用 Prime 呼叫 pay-by-prime
9
+
10
+ 支援:
11
+ - pay-by-prime 一般付款
12
+ - pay-by-card-token 重複扣款(訂閱、回購快速結帳)
13
+ - refund 退款
14
+ - query 查詢交易
15
+
16
+ API 文件: 參見 references/tappay-payment-api.md
17
+
18
+ 依賴:
19
+ pip install requests
20
+ """
21
+
22
+ import json
23
+ import time
24
+ from dataclasses import dataclass, field
25
+ from typing import Dict, List, Literal, Optional
26
+
27
+ import requests
28
+
29
+
30
+ # ============================================================================
31
+ # Data classes
32
+ # ============================================================================
33
+
34
+ @dataclass
35
+ class CardholderInfo:
36
+ """TapPay cardholder 資料"""
37
+ phone_number: str
38
+ name: str
39
+ email: str
40
+ zip_code: str = ''
41
+ address: str = ''
42
+ national_id: str = ''
43
+
44
+
45
+ @dataclass
46
+ class TapPayResponse:
47
+ success: bool
48
+ status: int = 0 # 0 = 成功
49
+ msg: str = ''
50
+ rec_trade_id: str = ''
51
+ bank_transaction_id: str = ''
52
+ auth_code: str = ''
53
+ card_secret: Optional[Dict[str, str]] = None # 含 card_key + card_token (記憶卡片時)
54
+ payment_url: str = '' # 行動錢包付款導轉 URL
55
+ raw: Dict[str, any] = field(default_factory=dict)
56
+
57
+
58
+ # ============================================================================
59
+ # Service
60
+ # ============================================================================
61
+
62
+ class TapPayService:
63
+ """
64
+ TapPay (CherryTech) 服務.
65
+
66
+ 認證金鑰:
67
+ - Partner Key: 後端密鑰,用於認證後端 API 呼叫
68
+ - App Key: 前端 SDK 公鑰,用於取 Prime(不放後端)
69
+ - Merchant ID: 商家識別
70
+
71
+ 端點:
72
+ - POST /tpc/payment/pay-by-prime Prime 付款
73
+ - POST /tpc/payment/pay-by-card-token 重複扣款
74
+ - POST /tpc/transaction/refund 退款
75
+ - POST /tpc/transaction/query 查詢
76
+ - POST /tpc/transaction/cap-refund 延遲請款後退款
77
+ - POST /tpc/card/remove 解除綁卡
78
+
79
+ Status code 對照(部分):
80
+ 0 成功
81
+ 1 付款失敗
82
+ 2 參數錯誤
83
+ 3 Prime 錯誤(過期/已用)
84
+ 4 卡片資訊錯誤
85
+ 5 銀行風控
86
+ 7 卡片過期
87
+ 10003 Partner Key 錯誤
88
+ 10005 Merchant ID 錯誤
89
+ 88001 3DS 驗證失敗
90
+ """
91
+
92
+ SANDBOX_BASE = 'https://sandbox.tappaysdk.com'
93
+ PROD_BASE = 'https://prod.tappayapis.com'
94
+
95
+ def __init__(self, partner_key: str, merchant_id: str, is_test: bool = True):
96
+ if not partner_key or not merchant_id:
97
+ raise ValueError('TapPay 需要 Partner Key 與 Merchant ID')
98
+ self.partner_key = partner_key
99
+ self.merchant_id = merchant_id
100
+ self.base_url = self.SANDBOX_BASE if is_test else self.PROD_BASE
101
+ self.is_test = is_test
102
+
103
+ @property
104
+ def headers(self) -> Dict[str, str]:
105
+ return {
106
+ 'x-api-key': self.partner_key,
107
+ 'Content-Type': 'application/json',
108
+ 'Accept': 'application/json',
109
+ }
110
+
111
+ # -- Operations -----------------------------------------------------------
112
+
113
+ def pay_by_prime(
114
+ self,
115
+ prime: str,
116
+ amount: int,
117
+ order_number: str,
118
+ cardholder: CardholderInfo,
119
+ details: str = '',
120
+ currency: str = 'TWD',
121
+ remember: bool = False,
122
+ result_url: Optional[Dict[str, str]] = None,
123
+ delay_capture_in_days: int = 0,
124
+ three_domain_secure: bool = False,
125
+ ) -> TapPayResponse:
126
+ """
127
+ Prime 付款(單次).
128
+
129
+ Args:
130
+ prime: 前端 SDK 取得的 prime token (60 秒過期)
131
+ amount: 金額(TWD 整數)
132
+ order_number: 商家訂單號(唯一)
133
+ cardholder: 持卡人資料
134
+ remember: True 會在回應內帶 card_secret (card_key + card_token),可用於 pay-by-token
135
+ result_url: {'frontend_redirect_url': '', 'backend_notify_url': '', 'go_back_url': ''}
136
+ delay_capture_in_days: > 0 表示延遲請款(auth + capture)
137
+ three_domain_secure: True 啟用 3DS
138
+ """
139
+ body = {
140
+ 'partner_key': self.partner_key,
141
+ 'prime': prime,
142
+ 'merchant_id': self.merchant_id,
143
+ 'details': details or order_number,
144
+ 'amount': amount,
145
+ 'currency': currency,
146
+ 'order_number': order_number,
147
+ 'cardholder': {
148
+ 'phone_number': cardholder.phone_number,
149
+ 'name': cardholder.name,
150
+ 'email': cardholder.email,
151
+ 'zip_code': cardholder.zip_code,
152
+ 'address': cardholder.address,
153
+ 'national_id': cardholder.national_id,
154
+ },
155
+ 'remember': remember,
156
+ 'three_domain_secure': three_domain_secure,
157
+ }
158
+ if delay_capture_in_days > 0:
159
+ body['delay_capture_in_days'] = delay_capture_in_days
160
+ if result_url:
161
+ body['result_url'] = result_url
162
+ return self._submit('/tpc/payment/pay-by-prime', body)
163
+
164
+ def pay_by_token(
165
+ self,
166
+ card_key: str,
167
+ card_token: str,
168
+ amount: int,
169
+ order_number: str,
170
+ details: str = '',
171
+ currency: str = 'TWD',
172
+ ) -> TapPayResponse:
173
+ """重複扣款(訂閱、自動續訂)— 使用 pay-by-prime remember=True 取得的 card_key/card_token"""
174
+ body = {
175
+ 'card_key': card_key,
176
+ 'card_token': card_token,
177
+ 'partner_key': self.partner_key,
178
+ 'merchant_id': self.merchant_id,
179
+ 'amount': amount,
180
+ 'currency': currency,
181
+ 'details': details or order_number,
182
+ 'order_number': order_number,
183
+ }
184
+ return self._submit('/tpc/payment/pay-by-card-token', body)
185
+
186
+ def refund(self, rec_trade_id: str, amount: Optional[int] = None) -> TapPayResponse:
187
+ """退款(amount 為 None 表示全額退)"""
188
+ body = {
189
+ 'partner_key': self.partner_key,
190
+ 'rec_trade_id': rec_trade_id,
191
+ }
192
+ if amount is not None:
193
+ body['amount'] = amount
194
+ return self._submit('/tpc/transaction/refund', body)
195
+
196
+ def query_transaction(
197
+ self,
198
+ rec_trade_id: Optional[str] = None,
199
+ order_number: Optional[str] = None,
200
+ bank_transaction_id: Optional[str] = None,
201
+ ) -> TapPayResponse:
202
+ """查詢交易"""
203
+ filters: Dict[str, any] = {}
204
+ if rec_trade_id:
205
+ filters['rec_trade_id'] = rec_trade_id
206
+ if order_number:
207
+ filters['order_number'] = order_number
208
+ if bank_transaction_id:
209
+ filters['bank_transaction_id'] = bank_transaction_id
210
+ body = {
211
+ 'partner_key': self.partner_key,
212
+ 'records_per_page': 50,
213
+ 'page': 0,
214
+ 'filters': filters,
215
+ 'order_by': {'attribute': 'time', 'is_descending': True},
216
+ }
217
+ return self._submit('/tpc/transaction/query', body)
218
+
219
+ def remove_card(self, card_key: str, card_token: str) -> TapPayResponse:
220
+ """解除綁卡"""
221
+ body = {
222
+ 'partner_key': self.partner_key,
223
+ 'card_key': card_key,
224
+ 'card_token': card_token,
225
+ }
226
+ return self._submit('/tpc/card/remove', body)
227
+
228
+ # -- HTTP submit ----------------------------------------------------------
229
+
230
+ def _submit(self, path: str, body: Dict[str, any]) -> TapPayResponse:
231
+ url = self.base_url + path
232
+ try:
233
+ r = requests.post(url, headers=self.headers, json=body, timeout=30)
234
+ except requests.exceptions.RequestException as e:
235
+ raise ConnectionError(f'TapPay API 連線失敗: {e}')
236
+
237
+ try:
238
+ resp = r.json()
239
+ except ValueError:
240
+ return TapPayResponse(
241
+ success=False,
242
+ status=r.status_code,
243
+ msg=f'回應非 JSON: {r.text[:200]}',
244
+ )
245
+
246
+ status = int(resp.get('status', -1))
247
+ is_success = (status == 0) and r.status_code < 400
248
+
249
+ return TapPayResponse(
250
+ success=is_success,
251
+ status=status,
252
+ msg=resp.get('msg', ''),
253
+ rec_trade_id=resp.get('rec_trade_id', ''),
254
+ bank_transaction_id=resp.get('bank_transaction_id', ''),
255
+ auth_code=resp.get('auth_code', ''),
256
+ card_secret=resp.get('card_secret') or None,
257
+ payment_url=resp.get('payment_url', ''),
258
+ raw=resp,
259
+ )
260
+
261
+
262
+ # ============================================================================
263
+ # Examples
264
+ # ============================================================================
265
+
266
+ def example_pay_by_prime():
267
+ print('=== TapPay Prime 付款 ===\n')
268
+ svc = TapPayService(
269
+ partner_key='YOUR_PARTNER_KEY', # 後端密鑰
270
+ merchant_id='YOUR_MERCHANT_ID',
271
+ is_test=True,
272
+ )
273
+ # prime 是前端 SDK (Direct Pay / TapPay Fields / Apple Pay 等) 取得的 token
274
+ prime = 'PRIME_FROM_FRONTEND_SDK' # 60 秒過期
275
+ cardholder = CardholderInfo(
276
+ phone_number='+886912345678',
277
+ name='王小明',
278
+ email='test@example.com',
279
+ )
280
+ resp = svc.pay_by_prime(
281
+ prime=prime,
282
+ amount=1050,
283
+ order_number=f'ORD{int(time.time())}',
284
+ cardholder=cardholder,
285
+ details='測試訂單',
286
+ remember=True, # 拿 card_key + card_token 用於後續 pay-by-token
287
+ )
288
+ if resp.success:
289
+ print(f'[OK] 付款成功')
290
+ print(f' rec_trade_id: {resp.rec_trade_id}')
291
+ print(f' auth_code: {resp.auth_code}')
292
+ if resp.card_secret:
293
+ print(f' card_key: {resp.card_secret.get("card_key")}')
294
+ print(f' card_token: {resp.card_secret.get("card_token")}')
295
+ else:
296
+ print(f'[FAIL] status={resp.status} msg={resp.msg}')
297
+
298
+
299
+ def example_pay_by_token():
300
+ print('\n=== TapPay 重複扣款 (Token) ===\n')
301
+ svc = TapPayService('YOUR_PARTNER_KEY', 'YOUR_MERCHANT_ID', is_test=True)
302
+ # card_key / card_token 來自先前 pay_by_prime(remember=True) 的回應
303
+ resp = svc.pay_by_token(
304
+ card_key='SAVED_CARD_KEY',
305
+ card_token='SAVED_CARD_TOKEN',
306
+ amount=199,
307
+ order_number=f'SUB{int(time.time())}',
308
+ details='月費訂閱',
309
+ )
310
+ if resp.success:
311
+ print(f'[OK] 訂閱扣款成功: rec_trade_id={resp.rec_trade_id}')
312
+ else:
313
+ print(f'[FAIL] status={resp.status} msg={resp.msg}')
314
+
315
+
316
+ def example_refund():
317
+ print('\n=== TapPay 退款 ===\n')
318
+ svc = TapPayService('YOUR_PARTNER_KEY', 'YOUR_MERCHANT_ID', is_test=True)
319
+ resp = svc.refund(rec_trade_id='ABC123', amount=500) # 部分退款 NT$500
320
+ if resp.success:
321
+ print('[OK] 退款成功')
322
+ else:
323
+ print(f'[FAIL] status={resp.status} msg={resp.msg}')
324
+
325
+
326
+ def example_query_transaction():
327
+ print('\n=== TapPay 查詢交易 ===\n')
328
+ svc = TapPayService('YOUR_PARTNER_KEY', 'YOUR_MERCHANT_ID', is_test=True)
329
+ resp = svc.query_transaction(order_number='ORD123456')
330
+ print(json.dumps(resp.raw, ensure_ascii=False, indent=2))
331
+
332
+
333
+ if __name__ == '__main__':
334
+ example_pay_by_prime()
335
+ example_pay_by_token()
336
+ example_refund()
337
+ example_query_transaction()