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.
- package/README.md +66 -137
- package/assets/taiwan-payment/README.md +65 -330
- package/assets/taiwan-payment/data/payment-methods.csv +11 -0
- package/assets/taiwan-payment/examples/linepay-payment-example.py +305 -305
- package/assets/taiwan-payment/examples/shopline-payment-example.py +291 -291
- package/assets/taiwan-payment/examples/tappay-payment-example.py +337 -337
- package/assets/taiwan-payment/references/ecpay-payment-api.md +53 -0
- package/package.json +2 -2
|
@@ -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()
|