Spiral Checkout (1.0.1)

Download OpenAPI specification:Download

E-mail: support@eftsolutions.freshdesk.com

Spiral Checkout支付網關的API文檔

API Call (商戶 to Spiral)

由商戶向Spiral發出的API

交易行動

進行交易動作的API ,包括Sale銷售, SaleSession銷售對話, Auth授權, AuthSession授權對話, Capture交易獲取及 Refund退款

path Parameters
clientId
required
string
Example: merchantOne

由Spiral指發的賬戶號

merchantRef
required
string
Example: 1627965086558-1

交易參考號，必須要有惟一性。

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

使用ISO格式%Y-%m-%d'T'%H:%M:%S'Z'的UTC時間,
用來表示API請求/回覆的時間

Spiral-Client-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

客戶端的簽署

Request Body schema: application/json
One of
clientId
required
string

由Spiral指發的賬戶號

merchantRef
required
string

交易參考號，必須要有惟一性。

cmd
required
string

交易行動的類別, Sale銷售, SaleSession銷售對話, Auth授權, AuthSession授權對話

type
required
string

交易類型, 例如 VM, FPS, Alipay, WeChat Pay

amt
required
number

交易金額

goodsName
required
string

貨品名稱

goodsDesc
string

貨品描述

channel
string

付款渠道（APP或WEB）

cardToken
string

卡號代碼，代替卡號進行交易，僅限直接交易時使用。需要同時提供cardTokenSrc。

cardTokenSrc
string

信用卡代碼的來源可以是SPIRAL, APPLE_PAY, GOOGLE_PAY

successUrl
string <uri>

付款完成後要在瀏覽器上重定向的頁面

failureUrl
required
string <uri>

付款失敗或取消時要在瀏覽器上重定向的頁面

webhookUrl
required
string <uri>

付款結果通知地址

duration
number

qrCode有效的天數（應僅通過郵件發送的轉數快FPS賬單付款使用）

Responses

Request samples

Content type
application/json
Example
saleRequest
saleRequest
captureRequest
refundRequest
{}

Response samples

Content type
application/json
Example
transactionResponse
transactionResponse
failureResponse
{
  • "clientId": "testAccount",
  • "merchantRef": "Order-1001",
  • "cmd": "SALE",
  • "orderId": "0c170aa0-7c5a-4b32-9529-102aaa454f51",
  • "type": "VM",
  • "txnId": "5fe3368b-453a-4cc1-81f1-4c2054cb4ca4",
  • "merchantId": "H345678H3620000",
  • "hostId": "1",
  • "card": "VISA",
  • "status": "Approved",
  • "amt": 100.5,
  • "resp": "APPROVED",
  • "hostTime": "2021-02-03T09:29:09.000Z",
  • "appCode": "123456",
  • "pan": "444000xxxxxx0010",
  • "expDate": "1027",
  • "respMsg": "ok",
  • "goodsName": "Sunmi T2 Lite",
  • "goodsDesc": "Electronic product",
  • "cardToken": 5544111234567890,
  • "cardTokenSrc": "SPIRAL",
  • "paidAmt": 100.5,
  • "orderAmt": 100.5,
  • "sessionId": "MPGSSESSION0002469410891M8961272I40",
  • "qrCode": "00020101021226490012hk.com.hkicl0313+852-64232435051221010812495052040000530334454040.805802HK5902NA6002HK62100506WC-15163042A3C"
}

交易查詢

用作查詢交易狀態的API

path Parameters
clientId
required
string
Example: merchantOne

由Spiral指發的賬戶號

merchantRef
required
string
Example: 1627965086558-1

交易參考號，必須要有惟一性。

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

使用ISO格式%Y-%m-%d'T'%H:%M:%S'Z'的UTC時間,
用來表示API請求/回覆的時間

Spiral-Client-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

客戶端的簽署

Responses

Response samples

Content type
application/json
Example
transactionResponse
transactionResponse
failureResponse
{
  • "clientId": "testAccount",
  • "merchantRef": "Order-1001",
  • "cmd": "SALE",
  • "orderId": "0c170aa0-7c5a-4b32-9529-102aaa454f51",
  • "type": "VM",
  • "txnId": "5fe3368b-453a-4cc1-81f1-4c2054cb4ca4",
  • "merchantId": "H345678H3620000",
  • "hostId": "1",
  • "card": "VISA",
  • "status": "Approved",
  • "amt": 100.5,
  • "resp": "APPROVED",
  • "hostTime": "2021-02-03T09:29:09.000Z",
  • "appCode": "123456",
  • "pan": "444000xxxxxx0010",
  • "expDate": "1027",
  • "respMsg": "ok",
  • "goodsName": "Sunmi T2 Lite",
  • "goodsDesc": "Electronic product",
  • "cardToken": 5544111234567890,
  • "cardTokenSrc": "SPIRAL",
  • "paidAmt": 100.5,
  • "orderAmt": 100.5,
  • "sessionId": "MPGSSESSION0002469410891M8961272I40",
  • "qrCode": "00020101021226490012hk.com.hkicl0313+852-64232435051221010812495052040000530334454040.805802HK5902NA6002HK62100506WC-15163042A3C"
}

產生交易鏈結

由網關產生交易鏈結的API

path Parameters
clientId
required
string
Example: merchantOne

由Spiral指發的賬戶號

merchantRef
required
string
Example: 1627965086558-1

交易參考號，必須要有惟一性。

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

使用ISO格式%Y-%m-%d'T'%H:%M:%S'Z'的UTC時間,
用來表示API請求/回覆的時間

Spiral-Client-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

客戶端的簽署

Request Body schema: application/json
clientId
required
string

由Spiral指發的賬戶號

merchantRef
required
string

交易參考號，必須要有惟一性。

amt
required
number

交易金額

goodsName
required
string

貨品名稱

goodsDesc
string

貨品描述

webhookUrl
required
string <uri>

付款結果通知地址

durationHr
required
number

qrCode有效的時數

Responses

Request samples

Content type
application/json
{
  • "clientId": "merchantOne",
  • "merchantRef": "Order-1001",
  • "amt": 100.5,
  • "goodsName": "Sunmi T2 Lite",
  • "goodsDesc": "Electronic product",
  • "webhookUrl": "https://www.merchantsite.com/webhook",
  • "durationHr": 24
}

Response samples

Content type
application/json
Example
transactionResponse
transactionResponse
failureResponse
{
  • "clientId": "testAccount",
  • "merchantRef": "Order-1001",
  • "cmd": "SALE",
  • "orderId": "0c170aa0-7c5a-4b32-9529-102aaa454f51",
  • "type": "VM",
  • "txnId": "5fe3368b-453a-4cc1-81f1-4c2054cb4ca4",
  • "merchantId": "H345678H3620000",
  • "hostId": "1",
  • "card": "VISA",
  • "status": "Approved",
  • "amt": 100.5,
  • "resp": "APPROVED",
  • "hostTime": "2021-02-03T09:29:09.000Z",
  • "appCode": "123456",
  • "pan": "444000xxxxxx0010",
  • "expDate": "1027",
  • "respMsg": "ok",
  • "goodsName": "Sunmi T2 Lite",
  • "goodsDesc": "Electronic product",
  • "cardToken": 5544111234567890,
  • "cardTokenSrc": "SPIRAL",
  • "paidAmt": 100.5,
  • "orderAmt": 100.5,
  • "sessionId": "MPGSSESSION0002469410891M8961272I40",
  • "qrCode": "00020101021226490012hk.com.hkicl0313+852-64232435051221010812495052040000530334454040.805802HK5902NA6002HK62100506WC-15163042A3C"
}

交易鏈結查詢

查詢交易鏈結結果的API

path Parameters
clientId
required
string
Example: merchantOne

由Spiral指發的賬戶號

merchantRef
required
string
Example: 1627965086558-1

交易參考號，必須要有惟一性。

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

使用ISO格式%Y-%m-%d'T'%H:%M:%S'Z'的UTC時間,
用來表示API請求/回覆的時間

Spiral-Client-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

客戶端的簽署

Responses

Response samples

Content type
application/json
Example
transactionResponse
transactionResponse
failureResponse
{
  • "clientId": "testAccount",
  • "merchantRef": "Order-1001",
  • "cmd": "SALE",
  • "orderId": "0c170aa0-7c5a-4b32-9529-102aaa454f51",
  • "type": "VM",
  • "txnId": "5fe3368b-453a-4cc1-81f1-4c2054cb4ca4",
  • "merchantId": "H345678H3620000",
  • "hostId": "1",
  • "card": "VISA",
  • "status": "Approved",
  • "amt": 100.5,
  • "resp": "APPROVED",
  • "hostTime": "2021-02-03T09:29:09.000Z",
  • "appCode": "123456",
  • "pan": "444000xxxxxx0010",
  • "expDate": "1027",
  • "respMsg": "ok",
  • "goodsName": "Sunmi T2 Lite",
  • "goodsDesc": "Electronic product",
  • "cardToken": 5544111234567890,
  • "cardTokenSrc": "SPIRAL",
  • "paidAmt": 100.5,
  • "orderAmt": 100.5,
  • "sessionId": "MPGSSESSION0002469410891M8961272I40",
  • "qrCode": "00020101021226490012hk.com.hkicl0313+852-64232435051221010812495052040000530334454040.805802HK5902NA6002HK62100506WC-15163042A3C"
}

Webhook (Spiral to 商戶)

Spiral向商戶發出的結果通知

交易通知

通知商戶交易結果的Webhook

path Parameters
successUrl
required
string

在銷售請求提供的URL

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

使用ISO格式%Y-%m-%d'T'%H:%M:%S'Z'的UTC時間,
用來表示API請求/回覆的時間

Spiral-Server-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

Spiral伺服器的簽署

Request Body schema: application/json
clientId
required
string

由Spiral指發的賬戶號

merchantRef
required
string

交易參考號，必須要有惟一性。

cmd
required
string

交易行動的類別

orderId
required
string <uuid>

由Spiral產生的訂單參考號

type
required
string

交易類型, 例如VM, FPS, Alipay, WeChat Pay

txnId
required
string <uuid>

由Spiral產生的交易參考號, 如果對銷售交易進行退款等後續動作，則orderID相同而txnID不同

merchantId
required
string

付款帳戶的商家ID, 單個clientId可以有複數的merchantId

hostId
required
string

主機ID可以在商戶網頁平台中找到

card
string

付款卡類型，例如VISA, MASTERCARD等等

status
required
string

交易狀況
Approved- 交易成功
Declined- 交易被拒絕
CommError- 通訊故障
FormatError- 格式錯誤
NotSupported- 不支持的功能或卡類
NotValid- 數據值無效
Timeout- 輸入超時
AlreadyVoided- 交易已撤銷
Unconfirmed- 交易未確定或未能穫得主機回應
Unauthenticated- 未能通過認證
Cancelled- 交易取消
PartialPaid- 只支付部份金額(只用於轉數快)
OverPaid- 支付金額多於原本金額(只用於轉數快)

amt
required
number

交易金額

resp
string

付款處理商的回應碼

hostTime
required
string <date-time>

付款系統的交易時間

appCode
string

授權碼

pan
string

卡號以遮蔽格式顯示

expDate
string

到期日。以遮蔽格式顯示

respMsg
string

支付系統的回應信息

goodsName
string

貨品名稱 (SALE/SALESESSION/AUTH/AUTHSESSION必要)

goodsDesc
string

貨品描述

cardToken
string

卡號代碼，代替卡號進行交易，僅限直接交易時使用。需要同時提供cardTokenSrc。

cardTokenSrc
string

信用卡代碼的來源可以是SPIRAL, APPLE_PAY, GOOGLE_PAY

paidAmt
required
number

已支付的金額（除轉數快FPS外，應與amt相同）

orderAmt
number

已為此訂單支付的總金額，僅適用於轉數快FPS

sessionId
string

會話ID，僅在Hosted Session流程中使用(SALESESSION/AUTHSESSION)

qrCode
string

用於在網頁或APP（用於轉數快FPS）中顯示的QR碼

Responses

Request samples

Content type
application/json
{
  • "clientId": "testAccount",
  • "merchantRef": "Order-1001",
  • "cmd": "SALE",
  • "orderId": "0c170aa0-7c5a-4b32-9529-102aaa454f51",
  • "type": "VM",
  • "txnId": "5fe3368b-453a-4cc1-81f1-4c2054cb4ca4",
  • "merchantId": "H345678H3620000",
  • "hostId": "1",
  • "card": "VISA",
  • "status": "Approved",
  • "amt": 100.5,
  • "resp": "APPROVED",
  • "hostTime": "2021-02-03T09:29:09.000Z",
  • "appCode": "123456",
  • "pan": "444000xxxxxx0010",
  • "expDate": "1027",
  • "respMsg": "ok",
  • "goodsName": "Sunmi T2 Lite",
  • "goodsDesc": "Electronic product",
  • "cardToken": 5544111234567890,
  • "cardTokenSrc": "SPIRAL",
  • "paidAmt": 100.5,
  • "orderAmt": 100.5,
  • "sessionId": "MPGSSESSION0002469410891M8961272I40",
  • "qrCode": "00020101021226490012hk.com.hkicl0313+852-64232435051221010812495052040000530334454040.805802HK5902NA6002HK62100506WC-15163042A3C"
}

交易鏈結結果通知

通知商戶交易鏈結結果的Webhook

path Parameters
successUrl
required
string

在銷售請求提供的URL

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

使用ISO格式%Y-%m-%d'T'%H:%M:%S'Z'的UTC時間,
用來表示API請求/回覆的時間

Spiral-Server-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

Spiral伺服器的簽署

Request Body schema: application/json
clientId
required
string

由Spiral指發的賬戶號

merchantRef
required
string

交易參考號，必須要有惟一性。

approvedTxnId
required
string

在此交易鏈結下成功交易的txnId

status
required
string

交易狀況
Approved- 交易成功
Declined- 交易被拒絕
CommError- 通訊故障
FormatError- 格式錯誤
NotSupported- 不支持的功能或卡類
NotValid- 數據值無效
Timeout- 輸入超時
AlreadyVoided- 交易已撤銷
Unconfirmed- 交易未確定或未能穫得主機回應
Unauthenticated- 未能通過認證
Cancelled- 交易取消
PartialPaid- 只支付部份金額(只用於轉數快)
OverPaid- 支付金額多於原本金額(只用於轉數快)

amt
required
number

交易金額

paymentLinkUrl
required
string

交易鏈結的URL

Responses

Request samples

Content type
application/json
{}