點數銀行 API
讓您的旅客利用賺取的會員點數預訂旅遊產品
您可選擇是否讓您的白標旅遊平台網站與忠誠度計劃連結，用於賺取或兌換忠誠度貨幣 (或兩者皆可)。您的會員計畫會定義旅客的哪些購買項目有資格賺取會員幣 (無論您的計畫採取何種形式：點數、美元或其他形式)，包括範本網站上的購買項目。您也可以允許旅客兌換範本網站上累積的點數來預訂旅遊產品。
您的旅客在兌換賺取的會員點數時有兩個選擇：直接透過您的範本網站，或透過電話聯絡 Expedia 旅行社。透過點數銀行 API，您的旅客將能夠：
- 兌換賺取的會員幣
- 復原旅遊產品購買作業 (也稱為取消或作廢)
- 因任何取消的旅遊計畫而收到全額或部分退款，並計入會員計畫總金額
- 取得會員帳戶餘額
如需其他資訊，請參閱通用資料和回應頁面。
我們可以在範本網站頁首中顯示旅客的會員計畫餘額。不過，由於這些 API 呼叫是在頁面載入時發生，顯示的點數在重新整理頁面之前不會更新，因此可能無法反映其他的會員計畫使用情況。
點數銀行 API 的端點涵蓋會員幣的兌換、復原和退款，也可以呼叫帳戶餘額端點。為了正確起見，請務必在交易時查詢此 API。下表詳細介紹每個端點，但所有端點 (及帳戶餘額端點) 都共用相同的標頭欄位。
標頭變數
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
partnerId | Expedia 提供的企業唯一識別碼 | 您的品牌 | 字串，最多 20 個字元 | 是 |
Authorization | Expedia 從您授權伺服器收到的存取標記，將由您的團隊進行驗證 | 標準 JSON Web 標記 (JWT) | 字串，標準 JWT 長度 | 否 |
Authorization2 | 由 Expedia 傳送的 JSON Web 標記 (JWT)；要在您這一端驗證的簽章和宣告 | 標準 JWT | 字串，標準 JWT 長度 | 否 |
如需有效負載詳細資料，請參閱我們的要求和回應範例頁面。
兌換
此單一步驟認可程序可讓您的旅客使用 POST /redeem，透過點數銀行兌換會員獎勵。
要求
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
requestId | 交易要求的唯一識別碼 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 字串，最多 40 個字元 | 是 |
membershipId | 透過 SSO 收到的唯一旅客識別碼 | a6fgju7he1bf | 字串，最多 40 個字元 | 是 |
loyaltyAccountNumber | 客戶的忠誠度帳戶號碼 (亦稱為programAccountNumber)； | 234986576 | 字串，最多 40 個字元 | 否 |
programId | 旅客所屬會員計畫的識別碼，或與會員計畫相關聯的等級名稱 | 銀卡 Gold 白金卡 | 字串，最多 20 個字元 | 否 |
sourceConfirmationId | Expedia 端的確認編號 (也稱為 orderId)；在兌換、退款和作廢要求中傳送，並應包含在回應有效負載及每日點數對帳檔案中傳回 | 9223371998507503799 | 字串，最多 50 個字元 | 是 |
itineraryId | 預訂請洽 ItineraryId | 7610133766295 | 字串，最多 20 個字元 | 否 |
totalproductCost | 總預訂費用 (最多 2 位小數)；等於以點數支付的現金等價金額 + 以現金或卡片支付的金額 | 230.09 | 字串，最多 10 個字元 | 是 |
PaymentDetails | 忠誠度貨幣與現金或卡支付詳情；請參閱下方PaymentDetails 區段以獲取物件詳情 | 是 | ||
pointsPurchaseDetails | 僅適用於點數購買情境。請參閱下方PointsPurchaseDetails 區段以獲取物件詳情 | 否 |
回應
| 欄位 | 詳情 | 範例值 |
|---|---|---|
status | 交易狀態 (值：「已核准」或「已拒絕」) | 已拒絕 |
requestId | 交易要求 (來自要求有效負載) 的唯一識別碼 | a5783c58-c5ce-4ff9-b83c-58c5cedff9 |
transactionDateTime | 合作夥伴系統上記錄的交易日期和時間 | 2023-04-20T12:01:23.203057Z |
sourceConfirmationId | Expedia 端的訂單識別碼 (也稱為 orderId)；在兌換、退款和作廢要求中傳送，並應包含在回應有效負載和每日點數對帳檔案中 | 9223371998507503799 |
redemptionDetails | 兌換忠誠獎勵確認函；請參閱下方RedemptionDetails 區段以獲取物品詳情 | |
DeclineReason | 交易被拒絕的原因；請參閱通用資料表DeclineReason 請參閱資料表以獲取物件詳細資訊 |
PaymentDetails
| 欄位 | 詳情 | 是否為必要？ |
|---|---|---|
redemptionDetails | 忠誠度兌換詳情；物件詳情請參閱下方RedemptionDetails 部分 | 是 |
amountPaidInCash | 客戶以現金或信用卡支付的預訂金額；參見通用資料表金額 物件詳情表 | 是 |
RedemptionDetails
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
amountPaidInLoyaltyCurrency | 為預訂支付的總點數、總里程數 (或任何其他會員幣總計)；請參閱通用資料金額表格中的嵌入欄位 | 是 | ||
redemptionConfirmationId | 兌換作業的識別碼；將在 Expedia 的退款或作廢要求中傳送，並應填入每日點數對帳報告中，做為兌換交易的「合作夥伴確認編號」 | expedia-a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 字串，最多 50 個字元 | 是 |
loyaltyRedemptionCode | 某些實作所需的兌換代碼，通常會在要求中填入；這是產品的一次性密碼，或預先定義的兌換代碼 (如果需要) | SKU | 字串，最多 20 個字元 | 否 |
promotionId | PromotionId (若兌換請求附有任何適用的促銷 ID) | 字串，最多 50 個字元 | 否 |
PointsPurchaseDetails
| 欄位 | 詳情 | 是否為必要？ |
|---|---|---|
pointsPurchaseValue | 採用網格定價預訂時需購買的總點數；詳見通用資料表Amount 中的物件詳細資訊 | 是 |
amountPaidForPointsPurchase | 購買所需點數所支付的總現金金額。此值亦為basePriceForPointsPurchase + taxesAndFeesForPointsPurchase；請參閱通用資料金額 表格以獲取嵌套項目的資訊 | 是 |
basePriceForPointsPurchase | 購買點數的基礎價格。例如需購買的點數為 2000 點，若以$0.02 每點價格購買，則基準價格為$40; 參見通用資料金額 表格中的嵌套項目 | 否 |
taxesAndFeesForPointsPurchase | 適用於點數購買基礎價格之稅金與費用 (如適用)；詳見通用資料表金額 嵌套項目表 | 否 |
復原
若要在點數銀行處理復原 (即會員計畫交易的撤銷，也稱為取消或作廢)，您將使用 POST /rollback 端點。
當兌換作業成功，但 Expedia 由於供應失敗等原因 (例如旅客嘗試訂房時發現飯店客房已售完) 而撤銷兌換時，就會觸發此 API。由於這是將兌換作業復原的動作，因此需要對帳，才能再次使用賺取的會員點數。
注意：兌換或復原交易均不應出現在每日點數對帳報告中。
要求
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
requestId | 交易要求的唯一識別碼 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 字串，最多 40 個字元 | 是 |
membershipId | 會員計畫中旅客的唯一識別碼 | a6fgju7he1bf | 字串，最多 40 個字元 | 是 |
sourceConfirmationId | Expedia 端的訂單識別碼 (也稱為 orderId)；在兌換、退款和作廢要求中傳送；應包含在回應有效負載和每日點數對帳檔案中 | 9223371998507503799 | 字串，最多 50 個字元 | 是 |
CancellationDetails | 復原交易的相關詳細資料；請參閱 CancellationDetails 表格中的嵌入項目 |
回應
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
status | 復原交易狀態，指出取消是否成功 (值：「已核准」或「已拒絕」) | 已核准 | 字串 | 是 |
requestId | 交易要求 (來自要求有效負載) 的唯一識別碼 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 字串，最多 40 個字元 | 是 |
transactionDateTime | 您系統上記錄的交易日期和時間 | 2023-04-20T12:01:23.203057Z | 字串，最多 40 個字元 | 是 |
sourceConfirmationId | Expedia 端的訂單識別碼 (也稱為 orderId)；在兌換、退款和作廢要求中傳送；應包含在回應有效負載和每日點數對帳檔案中 | 9223371998507503799 | 字串，最多 50 個字元 | 是 |
CancellationDetails | 復原交易的相關細節 (如果 status 值為「已核准」，則為必要)；請參閱 CancellationDetails 表格中的嵌入項目 | |||
Balance | 旅客帳戶中可用的點數、里程數或任何其他會員幣；請參閱通用資料金額表格中的嵌入項目 | |||
DeclineReason | 交易被拒絕的原因；請參閱通用資料 DeclineReason 表格中的嵌入項目 | |||
reasonMessage | 要隨附於拒絕回應的自訂訊息；請參閱通用資料 DeclineReason 表格中的嵌入項目 |
CancellationDetails
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
redemptionConfirmationId | 兌換的確認編號；在兌換回應中傳送；如果復原，則不應填入每日點數報告中 | a5783c58-c5ce-4ff9-b83c-58c5cedff991 | 字串，最多 50 個字元 | 是 |
cancellationConfirmationId | 復原作業的確認編號 (如果 status 值為「已核准」，則為必要)；不應填入每日點數報告中 | a5783c58-c5ce-4ff9-b83c-58c5cedff993 | 字串，最多 50 個字元 | 否 |
退款
此 API 用於透過 POST/refund 處理對您點數銀行的會員退款。當旅客在已使用賺取的會員點數進行預訂之後，必須取消計畫時，就會觸發此 API。由於這是賺取的會員點數退款，因此需要先進行對帳，才能在旅客的帳戶中使用退款的貨幣。
要求
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
requestId | 退款要求的唯一識別碼 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 字串，最多 40 個字元 | 是 |
membershipId | 旅客唯一識別碼 | a6fgju7he1bf | 字串，最多 40 個字元 | 是 |
sourceConfirmationId | Expedia 端的訂單識別碼 (也稱為 orderId)；在兌換、退款和作廢要求中傳送；應包含在回應有效負載和每日點數對帳檔案中 | 9223371998507503799 | 字串，最多 50 個字元 | 是 |
RefundDetails | 退款交易詳細資料；請參閱 RefundDetails 表格中的嵌入項目 |
回應
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
status | 退款狀態 (值：「已核准」或「已拒絕」) | 已核准 | 字串 | 是 |
requestId | 退款要求 (來自要求有效負載) 的唯一識別碼 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 字串，最多 40 個字元 | 是 |
transactionDateTime | 您系統上記錄的交易日期和時間 | 2023-04-20T12:01:23.203057Z | 字串，最多 40 個字元 | 是 |
sourceConfirmationId | Expedia 端的訂單識別碼 (也稱為 orderId)；在兌換、退款和作廢要求中傳送；應包含在回應有效負載和每日點數對帳檔案中 | 9223371998507503799 | 字串，最多 50 個字元 | 是 |
RefundDetails | 退款要求詳細資料；請參閱 RefundDetails 表格中的嵌入項目 | |||
Balance | 旅客帳戶中可用的點數、里程數或任何其他會員幣；請參閱通用資料金額表格中的嵌入項目 | |||
DeclineReason | 交易被拒絕的原因；請參閱通用資料 DeclineReason 表格中的嵌入項目 | |||
reasonMessage | 要隨附於拒絕回應的自訂訊息；請參閱通用資料 DeclineReason 表格 |
RefundDetails
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
loyaltyRefundAmount | 退款的總點數、總里程數或任何其他會員幣總計；請參閱通用資料金額表格中的嵌入項目 | |||
redemptionConfirmationId | 兌換作業的識別碼；在兌換回應中傳送 | a5783c58-c5ce-4ff9-b83c-58c5cedff918 | 字串，最多 50 個字元 | 是 |
refundConfirmationId | 退款作業的識別碼；將在 Expedia 的退款或作廢要求中傳送，並應填入每日點數對帳檔案中，做為退款交易的「合作夥伴確認編號」 | a324554f03-c5ce-4ff9-b83c-58c5cedff988 | 字串，最多 50 個字元 | 否 |
帳戶餘額
若要擷取旅客的會員帳戶餘額，您將使用 POST /balance 端點。
要求
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
requestId | 交易要求的唯一識別碼 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 字串，最多 40 個字元 | 是 |
membershipId | 會員計畫中旅客的唯一識別碼 | a6fgju7he1bf | 字串，最多 40 個字元 | 是 |
loyaltyAccountNumber | 旅客的會員帳號 (也稱為 programAccountNumber)；只有在會員計畫作業需要 membershipId 以外的識別碼時，才應填入 | 234986576 | 字串，最多 40 個字元 | 否 |
programId | 旅客所屬會員計畫的識別碼，或與會員計畫相關聯的等級名稱 | 白金卡 | 字串，最多 20 個字元 | 否 |
回應 (成功)
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
requestId | 交易要求的唯一識別碼 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 字串，最多 40 個字元 | 是 |
Balance | 旅客帳戶中可用的點數、里程數或任何其他會員幣；請參閱通用資料金額表格中的嵌入項目 |