點數銀行 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`)；只有在會員計畫作業需要 `membershipId` 以外的識別碼時，才應填入	234986576	字串，最多 40 個字元	否
`programId`	旅客所屬會員計畫的識別碼，或與會員計畫相關聯的等級名稱	銀卡 Gold 白金卡	字串，最多 20 個字元	否
`sourceConfirmationId`	Expedia 端的確認編號 (也稱為 `orderId`)；在兌換、退款和作廢要求中傳送，並應包含在回應有效負載及每日點數對帳檔案中傳回	9223371998507503799	字串，最多 50 個字元	是
`totalproductCost`	總預訂費用 (最多 2 位小數)；等於以點數支付的現金等價金額 + 以現金或卡片支付的金額	230.09	字串，最多 10 個字元	是
`PaymentDetails`	會員幣和現金或卡片付款詳細資料；請參閱 PaymentDetails 表格中的嵌入欄位			是

回應

欄位	詳情	範例值
`status`	交易狀態 (值：「已核准」或「已拒絕」)	已拒絕
`requestId`	交易要求 (來自要求有效負載) 的唯一識別碼	a5783c58-c5ce-4ff9-b83c-58c5cedff9
`transactionDateTime`	合作夥伴系統上記錄的交易日期和時間	2023-04-20T12:01:23.203057Z
`sourceConfirmationId`	Expedia 端的訂單識別碼 (也稱為 orderId)；在兌換、退款和作廢要求中傳送，並應包含在回應有效負載和每日點數對帳檔案中	9223371998507503799
`redemptionDetails`	兌換的會員獎勵確認；請參閱 RedemptionDetails 表格中的嵌入項目
`DeclineReason`	交易被拒絕的原因；請參閱通用資料 DeclineReason 表格中的嵌入項目
`reasonMessage`	要隨附於拒絕回應的自訂訊息，可使記錄更完善；請參閱通用資料 DeclineReason 表格中的嵌入項目

PaymentDetails

欄位	詳情	是否為必要？
`redemptionDetails`	會員兌換的詳細資料；請參閱 RedemptionDetails 表格中的嵌入項目	是
`amountPaidInCash`	旅客以現金或卡片為預訂支付的金額；請參閱通用資料金額表格中的嵌入項目	是

RedemptionDetails

欄位	詳情	範例值	欄位類型和長度	是否為必要？
`amountPaidInLoyaltyCurrency`	為預訂支付的總點數、總里程數 (或任何其他會員幣總計)；請參閱通用資料金額表格中的嵌入欄位			是
`redemptionConfirmationId`	兌換作業的識別碼；將在 Expedia 的退款或作廢要求中傳送，並應填入每日點數對帳報告中，做為兌換交易的「合作夥伴確認編號」	expedia-a5783c58-c5ce-4ff9-b83c-58c5cedff988	字串，最多 50 個字元	是
`loyaltyRedemptionCode`	某些實作所需的兌換代碼，通常會在要求中填入；這是產品的一次性密碼，或預先定義的兌換代碼 (如果需要)	SKU	字串，最多 20 個字元	否

復原

若要在點數銀行處理復原 (即會員計畫交易的撤銷，也稱為取消或作廢)，您將使用 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`	旅客帳戶中可用的點數、里程數或任何其他會員幣；請參閱通用資料金額表格中的嵌入項目