如何通過 API 連接我的支付服務？

付款 API 僅適用於商務版方案。使用付款 API 時，每筆交易需支付 NT$8 的手續費。此費用將從您的 Bukza 帳戶餘額中扣除。

您可以透過付款 API 將任何支付服務連接到 Bukza。為此，您需要有自己的伺服器，作為 Bukza 與您的支付服務之間的中介。需要具備程式設計技能。

請注意，此 API 未來可能會有變動。

如何啟用 API？

若要啟用付款 API，請發送請求至 support@bukza.com。在您的訊息中，請註明 Bukza 應該發送請求的伺服器 URL。我們將提供您的使用者 ID 以及產生簽章雜湊所需的金鑰。

現成整合範例

您可以在線上程式碼編輯器這裡查看 JavaScript 原始碼範例。

若要使用您的帳戶測試此範例，請依下列步驟操作：

前往 Glitch 註冊帳戶。
在這裡按下 "Remix" 按鈕，建立我們整合範例的副本。這將建立一個擁有相同原始碼的專屬應用程式。
接著，在 Glitch 中開啟 TERMINAL，執行指令：npm ci。這會安裝所需的相依套件。
寄信至 support@bukza.com，提供您的新應用程式網址。我們會將此設為您的伺服器 URL，並寄給您 bukza_user_id 及 bukza_key。
開啟您應用程式的 .env 檔案，輸入 bukza_user_id 及 bukza_key 的數值。此檔案不會對其他 Glitch 使用者公開。
前往您的 Bukza 帳戶。在付款處理表單中，啟用「自動付款處理的訂單」並設定所需的預付款金額。
使用小工具完成一筆訂單，並確保使用您帳戶的電子郵件地址。當您用帳戶電子郵件完成訂單時，將不會收取付款 API 的任何費用。
測試期間，請查看 Glitch 的 "Logs" 分頁。這裡會顯示收到與發送的請求紀錄。
在 server.js 與 index.hbs 檔案中實作您的付款表單顯示及處理支付系統回應。請勿將您的金鑰或密碼插入任何檔案，僅限於 .env 檔案。專案檔案及其完整變更歷史對其他 Glitch 使用者皆可存取。

整合選項

您可以實作下列兩種選項之一：

「含預先授權」 — 此選項可防止超額預訂。當訂單完成時，金額會先在卡片上預先授權，然後我們會檢查訂單是否仍可用且價格未變。若訂單已不可用，預先授權會立即取消。

使用此整合選項時，您可稍後手動扣款。您可自行驗證預訂，然後選擇扣款或取消預先授權。
「簡化模式」 — 此選項不使用預先授權。在此情況下，訂單完成時會立即扣款。我們仍會檢查訂單可用性與金額，若有問題，會在「新訂單」訊息中為管理者新增警告。

若您的支付服務不支援預先授權，請使用此選項。

如何產生簽章雜湊？

請求中總是包含下列參數：

userId — 您在 Bukza 系統中的 ID，例如 11223。
orderNumber — Bukza 的訂單號碼，例如 "574285869"。
command — 要執行的指令名稱。可能的值："GetPaymentData"、"CaptureCallback"、"AuthorizeCallback"、"Cancel"、"Capture" 或 "Refund"。
data — 額外的指令資料，例如您支付系統中的交易號碼："18493853499"。
amount — 支付金額，例如 99.75。
timestamp — 自 Unix epoch 起的秒數，例如 1596706182。不同程式語言的範例請參考：https://www.epochconverter.com。

若要建立或驗證請求簽章，請將所有這些參數串接成一個字串（不含空格或加號），以您的金鑰計算 HMAC SHA256，並將結果轉為 base64 字串：

hash = base64(hmacSha256(userId + orderNumber + command + data + amount + timestamp), key);

不同程式語言的實作範例：https://www.jokecamp.com/blog/examples-of-creating-base64-hashes-using-hmac-sha256-in-different-languages/

您可以在這裡檢查計算結果：http://jsfiddle.net/dwyrk513/1/

重要注意事項：

將金額值轉為字串時，若有小數，請使用點（.）作為小數分隔符。
接收請求時，Bukza 會檢查 timestamp 是否與伺服器目前時間相符，且誤差不超過 5 分鐘。
當您從 Bukza 接收請求時，也建議您同樣檢查雜湊值與 timestamp。

選項 #1「含預先授權」

1.1. 當訂單完成時，Bukza 會向您的伺服器 URL 發送 POST 請求，內容如下：

{
    userId:11223,
    orderNumber:"574285869",
    command: "GetPaymentData",
    data: "",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "p2t1xcpBiXLPPDdB129vUctRAgGbzQgRcnX4IiZ0bNE="
    email: "john@example.com",
    phone: "+11111111111",
    culture = "en",
    checkStateToken = "eyJVc2VySWQiOjIsIk9yZGVyS...Ws9In0%3D"
}

回應此請求時，您應傳回下列格式的資料：

{
url: "https://yoursite.ru/amount=99.75&orderNumber=574285869&bukzaCulture=ru&bukzaUser=11223&bukzaCheckStateToken=eyJVc2VySWQiOjIsIk9yZ",
redirect: false
}

url — 產生的付款頁面網址。此頁面可架設於您的伺服器或支付閘道伺服器上。
redirect — 決定是否將使用者完全導向指定網址。若設為 false，付款表單將以 iframe 方式顯示於小工具內。您可在小工具設定中用 CSS 調整 iframe 大小。
checkStateToken 會以 bukzaCheckStateToken 參數加到 url。此參數可讓您在付款頁面檢查訂單狀態。相關說明請參閱這裡。

1.2. 此時客戶會看到您的付款表單並完成付款。您應從支付閘道收到通知至您的伺服器。收到通知後，請立即向 https://public.bukza.com/api/pay 發送 POST 請求。請求內容：

{
    userId:11223,
    orderNumber:"574285869",
    command: "AuthorizeCallback",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "2kkjjx/grcar6B9yknqUMP6eOdMw4yJwa60Uc8fisNA=",
    comment: "任何付款備註。此內容會顯示於管理者介面，不參與請求簽章計算。"
}

1.3. 根據訂單可用性與處理參數，Bukza 可能會：取消預先授權、立即扣款，或僅保留預先授權資金並建立訂單。若為最後一種情況，您可在管理者介面自行取消或扣款。無論哪種情況，Bukza 都會向您的伺服器發送請求，您需再轉發給支付閘道。

若要取消預先授權，Bukza 會發送如下請求：

{
    userId:11223,
    orderNumber:"574285869",
    command: "Cancel",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "ejIS+AiPRSH9qXV/bBcAf7OSViCVUtj/hYPsL4aYpNM="
    email: "john@example.com",
    phone: "+11111111111",
}

若要扣款預先授權資金，Bukza 會發送如下請求：

{
    userId:11223,
    orderNumber:"574285869",
    command: "Capture",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "JE4fRRLObEzCYk7aRFaW81DZw3sTXTOXsEcq3r8zm+Y="
    email: "john@example.com",
    phone: "+11111111111",
}

對於此類請求，您應回應 HTTP 狀態 200（SUCCESS）。

選項 #2「簡化模式」

2.1. 當訂單完成時，Bukza 也會如步驟 1.1 一樣向您的伺服器 URL 發送 POST 請求。

2.2. 此時客戶會看到您的付款表單並完成付款。您應從支付閘道收到通知至您的伺服器。收到通知後，請立即向 https://public.bukza.com/api/pay 發送 POST 請求。請求內容：

{
    userId:11223,
    orderNumber:"574285869",
    command: "CaptureCallback",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "eUKOwld1sEK3axhF9ZAy0WugXMJW+9nrs4BRlvnCeb0=",
    comment: "任何付款備註。此內容會顯示於管理者介面，不參與請求簽章計算。"
}

退款

您可以透過管理者介面對特定付款進行退款。退款可為全額或部分金額。當退款處理時，Bukza 會向您的伺服器發送請求。您必須再向您的支付閘道發送相應請求。 Bukza 發送的請求內容如下：

{
    userId:11223,
    orderNumber:"574285869",
    command: "Refund",
    data: "18493853499",
    amount: 50.75,
    timestamp: 1596706182,
    hash: "E62WH04cKUjAvQ0dmirYMc16mCGN96YyQfrft8vLj0A="
    email: "john@example.com",
    phone: "+11111111111",
}

對於此類請求，您應回應 HTTP 狀態 200（SUCCESS）。