開始前
您需要同一客戶名下、已就緒的入金能力與已就緒的發行目的地錢包。請透過能力與任務 完成任何待辦事項,然後重新讀取兩項資源。1. 建立報價
使用POST /v3/quotes 建立價格。請傳送以下標頭:
data.id 儲存為 QUOTE_ID。請直接呈現回傳的金額與費用,而非由匯率重新計算。
2. 執行報價
在到期前,使用POST /v3/transfers 執行當前的報價。請為此筆預期轉帳使用新的金鑰:
data.id 儲存為 TRANSFER_ID,並保留其當前狀態。
為卡片與 Apple Pay 加入返回 URL
對於卡片或 Apple Pay 報價,您可以在同一請求中包含選用的redirectUrl。當客戶完成託管結帳後,結帳頁面會開啟此 URL,將客戶帶回您的應用程式。
redirectUrl 必須是長度不超過 2048 個字元的絕對 HTTPS URL,且不得包含內嵌憑證。對於不支援返回導向的報價,傳送 redirectUrl 會導致驗證失敗,而不會被忽略。
抵達 redirectUrl 僅代表瀏覽器完成了導向。它並不確認付款或轉帳已完成。請依據步驟 4 中的轉帳狀態以及 Webhook 事件判斷是否完成。
為卡片報價預先選擇結帳方式
對於卡片報價,您可以在同一請求中包含選用的checkoutMethod,用來選擇託管結帳開啟時預選的付款選項。目前的值為 card、apple_pay、google_pay、cash_app、sepa 與 blik。此清單是開放的且可能增加,因此在轉帳讀取中請容許您不認得的值。當請求的方式對客戶及其裝置可用時,結帳會以該方式開啟,客戶仍可選擇結帳提供的任何其他方式。省略該欄位即可保留預設的預先選擇。
checkoutMethod 是一種偏好,而不是保證。可用性取決於客戶、其裝置與結帳頁面,因此請求某種方式並不會使其變得可用。這裡的 sepa 與 blik 是卡片結帳內部的付款選項,而不是 Swipelux 的能力、通道或帳戶。預先選擇不會變更報價的能力、金額或費用,最終費用由結帳頁面確認。轉帳讀取會回傳請求的值,但不會確認客戶實際使用了哪種方式。對於非卡片報價傳送 checkoutMethod 會導致驗證失敗,而不會被忽略;使用相同冪等鍵的重送必須傳送相同的 checkoutMethod。
3. 取得入金指令
讀取GET /v3/transfers/{transferId}/instructions。請依回傳的 data.instructions 變體進行呈現,不要假設其類型。
這些資料僅屬於該筆轉帳。切勿將某筆轉帳的銀行座標、代碼、託管 URL、金額、參考編號或到期日重複用於另一筆入金。
對於銀行指令,若 reference.required 為 true,請於銀行座標旁顯示完整的 reference.value,並使其可複製。同時顯示同一組指令中回傳的金額與幣別。
發行的銀行帳戶則不同:它會為後續存款提供可重複使用的資料。若這才是您想要的體驗,請參閱發行銀行帳戶。
4. 追蹤結算
於執行後及每次事件後,讀取GET /v3/transfers/{transferId}。請以最新的 data.state 驅動面向客戶的狀態。
當轉帳需要進一步操作時,請使用 data.stateDetail 與 data.openTaskIds。切勿根據預期時程將其標記為已完成。
接下來,請加入 Webhooks,並持續同步轉帳狀態,直到其達到您產品可處理的結果。