點數銀行 API
讓客戶能夠使用他們的忠誠度獎勵來預訂旅遊行程
您可以自行決定是否讓您的白標旅遊平台網站與您的忠誠度計畫連結，以便累積或兌換忠誠度點數 (或兩者皆可)。您的忠誠度計畫會規定哪些購買行為符合累積忠誠度貨幣的資格 (無論該計畫中採用何種形式——點數、美 元或其他形式)，其中也包含您模板網站上的購買行為。您也可以允許旅客兌換範本網站上累積的點數來預訂旅遊產品。
顧客將有兩種方式兌換忠誠度獎勵——直接透過您的範本網站，或透過電話聯繫 Expedia 客服專員。透過「積分銀行」API，客戶將能夠：
- 兌換賺取的會員幣
- 復原旅遊產品購買作業 (也稱為取消或作廢)
- 因任何取消的旅遊計畫而收 到全額或部分退款，並計入會員計畫總金額
- 取得會員帳戶餘額
我們可以在您網站模板的頁首顯示客戶的忠誠度點數餘額。不過，由於這些 API 呼叫是在頁面載入時發生，顯示的點數在重新整理頁面之前不會更新，因此可能無法反映其他的會員計畫使用情況。
點數銀行 API 的端點涵蓋會員幣的兌換、復原和退款，也可以呼叫帳戶餘額端點。為了正確起見，請務必在交易時查詢此 API。下表詳細介紹每個端點，但所有端點 (及帳戶餘額端點) 都共用相同的標頭欄位。
標頭變數
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
partnerId | Expedia 提供的企業唯一識別碼 | 您的品牌 | 字串，最多 20 個字元 | 是 |
Authorization | Expedia 從您授權伺服器收到的存取標記，將由您的團隊進行驗證 | 標準 JSON Web 標記 (JWT) | 字串，標準 JWT 長度 | — |
Authorization2 | 由 Expedia 傳送的 JSON Web 標記 (JWT)；要在您這一端驗證的簽章和宣告 | 標準 JWT | 字串，標準 JWT 長度 | — |
>> 請參閱我們的請求與回應範例頁面，以了解有效載荷的詳細資訊
兌換
此 one-step 兌換流程讓客戶能夠透過積分銀行，使用 . 來兌換其忠誠度 Rewards 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」表中的「Object」欄位以查看詳細資訊 |
PaymentDetails
| 欄位 | 詳情 | 是否為必要？ |
|---|---|---|
redemptionDetails | 忠誠度兌換詳情；有關「Object」的詳細資訊，請參閱下方RedemptionDetails 部分 | 是 |
amountPaidInCash | 客戶以現金或信用卡支付的預訂金額；有關「物件」的詳細資訊，請參閱通用資料表「Amount」 | 是 |
RedemptionDetails
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
amountPaidInLoyaltyCurrency | 該預訂所支付的總點數、哩程 (或其他任何忠誠度貨幣)；關於嵌套欄位，請參閱通用資料表Amount | 是 | ||
redemptionConfirmationId | 兌換作業的識別碼；將在 Expedia 的退款或作廢要求中傳送，並應填入每日點數對帳報告中，做為兌換交易的「合作夥伴確認編號」 | expedia-a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 字串，最多 50 個字元 | 是 |
loyaltyRedemptionCode | 某些實作所需的兌換代碼，通常會在要求中填入；這是產品的一次性密碼，或預先定義的兌換代碼 (如果需要) | SKU | 字串，最多 20 個字元 | — |
promotionId | PromotionId (若該兌換請求附有適用之促銷編號) | 字串，最多 50 個字元 | — |
PointsPurchaseDetails
| 欄位 | 詳情 | 是否為必要？ |
|---|---|---|
pointsPurchaseValue | 採用網格定價進行預訂所需購買的總點數；有關物件詳情，請參閱「Amount」表格中的共通資料 | 是 |
amountPaidForPointsPurchase | 為購買所需點數而支付的現金總額。此值亦為basePriceForPointsPurchase + taxesAndFeesForPointsPurchase；關於嵌套項目，請參閱共通資料表Amount | 是 |
basePriceForPointsPurchase | 購買點數的基礎價格。舉例來說，若要購買 2000 點，且每點價格為 $0.02，則基礎價格為 $40;。關於嵌套項目的常見資料，請參閱Amount 表格。 | — |
taxesAndFeesForPointsPurchase | 若適用，購買點數之基礎價格將課徵相關稅費；關於嵌套項目，請參閱通用資料表Amount | — |
復原
若要在點數銀行處理復原 (即會員計畫交易的撤銷，也稱為取消或作廢)，您將使用 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 | 客戶帳戶中可用的點數、哩程或任何其他忠誠度貨幣的數量；關於嵌套項目，請參閱通用資料表「Amount」 | |||
DeclineReason | 交易遭拒絕的原因；請參閱「DeclineReason」資料表中的嵌套項目 | |||
reasonMessage | 隨拒絕回覆一併傳送的自訂訊息；關於嵌套項目，請參閱通用資料表DeclineReason |
>> 進一步了解 Amount
>> 進一步了解 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 | 客戶帳戶中可用的點數、哩程或任何其他忠誠度貨幣的數量；關於嵌套項目，請參閱「Amount」共通資料表 | |||
DeclineReason | 交易遭拒絕的原因；請參閱「DeclineReason」資料表中的嵌套項目 | |||
reasonMessage | 要隨附於拒絕回應的自訂訊息；請參閱通用資料 DeclineReason 表格 |
>> 進一步了解 Amount
>> 進一步了解 DeclineReason
RefundDetails
| 欄位 | 詳情 | 範例值 | 欄位類型和長度 | 是否為必要？ |
|---|---|---|---|---|
loyaltyRefundAmount | 退還的點數、哩程或任何其他忠誠度貨幣的總數；關於嵌套項目，請參閱「Amount」表格中的共通資料 | |||
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 | 客戶帳戶中可用的點數、哩程或任何其他忠誠度貨幣的數量；關於嵌套項目，請參閱通用資料表「Amount」 |