Points Bank API
お客様がロイヤルティの獲得ポイントを使って旅行を予約できるようにします
ホワイトラベル旅行プラットフォームのサイトを、ロイヤルティ プログラムと 連携させるかどうかは、お客様ご自身でお選びいただけます。これにより、ロイヤルティ 通貨の獲得や利用（あるいはその両方）が可能になります。ロイヤルティ プログラムでは、テンプレートサイトでの購入を含め、どの購入が ロイヤルティ 通貨（プログラム内でポイント、ドル、その他どのような形態であれ）の獲得対象となるかを定義しています。また、顧客が貯めたロイヤルティ通貨をテンプレートサイトで旅行予約に利用できるようにすることもできます。
お客様は、ロイヤルティ の獲得ポイントを、テンプレートサイトから直接、またはエクスペディアの担当者に電話で連絡して、2つの方法のいずれかでご利用いただけます。ポイントバンクAPIを利用することで、お客様は以下のことが可能になります：
- 獲得したロイヤルティ通貨を利用する
- 旅行の購入をロールバックする (キャンセルまたは無効化とも呼ばれる)
- キャンセルされた旅行プランの全額または一部をロイヤルティ残高に返金する
- ロイヤルティアカウントの残高を取得する
>> 詳細については、「共通データと回答」のページをご覧ください
テンプレートサイトのヘッダーに、お客様の ロイヤルティ の残高を表示することができます。ただし、API 呼び出しはページの読み込み時に行われるため、表示されるポイントはページが更新されるまで更新されず、他のロイヤルティの使用状況が反映されない場合があります。
Points Bank API には、ロイヤルティ通貨の利用、ロールバック、返金に対応するエンドポイントがあります。アカウント残高エンドポイントを呼び出すこともできます。正確を期すため、この API はトランザクション時に照会される必要があります。各エンドポイントの詳細は以下のタブで説明していますが、これらすべてのエンドポイントとアカウント残高エンドポイントでヘッダーフィールドは共通しています。
ヘッダー変数
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
partnerId | エクスペディアがが提供する、ビジネスの一意の識別子 | 貴社のブランド | 文字列 (最大 20 文字) | 必須 |
Authorization | エクスペディアが権限サーバーから受信したアクセス トークン (チームで検証) | 標準 JSON Web トークン (JWT) | 文字列 (標準 JWT 長) | — |
Authorization2 | エクスペディアから送信された 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 | 顧客が参加しているロイヤルティプログラムの識別子、またはロイヤルティプログラムに関連付けられているステータス名 | シルバー ゴールド プラチナ | 文字列 (最大 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 | お客様が予約に対して現金またはカードで支払った金額です。オブジェクトの詳細については、共通データテーブル「Amount」をご参照ください。 | 必須 |
RedemptionDetails
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
amountPaidInLoyaltyCurrency | その予約に対して支払われたポイント、マイル（またはその他の ロイヤルティ 通貨）の合計数です。ネストされたフィールドについては、共通データテーブル「Amount」をご参照ください。 | 必須 | ||
redemptionConfirmationId | 利用オペレーションの識別子。エクスペディアからの返金または無効化リクエストで送信されます。また、デイリーポイントレコンレポートでは、利用取引の「パートナー確認 ID」として記載されます。 | expedia-a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 文字列 (最大 50 文字) | 必須 |
loyaltyRedemptionCode | いくつかの実装で要求される利用コード (通常はリクエストに入力される)。ワンタイムパスワードか、必要に応じて商品のためにあらかじめ定義された利用コード | SKU | 文字列 (最大 20 文字) | — |
promotionId | PromotionId（引き換えリクエストに紐付けられているプロモーションIDがある場合） | 文字列 (最大 50 文字) | — |
PointsPurchaseDetails
| フィールド | 説明 | 必須/必須ではない |
|---|---|---|
pointsPurchaseValue | グリッド価格に基づいて予約するために購入が必要なポイントの合計です。オブジェクトの詳細については、共通データ「Amount」テーブルをご参照ください。 | 必須 |
amountPaidForPointsPurchase | 必要なポイントを購入するために支払った現金の総額です。この値は、basePriceForPointsPurchase + taxesAndFeesForPointsPurchase でもあります。ネストされた項目については、共通データテーブル「Amount」をご参照ください。 | 必須 |
basePriceForPointsPurchase | 購入するポイントの基本価格です。例えば、購入するポイントが2000ポイントの場合、1ポイントあたり$0.02で購入すると、基本価格は$40; となります。ネストされたアイテムについては、共通データAmount のテーブルをご参照ください。 | — |
taxesAndFeesForPointsPurchase | ポイント購入の基本価格に適用される税金および手数料（該当する場合）。ネストされた項目については、「共通データ」のAmount テーブルをご参照ください。 | — |
ロールバック
ポイントバンクでロールバック (つまり、ロイヤルティ取引の取り消し。キャンセルまたは無効化とも呼ばれます) を処理するに は、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 | お客様のアカウントに保有されているポイント、マイル、またはその他の ロイヤルティ 単位の残高です。ネストされた項目については、共通データテーブル「Amount」をご参照ください。 | |||
DeclineReason | トランザクションが拒否された理由については、ネストされた項目に関する共通データテーブル「DeclineReason」をご参照ください。 | |||
reasonMessage | 拒否応答に添付するカスタムメッセージです。ネストされた項目については、共通データ「DeclineReason」テーブルをご参照ください。 |
>> Amountの詳細はこちら
>> #の詳細はこちら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 | お客様のアカウントに保有されているポイント、マイル、またはその他の ロイヤルティ 単位の残高です。ネストされた項目については、共通データ「Amount」テーブルをご参照ください。 | |||
DeclineReason | トランザクションが拒否された理由については、ネストされた項目に関する共通データテーブル「DeclineReason」をご参照ください。 | |||
reasonMessage | 不承認レスポンスに添えるカスタムメッセージ (共通データ DeclineReason の表を参照) |
>> Amountの詳細はこちら
>> #の詳細はこちらDeclineReason
RefundDetails
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
loyaltyRefundAmount | 払い戻されたポイント、マイル、またはその他の ロイヤルティ 通貨の合計数。ネストされた項目につい ては、共通データAmount の表をご参照ください。 | |||
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 | お客様のアカウントに保有されているポイント、マイル、またはその他の ロイヤルティ 単位の残高です。ネストされた項目については、共通データテーブル「Amount」をご参照ください。 |