Points Bank API
顧客がロイヤルティの収益を使って旅行を予約できるようにします。
White Label Travel Platformサイトをロイヤルティプログラム に接続し、ロイヤルティ通貨を獲得するか交換するか（またはその両方）を選択します。あなたのロイヤルティプログラムでは、どの購入がロイヤルティ通貨（あなたのプログラムではポイント、ドル、その他どのような形であれ）を獲得する対象となるかを定義します。また、顧客が貯めたロイヤルティ通貨をテンプレートサイトで旅行予約に利用できるようにすることもできます。
お客様には、ロイヤルティ の収益を換金する方法として、お客様のテンプレート サイトから直接換金する方法と、エクスペディアの担当者と電話で換金する方法の2通りがあります。ポイントバンクAPIをご利用いただくと、以下のことが可能になります：
- 獲得したロイヤルティ通貨を利用する
- 旅行の購入をロールバックする (キャンセルまたは無効化とも呼ばれる)
- キャンセルされた旅行プランの全額または一部をロイヤルティ残高に返金する
- ロイヤルティアカウントの残高を取得する
追加情報については、一般的なデータとレスポンスに関するページをご覧ください。
お客様のロイヤルティ残高をテンプレートサイトのヘッダーに表示することができます。ただし、API 呼び出しはページの読み込み時に行われるため、表示されるポイントはページが更新されるまで更新されず、他のロイヤルティの使用状況が反映されない場合があります。
Points Bank API には、ロイヤルティ通貨の利用、ロールバック、返金に対応するエンドポイントがあります。アカウント残高エンドポイントを呼び出すこともできます。正確を期すため、この API はトランザクション時に照会される必要があります。各エンドポイントの詳細は以下のタブで説明していますが、これらすべてのエンドポイントとアカウント残高エンドポイントでヘッダーフィールドは共通しています。
ヘッダー変数
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
partnerId | エクスペディアがが提供する、ビジネスの一意の識別子 | 貴社のブランド | 文字列 (最大 20 文字) | 必須 |
Authorization | エクスペディアが権限サーバーから受信したアクセス トークン (チームで検証) | 標準 JSON Web トークン (JWT) | 文字列 (標準 JWT 長) | — |
Authorization2 | エクスペディアから送信された JSON Web トークン (JWT) (署名とクレームは貴社側で検証) | 標準 JWT | 文字列 (標準 JWT 長) | — |
ペイロードの詳細については、サンプルのリクエストとレスポンスのページをご覧ください。
利用
このone-stepコミットプロセスにより、お客様はポイントバンクを経由して、.NETを使用してロイヤルティRewards POST /redeem。
リクエスト
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
requestId | 取引リクエストの一意の識別子 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 文字列 (最大 40 文字) | 必須 |
membershipId | SSO 経由で受信した一意の顧客識別子 | a6fgju7he1bf | 文字列 (最大 40 文字) | 必須 |
loyaltyAccountNumber | お客様のロイ ヤルティアカウント番号（programAccountNumber）； | 234986576 | 文字列 (最大 40 文字) | — |
programId | 顧客が参加しているロイヤルティプログラムの識別子、またはロイヤルティプログラムに関連付けられているステータス名 | シルバー ゴールド プラチナ | 文字列 (最大 20 文字) | — |
sourceConfirmationId | エクスペディア側の確認識別子 (orderId とも呼ばれる)。利用、返金、無効化の各リクエストで送信され、レスポンスペイロードの一部として、およびデイリーポイントレコンファイルの一部として返送される必要があります。 | 9223371998507503799 | 文字列 (最大 50 文字) | 必須 |
itineraryId | ItineraryId | 7610133766295 | 文字列 (最大 20 文字) | — |
totalproductCost | 予約の合計金額 (小数点以下2桁まで)。ポイントで支払った金額の現金相当額 + 現金またはカードで支払った金額 | 230.09 | 文字列 (最大 10 文字) | 必須 |
PaymentDetails | ロイヤルティの通貨と現金またはカードによる支払いの詳細; オブジェクトの詳細については、以下のPaymentDetails セクションを参照してください。 | 必須 | ||
pointsPurchaseDetails | ポイント購入のシナリオにのみ必要。オブジェクトの詳細については、以下のPointsPurchaseDetails セクションを参照してください。 | — |
レスポンス
| フィールド | 説明 | サンプル値 |
|---|---|---|
status | 取引ステータス (値 : Approved または Declined) | Declined |
requestId | 取引リクエストの一意の識別子 (リクエストペイロードから) | a5783c58-c5ce-4ff9-b83c-58c5cedff9 |
transactionDateTime | パートナーシステムに記録されている取引日時 | 2023-04-20T12:01:23.203057Z |
sourceConfirmationId | エクスペディア側からの注文識別子 (orderId とも呼ばれる)。利用、返金、無効化の各リクエストで送信され、レスポンスペイロードとデイリーポイントレコンファイルに含める必要があります。 | 9223371998507503799 |
redemptionDetails | 交換されたロイヤルティアワードの確認; オブジェクトの詳細については、以下のRedemptionDetails セクションを参照してください。 | |
DeclineReason | トランザクションが拒否された理由。DeclineReasonテーブルを参照してください。 |
PaymentDetails
| フィールド | 説明 | 必須/必須ではない |
|---|---|---|
redemptionDetails | ロイヤルティ償還の詳細; オブジェクトの詳細については、以下のRedemptionDetails セクションを参照してください。 | 必須 |
amountPaidInCash | 顧客が予約に対して現金またはカードで支払った金額。オブジェクトの詳細については、共通データ金額 テーブルを参照してください。 | 必須 |
RedemptionDetails
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
amountPaidInLoyaltyCurrency | 予約に対して支払われたポイント、マイル (またはその他のロイヤルティ通貨) の合計数 (ネストされたフィールドについては、共通データ 金額 の表を参照) | 必須 | ||
redemptionConfirmationId | 利用オペレーションの識別子。エクスペディアからの返金または無効化リクエストで送信されます。また、デイリーポイントレコンレポートでは、利用取引の「パートナー確認 ID」として記載されます。 | expedia-a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 文字列 (最大 50 文字) | 必須 |
loyaltyRedemptionCode | いくつかの実装で要求される利用コード (通常はリクエストに入力される)。ワンタイムパスワードか、必要に応じて商品のためにあらかじめ定義された利用コード | SKU | 文字列 (最大 20 文字) | — |
promotionId | PromotionId (交換リクエストに添付されているプロモーションIDがある場合) | 文字列 (最大 50 文字) | — |
PointsPurchaseDetails
| フィールド | 説明 | 必須/必須ではない |
|---|---|---|
pointsPurchaseValue | グリッド価格で予約するために購入するポイントの合計。オブジェクトの詳細については、共通データ金額 テーブルを参照してください。 | 必須 |
amountPaidForPointsPurchase | 必要なポイントを購入するために支払った現金の総額。この値もbasePriceForPointsPurchase + taxesAndFeesForPointsPurchase です。ネストされた項目については、共通データ量 の表を参照してください。 | 必須 |
basePriceForPointsPurchase | 購入するポイントの基本価格。例えば、購入されるポイントは2000ポイントで、ポイントが1ポイントあたり$0.02で購入される場合、基本価格は$40; となります。ネストされた項目については、共通データ金額 テーブルを参照してください。 | — |
taxesAndFeesForPointsPurchase | ポイント購入の基本価格に適用される税金と手数料（該当する場合）。ネストされた項目については、共通データ金額 テーブルをご参照ください。 | — |
ロールバック
ポイントバンクでロールバック (つまり、ロイヤルティ取引の取り消し。キャンセルまたは無効化とも呼ばれます) を処理するには、POST /rollback エンドポイントを使用します。
利用オペレーションが成功したときにこの API がトリガーされますが、エクスペディアでは、旅行商品のエラー (たとえば、顧客が予約しようとしている間にホテルの客室が売り切れた) などの理由で利用オペレーションを取り消す必要があります。これは利用のロールバックであるため、ロイヤルティ通貨が再び利用できるようになるまでには消し込みが必要です。
注 : 利用取引とロールバック取引はデイリーポイント消し込みレポートに記載されません。
リクエスト
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
requestId | 取引リクエストの一意の識別子 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 文字列 (最大 40 文字) | 必須 |
membershipId | あなたのロイヤルティプログラムからの顧客の一意の識別子 | a6fgju7he1bf | 文字列 (最大 40 文字) | 必須 |
sourceConfirmationId | エクスペディア側からの注文識別子 (orderId とも呼ばれる)。利用、返金、無効化の各リクエストで送信され、レスポンスペイロードとデイリーポイントレコンファイルに含める必要があります。 | 9223371998507503799 | 文字列 (最大 50 文字) | 必須 |
CancellationDetails | ロールバック取引の詳細 (ネストされた項目については CancellationDetails の表を参照) |
レスポンス
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
status | キャンセルが成功したかどうかを示すロールバック取引ステータス (値 : Approved または Declined) | Approved | 文字列 | 必須 |
requestId | 取引リクエストの一意の識別子 (リクエストペイロードから) | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 文字列 (最大 40 文字) | 必須 |
transactionDateTime | 貴社のシステムに記録されている取引日時 | 2023-04-20T12:01:23.203057Z | 文字列 (最大 40 文字) | 必須 |
sourceConfirmationId | エクスペディア側からの注文識別子 (orderId とも呼ばれる)。利用、返金、無効化の各リクエストで送信され、レスポンスペイロードとデイリーポイントレコンファイルに含める必要があります。 | 9223371998507503799 | 文字列 (最大 50 文字) | 必須 |
CancellationDetails | ロールバック取引の詳細 (status の値が Approved の場合は必須。ネストされた項目については CancellationDetails の表を参照) | |||
Balance | 顧客のアカウントで利用可能なポイント、マイル、その他のロイヤルティ通貨の数 (ネストされた項目については、共通データ 金額 の表を参照) | |||
DeclineReason | 取引が不承認となった理由 (ネストされた項目については、共通データ DeclineReason の表を参照) | |||
reasonMessage | 不承認レスポンスに添えるカスタムメッセージ (ネストされた項目については、共通データ DeclineReason の表を参照) |
CancellationDetails
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
redemptionConfirmationId | 利用のための確認識別子。利用レスポンスで送信されます。ロールバックされた場合、デイリーポイントレポートには反映されません。 | a5783c58-c5ce-4ff9-b83c-58c5cedff991 | 文字列 (最大 50 文字) | 必須 |
cancellationConfirmationId | ロールバックオペレーションの確認識別子 (status の値が Approved の場合は必須。デイリーポイントレポートには反映されない) | a5783c58-c5ce-4ff9-b83c-58c5cedff993 | 文字列 (最大 50 文字) | — |
Refunds
この API は、POST /refund でロイヤルティのポイントバンクへの返金を処理するために使用されます。すでにロイヤルティ通貨を使用して予約した後で、顧客がプランをキャンセルする必要がある場合にトリガーされます。これはロイヤルティ通貨に対する返金であるため、返金された通貨が顧客のアカウントで利用できるようになる前に消し込みが必要です。
リクエスト
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
requestId | 返金リクエストの一意の識別子 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 文字列 (最大 40 文字) | 必須 |
membershipId | 一意の顧客識別子 | a6fgju7he1bf | 文字列 (最大 40 文字) | 必須 |
sourceConfirmationId | エクスペディア側からの注文識別子 (orderId とも呼ばれる)。利用、返金、無効化の各リクエストで送信され、レスポンスペイロードとデイリーポイントレコンファイルに含める必要があります。 | 9223371998507503799 | 文字列 (最大 50 文字) | 必須 |
RefundDetails | 返金取引の詳細 (ネストされた項目については RefundDetails の表を参照) |
レスポンス
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
status | 返金ステータス (値 : Approved または Declined) | Approved | 文字列 | 必須 |
requestId | 返金リクエストの一意の識別子 (リクエストペイロードから) | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 文字列 (最大 40 文字) | 必須 |
transactionDateTime | 貴社のシステムに記録されている取引日時 | 2023-04-20T12:01:23.203057Z | 文字列 (最大 40 文字) | 必須 |
sourceConfirmationId | エクスペディア側からの注文識別子 (orderId とも呼ばれる)。利用、返金、無効化の各リクエストで送信され、レスポンスペイロードとデイリーポイントレコンファイルに含める必要があります。 | 9223371998507503799 | 文字列 (最大 50 文字) | 必須 |
RefundDetails | 返金リクエストの詳細 (ネストされた項目については RefundDetails の表を参照) | |||
Balance | 顧客のアカウントで利用可能なポイント、マイル、その他のロイヤルティ通貨の数 (ネストされた項目については、共通データ 金額 の表を参照) | |||
DeclineReason | 取引が不承認となった理由 (ネストされた項目については、共通データ DeclineReason の表を参照) | |||
reasonMessage | 不承認レスポンスに添えるカスタムメッセージ (共通データ DeclineReason の表を参照) |
RefundDetails
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
loyaltyRefundAmount | 返金されるポイント、マイル、またはその他のロイヤルティ通貨の合計数 (ネストされたフィールドについては、共通データ 金額 の表を参照) | |||
redemptionConfirmationId | 利用オペレーションの識別子 (利用レスポンスで送信される) | a5783c58-c5ce-4ff9-b83c-58c5cedff918 | 文字列 (最大 50 文字) | 必須 |
refundConfirmationId | 返金オペレーションの識別子。エクスペディアからの返金または無効化リクエストで送信されます。また、デイリーポイントレコンファイルでは、返金取引の「パートナー確認 ID」として記載されます。 | 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 | 顧客のアカウントで利用可能なポイント、マイル、その他のロイヤルティ通貨の数 (ネストされた項目については、共通データ 金額 の表を参照) |