當你選擇使用Spiral交易網關,首先你應該開發Hosted Session流程, 該流程可以應用在所有的支付類型上。如果有需要, 可以再開發直接交易流程。

 

當使用Hosted Session,顧客的瀏覽器會被跳轉至新的頁面(或經由APP的SDK產生新的頁面),而該頁面是由支付供應商管理而不經由商戶控制,並處理輸入卡號,顯示支付碼等。這可以減低PCI對數據安全要求的開發成本。

 

Hosted Session有3個步驟:

Hosted-Session-Chi

步驟一:建立訂單

商戶的後台向Spiral網關發起交易的API訊息,當中包括交易資料(如金額及單號)及cmd設為SALESESSION或AUTHSESSION)。Spiral網關會返回會話ID(session ID)及相關資料。
會話ID(session ID)將在下一步驟用作處理交易。.

轉至 API 文檔
codeCreated with Sketch.

步驟二:在前端處理交易

獲取會話ID(session ID)之後,網頁應該調用Spiral的Javascript程式庫(或在APP調用提供的SDK程式庫)去進行支付程序。

當交易完成,程式庫會將頁面跳轉至商戶指定的完成版面(使用APP時,則返回結果給APP)。

轉至前端處理
WebhooksCreated with Sketch.

步驟三:接收交易結果通知

當交易完成,Spiral網關會發起通知(webhook)給商戶的後台。

如果Spiral未能收到商戶後台的確認(response code 200),則會在約兩小時內, 以大約15分鐘的間距重發。
如果商戶未能在正常時間下收到通知,可以發起查詢的API以取得交易結果。

轉至 API 文檔
  • 請只經由後台送出交易API

    而不要經由前端。因為API訊息是要使用密鑰簽署,而密鑰不應在前端部署。

  • 只相信webhook通知或是查詢API

    因為顧客可以中途關掉網頁甚至自行更改URL,所以通過前端的動作去判定交易結果是不安全的做法。

在相理交易時,使用一個有唯一性的ID去尋找和區別交易是非常重要的。這裏說明一下幾項交易ID的用法和關係。

商戶參考號 (merchantRef) – 這是由商戶自行設定,每筆交易也有不同值。如每同一個訂單下需要進行獲取/退款,需要一個與原來不同,新的商戶參考號值。
格式:最長25位, [A-Za-z0-9_-],最後三位不可以是’_’。

交易 ID (txnId) – 類似商戶參考號,但這是經由 Spiral 而不是商戶生成。

訂單 ID (orderId) – 同交易ID一樣是經由Spiral產生, 但在同一組訂單下的交易 (例如獲取/退款)都會擁有相同的訂單ID,而交易ID則有不同值。 進行獲取/退款時需要提供訂單ID去辦別原來訂單。

Hosted Session及直接交易兩種流程的不同使用場景:

直接交易

Hosted Session

  • 使用Spiral Tokens (信用卡)
  • 使用Apple Pay Tokens
  • 使用Google Pay Tokens
  • 退款
  • 獲取交易
  • 所有不使用tokens的銷售或授權