JiaoPay Service Integration Doc

Version: 3.3.4

Prerequisite

Before starting service integration, we should contact with service manager to ensure below things already finished:

• Get companyId from email, which 8 chars long
• Get API Domain from email
• Get API KEY from email
• Get Validate KEY from email, which 25 chars long
• Set the Webhook urls which describe in webhooks section
  • virtualAccountCreatedCallbackUrlV3 (only accept https endpoint)
  • convenienceStorePayCodeCreatedCallbackUrlV3 (only accept https endpoint)
  • paymentCallbackUrlV3 (only accept https endpoint)

Global Config

• Request
  • Content-Type: application/json
• Response
  • Content-Type: application/json
• webhooks
  • After received webhook request event, please response “success” string, and JiaoPay will know client already received the event successfully.

Transaction Type & Details

目前可以建立交易的種類包含以下7種：

1. 虛擬帳號
2. 信用卡
3. Google Pay
4. Apple Pay
5. Union Pay (銀聯卡支付)
6. LINE Pay
7. PayPal
8. ConvenienceStore (超商代碼)
9. AliPay (支付寶)

交易種類	適用地區與範圍	交易金額限制	備註
虛擬帳號	僅限台灣	由於銀行洗錢防制法的關係，單筆最高交易金額為49999元，當日無金額上限	非台灣玩家能夠產生虛擬帳號，但是銀行端只接受台灣的銀行帳戶將款項轉入虛擬帳號
信用卡	全球通用	單卡單筆最高199999元	只支援Visa、MasterCard、JCB
Google Pay	全球通用	單卡單筆最高199999元	除了銀聯卡以外，其他信用卡都支援
Apple Pay	全球通用	單卡單筆最高199999元	除了銀聯卡以外，其他信用卡都支援
Union Pay	全球通用	單卡單筆最高199999元	只支援銀聯卡
LINE Pay	僅限台灣	最高消費金額即為使用者的信用卡當下最高可消費額度	只有台灣的LINE Pay帳號能夠透過LINE Pay服務進行交易
PayPal	全球通用	依照使用者信用卡額度/帳戶儲值金額	只支援PayPal交易
超商代碼	僅限台灣	單筆最低金額30元，最高金額20000元	只接受台灣超商繳費，目前只支援7-11
支付寶	僅限中國(不含港澳)	單筆最低1元台幣，最高金額約8200台幣(2000人民幣)	建立訂單時以台幣進行交易，JiaoPay將會根據我方實時匯率轉換為人民幣，讓使用者於支付寶進行人民幣付款

Sequence Diagram

交易流程分為以下2種情況
A. 一般交易，包含信用卡、Google Pay、Apple Pay、LINE Pay、Union Pay、PayPal、支付寶(AliPay)
B. 非同步交易：包含虛擬帳號(VirtualAccount)、超商代碼(ConvenienceStore)交易

一般交易

非同步交易

API Response / Webhook Request Format

JiaoPay using a simple, basic format to do data transfer, no matter business logic running success or got error, JiaoPay always send data to client with HTTP Status Code 200.

Non-error json data example (success response/request)

{
 statusCode: '00000', // statusCode, 00000 means sucess
 statusMessage: 'OK', // information about the status code
 timestamp: 1653279278123, // current timestamp
 data: {
   ...
 }, // data will be the payload object when success
}

Error json data example (error response/request)

{
 statusCode: 'API00001', // statusCode not 00000 means error
 statusMessage: 'COMPANY_NOT_FOUND', // information about the status code
 timestamp: 1653279278123, // current timestamp
 data: null // data will be null when error
}

APIs

POST /api/v3/payment

透過這個endpoint可以建立所有類型的交易，交易類型包含：

1. 虛擬帳號 (VirtualAccount)
2. 信用卡
3. Google Pay
4. Apple Pay
5. Union Pay (銀聯卡支付)
6. LINE Pay
7. PayPal
8. 超商代碼 (ConvenienceStore)
9. 支付寶 (AliPay)

Request

Query Params

parameter name	is require	type	description
key	✅	string	The api auth key.

Body (json format)

attribute name	is require	type	description
CompanyID	✅	string	公司代號，長度 8 為個字元
MerTradeID	✅	string	店家交易 ID，交易編號是 global unique 的數字與英文字母的組合，不能重複。另外，MerTradeID 總長度最少 5 個字元，最多 32 個字元。
MerProductID	✅	string	店家商品 ID，店家自行設定，長度 1~40 個字元，僅限數字與英文字母，以及「-」、「.」、「_」的組合。
MerProdDesc	✅	string	店家商品敘述，長度 1 ~ 500 個字元
MerUserID	✅	string	店家消費者 ID，店家自行設定，限數字與英文字母的組合，長度 1~40 個字元。
Amount	✅	string	如果PaymentType 是 PayPal，交易金額為「美金」數字字串，支援小數點以下2位，如果是其他交易，交易金額為「台幣」數字字串，不能有小數點和千分位，除了AliPay 單筆交易最低金額為台幣1元以外，其餘都是單筆最低交易金額是台幣 15 元，詳細限制如下
PaymentType	✅	string	根據交易類別，對應所要傳入的值為 VirtualAccount/CreditCard/GooglePay/ApplePay/UnionPay/LinePay/PayPal/ConvenienceStore
BackURL	optional	string	在付款結果頁/取得虛擬帳號頁面會顯示「返回商店按鈕」，使用者點擊後會將頁面導去此網址，網址必須以https://開頭
UserMail	optional	string	使用者的電子郵件地址，長度限制在 200 個字元以內，格式必須是有效的 email 格式。這個欄位是可選的，但如果提供，將會在付款頁面被預先填入。

Example:

台幣交易：

{
 CompanyID: 'abcdefgh',
 MerTradeID: 'traderId12345678',
 MerProductID: 'product1',
 MerProdDesc: '小明奶奶養的烏龜',
 MerUserID: 'testuser1',
 Amount: '12345',
 PaymentType: 'GooglePay',
 BackURL: 'https://google.com/shop'
}

美金交易：

{
 CompanyID: 'abcdefgh',
 MerTradeID: 'traderId12345678',
 MerProductID: 'product1',
 MerProdDesc: '小明奶奶養的烏龜',
 MerUserID: 'testuser1',
 Amount: '12345.12',
 PaymentType: 'PayPal',
 BackURL: 'https://google.com/shop'
}

Response

Attributes

attribute name	always include	type	description
code	✅	string	建立虛擬帳號授權碼

Example:

{
 statusCode: '00000',
 statusMessage: 'OK',
 timestamp: 1653279278123,
 data: {
  code: 'U2FsdGVkX1%2FuA7s3wB%2FN...lMXeMjW%2BrSjHj'
 }
}

取得code之後，將使用者的瀏覽頁面導去以下的網址(範例)

https://{domain}/payment-universal?code=U2FsdGVkX1%2FuA7s3wB%2FN...lMXeMjW%2BrSjHj

Beta環境各類型交易測試方式：

1. 虛擬帳號 (VirtualAccount)

• 建立虛擬帳號後會自動觸發virtualAccountCreatedCallbackUrlV3 webhook
• 需要觸發虛擬帳號交易完成的事件，請聯絡技術窗口，技術窗口將協助手動觸發paymentCallbackUrlV3 webhook

2. 信用卡

• 請用測試卡，卡號4147631000000001 ，卡片到期日及背面末三碼可任意填入
• 交易完成後會自動觸發 paymentCallbackUrlV3 webhook

3. Google Pay

• 請在PC瀏覽器/有安裝Google Pay的手機上使用一般瀏覽器開啟交易頁面
• 在交易頁面中填寫完成表單並送出，將會跳去Google Pay支付介面
• 選擇任意一張卡片，交易會直接完成，並且不會真正扣款
• 交易完成後會自動觸發 paymentCallbackUrlV3 webhook

4. Apple Pay

• 請在iPhone/iPad，或是支援Apple Pay的裝置上使用一般瀏覽器開啟交易頁面
• 在交易頁面中填寫完成表單並送出，將會跳去Apple Pay支付介面
• 選擇任意一張卡片，交易會直接完成，並且不會真正扣款
• 交易完成後會自動觸發 paymentCallbackUrlV3 webhook

5. LINE Pay

• 在交易頁面中填寫完成表單並送出後會直接完成，並且不會真正扣款
• 交易完成後會自動觸發 paymentCallbackUrlV3 webhook

6. Union Pay (銀聯卡支付)

• 在交易頁面中填寫完成表單並送出後會直接完成，並且不會真正扣款
• 交易完成後會自動觸發 paymentCallbackUrlV3 webhook

7. PayPal

• 請使用PayPal Sandbox帳號綁定信用卡進行支付，詳細資訊可以參考PayPal sandbox testing guide
• 交易完成後會自動觸發 paymentCallbackUrlV3 webhook

8. 超商代碼 (ConvenienceStore)

• 建立超商代碼後會自動觸發convenienceStorePayCodeCreatedCallbackUrlV3 webhook
• 需要觸發超商代碼完成的事件，請聯絡技術窗口，技術窗口將協助手動觸發paymentCallbackUrlV3 webhook

9. 支付寶 (AliPay)

• 請向技術窗口索取測試用帳號
• 在交易頁面中填寫完成表單並送出後會直接完成
• 交易完成後會自動觸發 paymentCallbackUrlV3 webhook

Webhooks

virtualAccountCreatedCallbackUrlV3

當虛擬帳號成功建立之後，JiaoPay會對這個webhook發起request，將虛擬帳號建立成功的資料傳過去

Request

attribute name	always include	type	description
MerTradeID	✅	string	店家交易ID
MerProductID	✅	string	店家商品ID
MerUserID	✅	string	店家消費者ID
Amount	✅	string	交易金額
BankCode	✅	string	銀行代碼
BankName	✅	string	銀行名稱
VirtualAccount	✅	string	銀行虛擬帳戶轉帳帳號
ExpireDateTime	✅	string	付款截止日期，格式為YYYY-MM-DD HH:mm:ss，該時間過後虛擬帳號將會過期，過期之後該筆虛擬帳號不論是否有匯入款項、款項是否正確，交易都不會成功
Validate	✅	string	檢查碼，詳細內容請參閱Transaction Validation

虛擬帳號建立成功的Request範例:

{
 statusCode: '00000',
 statusMessage: 'OK',
 timestamp: 1653279278123,
 data: {
  MerTradeID:  'traderId12345678',
  MerProductID:  'product1',
  MerUserID:  'testuser1',
  Amount:  '12345',
  BankCode:  '013',
  BankName:  '國泰世華',
  VirtualAccount:  '12345678123456',
  ExpireDateTime:  '2023-11-27 23:11:54',
  Validate:  '00a478ce72d0a7206c9ae1b250e4672d'
}

convenienceStorePayCodeCreatedCallbackUrlV3

當超商代碼成功建立之後，JiaoPay會對這個webhook發起request，將超商代碼建立成功的資料傳過去

超商代碼建立成功的Request範例:

Request

attribute name	always include	type	description
MerTradeID	✅	string	店家交易ID
MerProductID	✅	string	店家商品ID
MerUserID	✅	string	店家消費者ID
Amount	✅	string	交易金額
StoreType	✅	string	超商類別
PayCode	✅	string	超商代碼
ExpireDateTime	✅	string	付款截止日期，格式為YYYY-MM-DD HH:mm:ss，該時間過後超商代碼將會過期，過期之後該筆超商代碼無法繳費
Validate	✅	string	檢查碼，詳細內容請參閱Transaction Validation

{
 statusCode: '00000',
 statusMessage: 'OK',
 timestamp: 1752247086765,
 data: {
  MerTradeID:  'cvspay123456731',
  MerProductID:  'devproduct',
  MerUserID:  'devuser',
  Amount:  '30',
  StoreType:  'SEVEN',
  PayCode:  'T00040035476',
  ExpireDateTime:  '2025-07-18 23:59:59',
  Validate:  '7208f974911587f4d2299dea21fe8505296ba8dd914ef348aadfc50442444f8bb5905b1c081c011db049808f34351a94'
}

Response

如果收到了Request，請回傳 success 字串(Plain Text)，告知JiaoPay客戶端已經成功接收

paymentCallbackUrlV3

當交易成功之後，JiaoPay會對這個webhook發起request，將交易成功的資料傳過去

This callback will be call only after user paid successfully.

Request

attribute name	always include	type	description
MerTradeID	✅	string	店家交易ID
MerProductID	✅	string	店家商品ID
MerUserID	✅	string	店家消費者ID
Amount	✅	string	交易金額
PaymentType	✅	string	根據交易類別，會收到的值為 VirtualAccount/CreditCard/GooglePay/ApplePay/LinePay擇一
PayDateTime	✅	string	付款日期，格式為YYYY-MM-DD HH:mm:ss
Validate	✅	string	檢查碼，詳細內容請參閱Transaction Validation

交易成功的Request範例:

{
 statusCode: '00000',
 statusMessage: 'OK',
 timestamp: 1653279278123,
 data: {
  MerTradeID:  'test12345678901234567890',
  MerProductID:  'testproduct1',
  MerUserID:  'testuser1',
  Amount:  '123',
  PaymentType:  'GooglePay',
  PayDateTime:  '2024-01-17 18:33:11',
     Validate:  '00a478ce72d0a7206c9ae1b250e4672d'
 }
}

Response

如果收到了Request，請回傳 success 字串(Plain Text)，告知JiaoPay client已經成功接收

Errors

API Auth Error

Invalid API Key

{
 "code": 400,
 "message": "INVALID_ARGUMENT:API key not valid. Please pass a valid API key."
}

Unauthenticated Method

{
 "code": 401,
 "message": "UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API."
}

API EndPoint Not Found

{
 "code": 404,
 "message": "The current request is not defined by this API."
}

API / Webhook Error

StatusCode	StatusMessage	description
40001	REQUEST_CONTENT_INVALID	request payload 缺少必要參數、多給參數或是參數型別錯誤
50001	COMPANY_NOT_FOUND	無法透過提供的資訊找到對應的Company
50002	COMPANY_CALLBACK_URL_INVALID	Company callback url應該要是https開頭的網址
60001	TRANSACTION_NOT_FOUND	無法透過提供的資訊找到對應的Transaction
60002	TRANSACTION_INVALID	交易驗證未通過
70001	SERVICE_ERROR	系統錯誤，如果遇到請聯絡服務管理員
80001	NETWORK_ERROR	系統網路傳輸錯誤，如果遇到請聯絡服務管理員

Notes

Transaction Validation

交易檢查碼驗證方式

1. 檢查碼使用SHA384進行編碼
2. 驗證時請注意英文字母大小寫比對
3. v3.0.0之後，CompanyId改為CompanyID

SHA384(ValidateKey=商家驗證碼&CompanyID=店家ID&MerTradeID=店家交易編號&MerProductID=店家產品編號&MerUserID=店家消費者ID&Amount=交易金額)

Javascript Example:

if(Validate.toUpperCase() === SHA384(ValidateKey=ABC&CompanyID=abcdefg&MerTradeID=testTradeId&MerProductID=testProductId&MerUserID=userId&Amount=123)toUpperCase()) {
  // valided transaction
}