ATM 虛擬帳號轉帳產品文件V1.2.0

文件修訂紀錄: 2024.04.16

0TapPay – ATM 虛擬帳號轉帳產品文件

日期(YYYY.M
M.DD)

修訂紀錄

版本號

2024.02.15

初版

V1.0.0Peggy

V1.1.0CharmianV1.2.0

Kyle

編輯
人員

1. 新增 3.1 前端 SDK 說明
2. 移除 3.2 後端 API 說明 - RefundAPI 說明、3.2.2 取消交易流程圖
3. 調整 4.2 Backend Notify 中 4.2.3
Request Body 及 4.2.4 Requet
Example pay_info 欄位名稱及說明
2024.04.11

4. 移除原 4.3 Refund API 功能及原接
續章節編號
5. 調整 4.3 Record 中 4.3.5 Request
Body 及 4.3.6 Requet Example
pay_info 欄位名稱及說明
6. 移除 5. Error Code 與說明欄位

2024.4.16

1. 更新 3.2.2 流程圖

1TapPay – ATM 虛擬帳號轉帳產品文件目錄
1. 說明與應用.......................................................................................................................................... 4
2. 架構介紹與角色定位.......................................................................................................................... 5
2.1. 架構說明 ...................................................................................................................................... 5
2.2. 角色定位 ...................................................................................................................................... 5
3. 功能說明與資料流.............................................................................................................................. 6
3.1. 前端 SDK 說明 ............................................................................................................................ 6
3.1.1 Setup SDK .............................................................................................................................. 6
3.1.2 Get Prime................................................................................................................................ 6
3.2. 後端 API 說明 ............................................................................................................................. 7
3.3. 資訊流 .......................................................................................................................................... 8
3.3.1 正向交易 ............................................................................................................................... 8
3.2.2 Sandbox 模擬交易 ................................................................................................................. 9
4. API 規格 ............................................................................................................................................. 10
4.1 Pay by Prime ................................................................................................................................ 10
4.1.1 Request Type & URL ........................................................................................................... 10
4.1.2 Request Header..................................................................................................................... 10
4.1.3 Request Body ....................................................................................................................... 11
4.1.4 Request Example .................................................................................................................. 12
4.1.5 Response Body ..................................................................................................................... 13
4.1.6 Response Example ............................................................................................................... 14
4.2 Backend Notify ............................................................................................................................ 15
4.2.1 Request Type & URL ........................................................................................................... 15
4.2.2 Request Header..................................................................................................................... 15
4.2.3 Request Body ....................................................................................................................... 15
4.2.4 Request Example .................................................................................................................. 16
4.3 Record .......................................................................................................................................... 16
4.3.1 Request Type & URL ........................................................................................................... 16
4.3.2 Request Header..................................................................................................................... 16
4.3.3 Request Body ....................................................................................................................... 16
4.3.4 Request Example .................................................................................................................. 18
4.3.5 Response Body ..................................................................................................................... 19
4.3.6 Response Example ............................................................................................................... 26
4.4 Trade History................................................................................................................................ 28
4.4.1 Request Type & URL ........................................................................................................... 28
4.4.2 Request Header..................................................................................................................... 28
4.4.3 Request Body ....................................................................................................................... 28
4.4.4 Request Example .................................................................................................................. 28
4.4.5 Response Body ..................................................................................................................... 29
4.4.6 Response Example ............................................................................................................... 30
4.5 Reconciliation............................................................................................................................... 31
4.5.1 Request Type & URL ........................................................................................................... 31
4.5.2 Request Header..................................................................................................................... 31
4.5.3 Request Body ....................................................................................................................... 31
4.5.4 Request Example .................................................................................................................. 31
4.5.5 Response Body ..................................................................................................................... 32
2

TapPay – ATM 虛擬帳號轉帳產品文件

4.5.6 Response Example ............................................................................................................... 36
4.6 Simulated Payment....................................................................................................................... 37
4.6.1 Request Type & URL ........................................................................................................... 37
4.6.2 Request Header..................................................................................................................... 37
4.6.3 Request Body ....................................................................................................................... 37
4.6.4 Request Example .................................................................................................................. 37
4.6.5 Response Body ..................................................................................................................... 37
4.6.6 Response Example ............................................................................................................... 37
5. ERROR CODE ................................................................................................................................... 38

3

TapPay – ATM 虛擬帳號轉帳產品文件

1. 說明與應用
本文旨在說明 TapPay 代收付商戶如何藉由 TapPay 服務使用非同步支付ATM 轉帳進行收款。
商戶可透過 TapPay 服務取得 ATM 虛擬帳號，將其提供予消費者使用自動櫃員機或網路銀行完成 ATM 轉帳付款，並於消費者付款後接收付款完成通知。
注意事項：
l

需使用 TapPay Web SDK 5.18.0 以上才支援『ATM』功能。

l

因應政府針對網路虛擬 ATM 與一般 ATM 轉帳交易收款金融機構規則，TapPay ATM
轉帳每筆交易金額為 49,999 元(含)以下。

l

繳費逾期
n

系統串接可能有延遲通知狀況，若有逾期判斷需求，建議不要於繳費期限即時判
斷。

4

TapPay – ATM 虛擬帳號轉帳產品文件

2. 架構介紹與角色定位
2.1. 架構說明2.2. 角色定位l

商戶伺服器(Merchant Server)：向 TapPay 發起取 ATM 虛擬帳號、取消交易等動作l

TapPay Server：負責處理交易分流、取消交易等作業

lBank Server：負責驗證 ATM 虛擬帳號有效性及金額，並於收款後發出付款完成通知

5

TapPay – ATM 虛擬帳號轉帳產品文件

3. 功能說明與資料流
3.1. 前端 SDK 說明
於結帳頁面引用 TapPay SDK，以取得交易所需要的 Prime。

3.1.1 Setup SDK
設定 SDK 相關參數與環境。
TPDirect.setupSDK(appID, appKey, serverType)

名稱
appID

說明

appKey

於後台「開發人員內容」可取得，請參考 appkey

serverTypesandbox, production

於後台「開發人員內容」可取得，請參考 appid

Example code
<script src="https://js.tappaysdk.com/sdk/tpdirect/v5.18.0"></script><script>
TPDirect.setupSDK(APP_ID, 'APP_KEY', 'sandbox')</script>3.1.2 Get Prime
取得 ATM 專屬的 Prime，並將 Prime 送到您自己的伺服器。
TPDirect.virtualAccount.getPrime(callback)Example code
function getPrime() {// Get Prime
TPDirect.virtualAccount.getPrime(function(error, result){
if (error) {console.log(error);
return;}if (result.status !== 0) {console.log("result : " , result)// Post Prime To Your Server// $.ajax({//
url: '/create_order',//data: {//
"prime" : result.prime//},//
type: "POST",//
dateType: "json",//
success: function(result) {//$('#sendButton').click(function() {6

TapPay – ATM 虛擬帳號轉帳產品文件

//
//
//
//
//
//
//
//
// })

// Go to ATM(VirtualAccount) Payment Page.
TPDirect.redirect(result.payment_url)})},
error: function (xhr, ajaxOptions, thrownError) {alert(xhr.status);alert(thrownError);
}

}
})
}

3.2. 後端 API 說明
API 名稱
Pay by Prime

功能描述

Backend Notify

透過 Pay by Prime 設定 backend_notify_url ，當 ATM 轉帳

可利用此 API 取得 ATM 虛擬帳號並設置繳費期限。
完成後，系統會發一個 POST 到 backend_notify_url 進行
付款完成通知Record此 API 能讓您用您的後台直接進行交易紀錄查詢Trade History

此 API 能讓您查詢該筆交易的詳細狀態

Reconciliation

此 API 能讓您查詢 TapPay 與銀行請退款後的結果，如欲取得 TapPay 與銀行最新請退款結果，請於每日 13:00 pm
以後於此篩選前一日請退款結果。
此 API 僅支援回覆 2020/10/16 以後的請退款紀錄
請注意資料篩選的時間區間，起始時間到結束時間的天數不
得超過 31 天Simulated
Payment

此 API 能讓您在 Sandbox 環境模擬付款完成通知

7

TapPay – ATM 虛擬帳號轉帳產品文件

3.3. 資訊流
3.3.1 正向交易

8

TapPay – ATM 虛擬帳號轉帳產品文件

3.2.2 Sandbox 模擬交易

9

TapPay – ATM 虛擬帳號轉帳產品文件

4. API 規格
我們的後台使用的是 REST 架構，所以每個請求皆是使用 HTTP POST 來進
行傳輸。

4.1 Pay by Prime
4.1.1 Request Type & URL
Production Request URL
Sandbox Request URL
4.1.2 Request Header
x-api-key
Content-Typehttps://prod.tappaysdk.com/tpc/payment/pay-byprime
https://sandbox.tappaysdk.com/tpc/payment/payby-prime
Your Partner Key
application/json

10

TapPay – ATM 虛擬帳號轉帳產品文件

4.1.3 Request Body
名稱(* =

型別(長度)

說明

必填)
prime*

String(67)由 getPrime 成功時回傳，prime 的時效為 90 秒
ATM sandbox 測試 prime：
va_test_33e97cb62276e4010813921f66f99b1f2d8910
7f6b81084e6e35ad2a79404142

partner_key*
merchant_id*merchant_g
roup_id

String(64)綁定 Portal 帳戶的驗證金鑰

String(50)

於 Portal 登錄商家時所產生的識別碼String(50)

於 Portal 設置的商家管理設置，交易時會依據
portal 的支付配置進行交易
不可與 merchant_id 同時使用

amount*int

交易金額。目前僅支援台幣，ATM 金額限制為
16-49,999 元。

currency

String(3)貨幣種類。預設為 TWD

order_numb String(50)er商戶自行定義的訂單編號，用於 TapPay 做訂單

bank_transa
ction_id

銀行端的訂單編號。

String(30)識別，可重複帶入由大寫英文字母及數字所組成的訂單編號，強烈建議商戶可自訂，但不能與之前的重複；若您沒有自訂則會自動幫您產生一組。
但若您沒自訂，當發生 421 Gateway 操作逾時
（發生機率低），則無法反查該筆交易。

details*

String(100)交易品項內容，為符合 PCI 要求至少必須要有品
項名稱

cardholder*

JSONObject 持卡人或購買人資訊
名稱(* =

型別必填)
phone_num
ber*

(長度)
String( 手機號碼，可為 09 開頭的電話或是包
40)
含加號之 E.164 格式(“+886923456789”)
String( 姓名40)String( 電子信箱
40)

name*
email*

說明

11

TapPay – ATM 虛擬帳號轉帳產品文件

zip_code
addressnational_id
result_url*

String( 郵遞區號
40)
String( 地址90)String( 身份證字號
40)

JSONObject 交易結果 URL
名稱(* =

型別

必填)
(長度)
backend_not String
ify_url*說明
商戶 Server 接收付款完成通知的
URL。必須以 https 開頭，僅支援 443
port。

additional_
data

JSONString(3000)

資料會加密保存，並在其他客製化需求時才解密

expire_in_d
ays

int

繳費資訊有效天數。

做使用
ATM 天數限制為 1-7 天，預設值 7 天。

4.1.4 Request Example// *** Format ***// Sandbox URL: https://sandbox.tappaysdk.com/tpc/payment/pay-by-prime// Production URL: https://prod.tappaysdk.com/tpc/payment/pay-by-prime// Header:// Content-Type: application/json// x-api-key: Your Partner Key{"prime":"va_test_33e97cb62276e4010813921f66f99b1f2d89107f6b81084e6e35ad2a794041
42","partner_key": " Your Partner Key ","merchant_id": "ATM_merchant_ID ","amount": 30,"order_number": "123456478","bank_transaction_id": "7874545","details": "ATM","cardholder": {"phone_number": "+0987654321","name": "Test","email": "test@cherricorp.com"},"result_url": {"backend_notify_url": "Backend Notify"},"expire_in_days": 1}12

TapPay – ATM 虛擬帳號轉帳產品文件

4.1.5 Response Body
名稱status型別(長度)
int

說明

msg

String

交易訊息

rec_trade_id

String(20)TapPay 交易紀錄識別碼交易代碼，成功的話為 0將於請退款、查詢時用到，請妥善保管
bank_transaction_id

String(30)

銀行端的訂單編號

amountint

交易金額。

order_number

String(50)商戶自行定義的訂單編號，用於TapPay 做訂單識別，可重複帶入格式請參考 reference。若有帶入此
欄位，則不能為空

acquirer

String收單銀行 / 金流處理器

transaction_time_millis long

交易時間

bank_transaction_time

銀行處理時間JSONObject

名稱
型別(長度) 說明
start_time_millis String單位為毫秒
end_time_millis String單位為毫秒
bank_result_code

String(40)

銀行回傳的交易結果代碼bank_result_msg

String(300)

銀行回傳的交易結果訊息

merchant_id

String(50)

於 Portal 登錄商家時所產生的識別碼

payee_info

JSONObject

繳費資訊

名稱
expire_time
vacc_bank_code

型別(長度) 說明
String(20)繳費截止時間，格式
yyyy-mm-dd hh:mi:ss
String(5)繳費金融代碼。

vacc_noString(16)繳費虛擬帳號。

13

TapPay – ATM 虛擬帳號轉帳產品文件

4.1.6 Response Example{"status": 0,"msg": "Success","rec_trade_id": "VA20240215FncyTm","bank_transaction_id": "7874545","amount": 30,"order_number": "123456478","acquirer": "TW_TAPPAY_ATM","transaction_time_millis": 1707989054080,"bank_transaction_time": {"start_time_millis": "1707989054099","end_time_millis": "1707989054857"},"bank_result_code": "SUCCESS","bank_result_msg": "","merchant_id": " ATM merchant ID ","payee_info": {"expire_time": "2024-02-16 23:59:59","vacc_bank_code": "822","vacc_no": "9259624020021523"}}

14

TapPay – ATM 虛擬帳號轉帳產品文件

4.2 Backend Notify
4.2.1 Request Type & URL
Product Request URL
Sandbox Request URL
4.2.2 Request Header
Content-Type
X-Api-Checksum{backend_notify_url}{backend_notify_url}
application/json
如果商戶設有 share_secret 則有此值

4.2.3 Request Body
名稱(* = 必填)
status*型別(長度)
String說明msg*

String

交易訊息

rec_trade_id*

StringTapPay 交易紀錄識別碼

bank_transaction_id*

String

銀行端訂單編號order_number

String您自定義的訂單編號amount*int

金額

交易代碼，成功為 0transaction_time_millis* Long

交易時間

pay_info*

JSONObject付款資訊

名稱(* = 必填)
payment_time*

型別(長度)
String(20)

說明
付款時間，
格式 yyyymm-dd
hh:mi:ss。

payer_bank_code*

String(5)

付款銀行機
構代碼。

payer_account_last_five* String(16)

付款銀行帳
號後五碼。

acquirer*

String收單銀行 / 金流處理器

15

TapPay – ATM 虛擬帳號轉帳產品文件

4.2.4 Request Example// *** Format ***// Sandbox URL: {backend_notify_url}// Production URL: {backend_notify_url}// Header:// Content-Type: application/json// x-api-key: Your Partner Key{"status": 0,"msg": "Success","rec_trade_id": "VA20240126VN984Y","bank_transaction_id": "TP20240126VN984Y","order_number": "","amount": 30,"transaction_time_millis": 1706245003557,"pay_info": {"payment_time": "2024-01-26 12:56:41","payer_bank_code": "822","payer_account_last_five": "付款銀行帳號後五碼"},"acquirer": "TW_TAPPAY_ATM"}

4.3 Record
4.3.1 Request Type & URL
Product Request URL https://prod.tappaysdk.com/tpc/transaction/query
Sandbox Request URL https://sandbox.tappaysdk.com/tpc/transaction/query
4.3.2 Request Header
x-api-key
Your Partner Key
Content-Typeapplication/json
4.3.3 Request Body
名稱(* = 必填)
partner_key*

型別(長度)
String(64)records_per_page int說明綁定 Portal 帳戶的驗證金鑰每頁的交易數量，最大為 200，預設
為 50

Page

int

第幾頁交易，預設為 0

filters*

JSONObject

交易紀錄的限制

名稱(* = 必填)
time*

型別(長度)JSONObject

說明起始到結束時間上限
為 90 天16

TapPay – ATM 虛擬帳號轉帳產品文件

amountcardholder

merchant_id

名稱(* = 必

型別

說明

填)

(長

start_time*

度)
long

end_time*

long

JSONObject

金額條件

名稱(* = 必

型別

填)

(長

upper_limit

度)
int

最高價格

lower_limit

int

最低價格

JSONObject

消費者條件

名稱(* = 必

型別

填)

(長

name

度)
String

姓名

phone_number String

電話

email

String

電子信箱

Array String

於 Portal 登錄商家時

起始時間(Milliseconds)
結束時間(Milliseconds)
說明說明所產生的識別碼。可
放多個 Merchant ID。
record_statusint

交易紀錄的狀態
-1：交易錯誤
1：交易完成2：部分退款
3：完全退款
4：待付款
17

TapPay – ATM 虛擬帳號轉帳產品文件

5：取消交易rec_trade_id

StringTapPay 交易紀錄識別碼order_number

String

商戶自行定義的訂單編號

bank_transaction_id Stringorder_by

JSONObject

排序的方式。

名稱(* = 必填)
attribute

型別(長度)
String

銀行端的訂單編號
說明
排序欄位。預設
值為 time。
time：時間排序
amount：金額排序

is_descending

boolean

排序方式。預設
為 true。
true：降冪
false：升冪

4.3.4 Request Example
curl --location ' https://prod.tappaysdk.com/tpc/transaction/query ' \--header 'x-api-key: Your Partner Key' \--header 'Content-Type: application/json' \--data-raw '{"partner_key": "Your Partner Key ","filters": {"time": {"start_time": 1706630400000,"end_time": 1706716799000},"amount": {"upper_limit": 1000,"lower_limit": 0},"cardholder": {"phone_number": "0912345678","name": "Tester","email": "Tester@cherricorp.com"},"merchant_id": ["MID1","MID2"],
18

TapPay – ATM 虛擬帳號轉帳產品文件"record_status": 0,"rec_trade_id": "VA20240216p1OWOZ","order_number": "B12345678","bank_transaction_id": "12345678"},"order_by": {"attribute": "time","is_descending": true}}'
4.3.5 Response Body
名稱Status型別(長度)int說明
交易代碼
2 的話代表在當前過濾條件內，已無
更多紀錄

Msg

String

交易訊息

records_per_pag
e
Page

int

每頁的交易數量，最大為 200

int

第幾頁交易

total_page_count int

總頁數

number_of_trans longactions
trade_records
JSONArray

總交易筆數

名稱
rec_trade_id

型別(長度)
String(20)

交易紀錄說明TapPay 交易紀錄識別碼

auth_code

String(6)銀行授權碼merchant_id

String(50)

於 Portal 登錄
商家時所產生的識別碼。

merchant_name

String(50)

商家名稱

app_name

String

App 或網站名
稱

time

long

交易時間

amountint

交易金額，已扣
除退款金額

refunded_amount

int

退款金額
19

TapPay – ATM 虛擬帳號轉帳產品文件

record_status

int

交易狀態

bank_transaction_id

String

銀行端訂單編號

cap_millislong

交易會被請款的
時間

original_amountint

原始交易金額bank_transaction_sta longrt_millis

銀行實際交易時

bank_transaction_end_millislong

銀行實際結束時

is_captured

boolean是否已請款

bank_result_code

String(40)

銀行回傳的交易間
間

結果代碼
bank_result_msg

String(300)

銀行回傳的交易
結果訊息

partial_card_number

String卡號的前六碼與
後四碼。ATM轉帳回傳空字串

payment_method

String付款方式
direct_pay
apple_pay
google_pay_tokengoogle_pay_fpan
samsung_pay
line_pay
sp_tokenjko_payeasy_walletatome
pi_wallet
plus_payatm

details

String

交易品項內容cardholder

JSONObject

消費者資料

名稱

型別(長

說明

度)

20

TapPay – ATM 虛擬帳號轉帳產品文件

phone_number

String(4
0)

消費
者電
話

name

String(4
0)

消費
者姓
名

email

String(4
0)

消費
者信
箱

zip_code
addressnational_id

member_id

String(40)

郵遞String(90)
String(40)

地址String(6
4)

區號

身份
證字
號
ATM
轉帳
回傳
空字

bank_member_id

String(5
0)

串
ATM
轉帳
回傳
空字
串

currency

String

此筆交易幣別three_domain_secureboolean

是否為 3D 驗
證交易，ATM轉帳為 false

pay_by_instalment

boolean

是否為分期付款，ATM 轉帳為 false21

TapPay – ATM 虛擬帳號轉帳產品文件

order_number

String

商戶自行定義的訂單編號pay_info

JSONObject

付款資訊

名稱

型別(長

payment_time

度)
String(2
0)

說明
付款
時
間，
格式
yyyymmdd
hh:mi:
ss

payer_bank_code

String(5
)

付款
銀行
機構
代碼

payer_account_last_f String(1
ive
6)

付款
銀行
帳號
後五
碼

credit_card

int

使用
信用
卡支
付金
額。
ATM
轉帳
回傳
0

balance

int

使用
錢包
儲值
22

TapPay – ATM 虛擬帳號轉帳產品文件

帳戶
支付
金
額。
ATM
轉帳
回傳
0
bank_account

int

使用
銀行
連結
帳戶
支付
金
額。
ATM
轉帳
回傳
0

point

int

折抵
金
額。
ATM
轉帳

discount

int

回傳
0
LINE
Pay
折扣
碼折
抵金
額。
ATM
轉帳
回傳
0
23

TapPay – ATM 虛擬帳號轉帳產品文件

payee_info

JSONObject

繳費資訊

名稱

型別

說明

expire_time(長度)String(
20)

繳費
截止
時
間，
格式
yyyymm-dd
hh:mi:
ss

vacc_bank_code

String(
5)

繳費
金融
代碼

vacc_noString(
16)

繳費
虛擬
帳號

pay_by_redeem

boolean

是否為紅利折抵
交易，ATM 轉
帳為 false

kyc_info

JSONObject

KYC 驗證資訊

名稱

型別

說明

is_kyc_verified(長度)
Boolea
n

是否有
做
KYC
驗證，
ATM
轉帳為
false

kyc_verification_mer String
chant_id

執行
KYC
驗證的
merchant id，
24

TapPay – ATM 虛擬帳號轉帳產品文件

ATM
轉帳回
傳空字
串
card_identifier

String

信用卡識別碼，ATM 轉帳回傳
空字串

is_rba_verified

Boolean

該交易有無取得
RBA 評估的風
險分數 RBA，
ATM 轉帳為false

25

TapPay – ATM 虛擬帳號轉帳產品文件

4.3.6 Response Example{"msg": "End of list","records_per_page": 50,"total_page_count": 1,"number_of_transactions": 1,"page": 0,"trade_records": [{"rec_trade_id": "VA20240131WoZbcy","pay_info": {"payer_bank_code": "004","credit_card": 0,"balance": 0,"masked_credit_card_number": "","payment_time": "2024-01-31 17:05:32","discount": 0,"payer_account_last_five": "29637","point": 0,"bank_account": 0},"record_status": 1,"order_number": "","merchant_id": "ATM MID ","is_rba_verified": false,"cap_millis": 0,"original_amount": 30,"details": "Natalie test","currency": "TWD","partial_card_number": "","payee_info": {"vacc_no": "9259624010016050","expire_time": "2024-02-07 23:59:59","vacc_bank_code": "822"},"three_domain_secure": false,"payment_method": "atm","bank_transaction_start_millis": 1706691924123,"bank_result_code": "SUCCESS","bank_result_msg": "","amount": 30,"bank_transaction_id": "TP20240131WoZbcy","pay_by_instalment": false,"merchant_name": "TEST","is_captured": true,"bank_transaction_end_millis": 1706691926697,"cardholder": {"national_id": "A123456789","member_id": "","address": "台北市天龍區芝麻街 1 號 1 樓",
26

TapPay – ATM 虛擬帳號轉帳產品文件"bank_member_id": "","name": "王小明","phone_number": "0934567890","email": "LittleMing@Wang.com","zip_code": "100"},"auth_code": "","refunded_amount": 0,"app_name": "test","kyc_info": {"is_kyc_verified": false,"kyc_verification_merchant_id": ""},"time": 1706691924079,"pay_by_redeem": false,"card_identifier": ""}],"status": 2}27

TapPay – ATM 虛擬帳號轉帳產品文件

4.4 Trade History
4.4.1 Request Type & URL
Product Request
https://prod.tappaysdk.com/tpc/transaction/trade-history
URL
Sandbox Request
https://sandbox.tappaysdk.com/tpc/transaction/tradeURL
history
4.4.2 Request Header
x-api-key
Your Partner Key
Content-Typeapplication/json
4.4.3 Request Body
名稱(* = 必填) 型別(長度) 說明
partner_key*
String(64) 綁定 Portal 帳戶的驗證金鑰
rec_trade_id*
String(20) TapPay 交易紀錄識別碼
4.4.4 Request Example
curl --location ' https://prod.tappaysdk.com/tpc/transaction/trade-history' \--header 'x-api-key: Your Partner Key \--header 'Content-Type: application/json' \--data '{"partner_key": " Your Partner Key ","rec_trade_id": "VA20240131WoZbcy"}'

28

TapPay – ATM 虛擬帳號轉帳產品文件

4.4.5 Response Body
名稱status型別(長度)
int

說明

msg

String

交易訊息

rec_trade_id

String(20)TapPay 交易紀錄識別碼currencyint

貨幣種類(ISO 4217)。

trade_history JSONArray

交易代碼，，成功的話為 0

交易歷史紀錄

名稱
amount型別(長度)
int說明

action

int

交易狀態

交易金額
0 授權
1 請款
3 退款
4 待付款
5 取消
6 取消退款

millislong觸發該狀態的時
間

success

booleanbank_transaction_millis long該狀態是否成功
真實送到銀行進
行授權、請款、取消交易的時間

is_pending

Boolean當退款並未完成
前會回應 true，
已完成則會回傳
false

bank_result_code

String(40)

銀行回傳的交易結果代碼
授權與請款會顯
示實際從銀行拿
到的最新狀態。

bank_result_msg

String(300)

銀行回傳的交易
結果訊息
29

TapPay – ATM 虛擬帳號轉帳產品文件

授權與請款會顯
示實際從銀行拿
到的最新狀態。
4.4.6 Response Example{"status": 0,"msg": "Success","currency": "901","rec_trade_id": "VA20240131WoZbcy","trade_history": [{"action": 0,"millis": 1706691924079,"amount": 30,"success": true,"bank_transaction_millis": 1706691924123,"is_pending": false,"bank_result_code": "","bank_result_msg": ""},{"action": 1,"millis": 1706691932000,"amount": 30,"success": true,"bank_transaction_millis": 1706691932000,"is_pending": false,"bank_result_code": "SUCCESS","bank_result_msg": ""
}
]
}

30

TapPay – ATM 虛擬帳號轉帳產品文件

4.5 Reconciliation
4.5.1 Request Type & URL
Product Request
https://prod.tappaysdk.com/tpc/transaction/reconciliation
URL
Sandbox Request
https://sandbox.tappaysdk.com/tpc/transaction/reconciliation
URL
4.5.2 Request Header
x-api-key
Your Partner Key
Content-Typeapplication/json
4.5.3 Request Body
名稱(* = 必填)
partner_key*

型別(長度)
String說明

start_time_millis*

long

真實向銀行請退款的起始時間

end_time_millis*

long

真實向銀行請退款的結束時間

綁定 Portal 帳戶的驗證金鑰transaction_actions* StringArray 請款：CAPTURE
退款(意指請款後退款)：REFUND
records_per_page

int

每頁的交易數量，最大為 200 筆，預設為
50 筆

Page

int

merchant_ids

StringArray 於 Portal 登錄商家時所產生的識別碼。可第幾頁的交易，預設為 0
放多個 Merchant ID。
Merchant ID 與收單銀行只可擇一使用

acquirers

StringArray 收單銀行 / 金流處理器。可以放多個
acquirers
Merchant ID 與收單銀行只可擇一使用

4.5.4 Request Example
curl --location 'https://prod.tappaysdk.com/tpc/transaction/reconciliation' \--header 'x-api-key: Your Partner Key ' \--header 'Content-Type: application/json' \--data '{"partner_key": " Your Partner Key ","transaction_actions": ["CAPTURE","REFUND"],"start_time_millis": 1705248000000,"end_time_millis": 1706716800000,"merchant_ids":["TEST1"," TEST"]}'
31

TapPay – ATM 虛擬帳號轉帳產品文件

4.5.5 Response Body
名稱status型別(長度)int說明
交易代碼
2 的話代表在當前過濾條件內，已
無更多紀錄

msg

String

交易訊息

records_per_page

int

每頁的交易數量，最大為 200

page

int

第幾頁交易

total_page_count

int

總頁數

number_of_transact longions
reconciliation_datas JSONArray

總交易筆數

名稱
merchant_id

型別(長度)
String

每筆交易的請退款動作細節說明
於 Portal 登錄
商家時所產生merchant_descripti
onString的識別碼TapPay Portal
商家設定中的
Merchant 備註

acquirer

String收單銀行 / 金流處理器payment_method

String付款方式
direct_pay
apple_pay
google_pay_tok
engoogle_pay_fpansamsung_pay
line_pay
tsp_token
jko_payeasy_walletatome
pi_wallet
plus_payatm

rec_trade_id

StringTapPay 交易紀錄識別碼32TapPay – ATM 虛擬帳號轉帳產品文件

bank_transaction_idStringorder_number

String

銀行端的訂單
編號
商戶自行定義的訂單編號millislong觸發該狀態的時間

bank_transaction_
millislong

真實送到銀行
進行授權、請款、退款、取消退款的時
間。

transaction_action

String

交易操作
請款：
CAPTURE退款(意指請款後退款)：
REFUNDtransaction_result

Boolean

該狀態是否成功

trade_amount

int

請退款金額

auth_millis

long

商戶呼叫
TapPay API 進
行授權的時間

auth_amount

int

授權金額

currency

String

此筆交易幣別partial_card_numbe Stringr

卡號的前六碼
與後四碼，ATM 轉帳回傳
空字串

card_type

int

卡片種類
-1 = Unknown
1 = Visa
2 = MasterCard
3 = JCB33

TapPay – ATM 虛擬帳號轉帳產品文件

4 = Union Pay
5 = AMEX
auth_code

String銀行授權碼，
ATM 轉帳回傳
空字串

is_kyc_verified

Boolean

是否有做 KYC
驗證，ATM 轉
帳為 false

instalment_info

JSONObject

分期付款資
訊。

名稱

型別 說明
(長

度)
number_of_instalm int
ents

分期付
款期
數，
ATM 轉
帳回傳 0

redeem_info

JSONObject

使用紅利折抵
資訊

名稱

型別

說明

(長
offset_amount

度)
Strin
g

紅
利折抵
金額

pay_info

JSONObject

付款資訊

名稱

型別

說明

(長
credit_card

度)
int

使用信
用卡支
付金

34

TapPay – ATM 虛擬帳號轉帳產品文件

額。
ATN 轉
帳回傳
0
balance

int

使用錢
包儲值
帳戶支
付金
額。
ATN 轉
帳回傳
0

bank_account

int

使用銀
行連結
帳戶支
付金
額。
ATN 轉

point

int

帳回傳
0
LINE
Point,
街口幣,
全盈支
付折抵
金額。
ATN 轉

discount

int

帳回傳
0
LINE
Pay 折
扣碼折
抵金
額。
ATN 轉
35

TapPay – ATM 虛擬帳號轉帳產品文件

帳回傳
0
4.5.6 Response Example{"status": 2,"msg": "End of list","page": 0,"records_per_page": 50,"total_page_count": 1,"number_of_transactions": 5,"reconciliation_datas": [{"acquirer": "TapPay","millis": 1706691932000,"currency": "TWD","merchant_id": "ATM MID","merchant_description": "","payment_method": "atm","rec_trade_id": "VA20240131Wo4bcy","bank_transaction_id": "TP20240131WoZb6y","order_number": "","bank_transaction_millis": 1706691932000,"transaction_action": "CAPTURE","transaction_result": true,"trade_amount": 30,"auth_millis": 1706691924079,"auth_amount": 30,"partial_card_number": "","card_type": -1,"auth_code": "","is_kyc_verified": false,"instalment_info": {"number_of_instalments": 0},"redeem_info": {"offset_amount": "0"},"pay_info": {"balance": 0,"point": 0,"discount": 0,"credit_card": 0,"bank_account": 0
}
}
]
}

36

TapPay – ATM 虛擬帳號轉帳產品文件

4.6 Simulated Payment
4.6.1 Request Type & URL
Sandbox Request URL https://sandbox.tappaysdk.comtpc/simulate/paid
4.6.2 Request Header
x-api-key
Content-TypeYour Partner Key
application/json

4.6.3 Request Body
名稱(* = 必填) 型別(長度) 說明
partner_key
String(64) 綁定 Portal 帳戶的驗證金鑰
rec_trade_id
String(20) TapPay 交易紀錄識別碼
4.6.4 Request Example
curl --location ' https://sandbox.tappaysdk.comtpc/simulate/paid ' \--header 'x-api-key: Your Partner Key' \--header 'Content-Type: application/json' \--data '{"partner_key": " Your Partner Key ","rec_trade_id": "VA20240285nTGwfu"}'
4.6.5 Response Body
名稱 型別(長度) 說明
status int
交易代碼，成功為 0
msg
String
交易訊息

4.6.6 Response Example{"status": 0,"msg": "Success"}37

TapPay – ATM 虛擬帳號轉帳產品文件

5. Error Code
此為 ATM 轉帳新增的 Error code，完整 Error code 請見 TapPay 官網。
Error CodeError Msg
Remark9154
Invalid arguments :vacc_bank9155
Missing arguments :vacc_bank9156
Invalid argument :expire_in_days
9157
Out of range :繳費資訊有效天數為 1-7
expire_in_days
天962
Virtual accountATM 繳費期限已過
transaction is expired
9160
Out of range : amountATM 金額限制為 1649999 元

38