Points Bank API
顧客がロイヤルティポイントを旅行の予約に利用できるようにする
ホワイトレーベルテンプレートサイトを貴社のロイヤルティプログラムに連携して、ロイヤルティ通貨を獲得または利用 (またはその両方) できるようにするかを選択します。ロイヤルティプログラムでは、テンプレートサイトでの購入も含め、顧客のどの購入がロイヤルティ通貨 (ポイントやドルなど、プログラムでのロイヤルティ通貨の名称はさまざまです) の獲得対象になるかを定義します。また、顧客が貯めたロイヤルティ通貨をテンプレートサイトで旅行予約に利用できるようにすることもできます。
顧客が獲得したロイヤルティ通貨を利用するには、貴社のテンプレートサイトから直接利用する方法と、エクスペディアのエージェントに電話で依頼する方法の 2 つの方法があります。Points Bank API を使用すると、顧客は以下のことができるようになります。
- 獲得したロイヤルティ通貨を利用する
- 旅行の購入をロールバックする (キャンセルまたは無効化とも呼ばれる)
- キャンセルされた旅行プランの全額または一部をロイヤルティ残高に返金する
- ロイヤルティアカウントの残高を取得する
追加情報については、一般的なデータとレスポンスに関するページをご覧ください。
顧客のロイヤルティ残高はテンプレートサイトのヘッダーに表示できます。ただし、API 呼び出しはページの読み込み時に行われるため、表示されるポイントはページが更新されるまで更新されず、他のロイヤルティの使用状況が反映されない場合があります。
Points Bank API には、ロイヤルティ通貨の利用、ロールバック、返金に対応するエンドポイントがあります。アカウント残高エンドポイントを呼び出すこともできます。正確を期すため、この API はトランザクション時に照会される必要があります。各エンドポイントの詳細は以下のタブで説明していますが、これらすべてのエンドポイントとアカウント残高エンドポイントでヘッダーフィールドは共通しています。
ヘッダー変数
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
partnerId | エクスペディアがが提供する、ビジネスの一意の識別子 | 貴社のブランド | 文字列 (最大 20 文字) | 必須 |
Authorization | エクスペディアが権限サーバーから受信したアクセス トークン (チームで検証) | 標準 JSON Web トークン (JWT) | 文字列 (標準 JWT 長) | 必須ではない |
Authorization2 | エクスペディアから送信された JSON Web トークン (JWT) (署名とクレームは貴社側で検証) | 標準 JWT | 文字列 (標準 JWT 長) | 必須ではない |
ペイロードの詳細については、サンプルのリクエストとレスポンスのページをご覧ください。
利用
このワンステップコミットプロセスにより、顧客は POST /redeem を使用してポイントバンクを経由して、ロイヤルティリワードを利用できます。
リクエスト
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
requestId | 取引リクエストの一意の識別子 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 文字列 (最大 40 文字) | 必須 |
membershipId | SSO 経由で受信した一意の顧客識別子 | a6fgju7he1bf | 文字列 (最大 40 文字) | 必須 |
loyaltyAccountNumber | 顧客のロイヤルティアカウント番号 (別名 programAccountNumber) (これは、ロイヤルティオペレーションに membershipId 以外の識別子が必要な場合にのみ入力する必要があります) | 234986576 | 文字列 (最大 40 文字) | 必須ではない |
programId | 顧客が参加しているロイヤルティプログラムの識別子、またはロイヤルティプログラムに関連付けられているステータス名 | シルバー ゴールド プラチナ | 文字列 (最大 20 文字) | 必須ではない |
sourceConfirmationId | エクスペディア側の確認識別子 (orderId とも呼ばれる)。利用、返金、無効化の各リクエストで送信され、レスポンスペイロードの一部として、およびデイリーポイントレコンファイルの一部として返送される必要があります。 | 9223371998507503799 | 文字列 (最大 50 文字) | 必須 |
totalproductCost | 予約の合計金額 (小数点以下2桁まで)。ポイントで支払った金額の現金相当額 + 現金またはカードで支払った金額 | 230.09 | 文字列 (最大 10 文字) | 必須 |
PaymentDetails | ロイヤルティ通貨および現金またはカードによる支払いの詳細 (ネストされたフィールドについては PaymentDetails の表を参照) | 必須 |
レスポンス
| フィールド | 説明 | サンプル値 |
|---|---|---|
status | 取引ステータス (値 : Approved または Declined) | Declined |
requestId | 取引リクエストの一意の識別子 (リクエストペイロードから) | a5783c58-c5ce-4ff9-b83c-58c5cedff9 |
transactionDateTime | パートナーシステムに記録されている取引日時 | 2023-04-20T12:01:23.203057Z |
sourceConfirmationId | エクスペディア側からの注文識別子 (orderId とも呼ばれる)。利用、返金、無効化の各リクエストで送信され、レスポンスペイロードとデイリーポイントレコンファイルに含める必要があります。 | 9223371998507503799 |
redemptionDetails | 利用されたロイヤルティアワードの確認 (ネストされた項目については RedemptionDetails の表を参照) | |
DeclineReason | 取引が不承認となった理由 (ネストされた項目については、共通データ DeclineReason の表を参照) | |
reasonMessage | ロギングの向上のために、不承認レスポンスに添えるカスタムメッセージ (ネストされた項目については、共通データ DeclineReason の表を参照) |
PaymentDetails
| フィールド | 説明 | 必須/必須ではない |
|---|---|---|
redemptionDetails | ロイヤルティの利用の詳細 (ネストされた項目については RedemptionDetails の表を参照) | 必須 |
amountPaidInCash | 顧客が予約に対して現金またはカードで支払った金額 (ネストされた項目については、共通データ 金額 の表を参照) | 必須 |
RedemptionDetails
| フィールド | 説明 | サンプル値 | フィールドのタイプと長さ | 必須/必須ではない |
|---|---|---|---|---|
amountPaidInLoyaltyCurrency | 予約に対して支払われたポイント、マイル (またはその他のロイヤルティ通貨) の合計数 (ネストされたフィールドについては、共通データ 金額 の表を参照) | 必須 | ||
redemptionConfirmationId | 利用オペレーションの識別子。エクスペディアからの返金または無効化リクエストで送信されます。また、デイリーポイントレコンレポートでは、利用取引の「パートナー確認 ID」として記載されます。 | expedia-a5783c58-c5ce-4ff9-b83c-58c5cedff988 | 文字列 (最大 50 文字) | 必須 |
loyaltyRedemptionCode | いくつかの実装で要求される利用コード (通常はリクエストに入力される)。ワンタイムパスワードか、必要に応じて商品のためにあらかじめ定義された利用コード | SKU | 文字列 (最大 20 文字) | 必須ではない |
ロールバック
ポイントバンクでロールバック (つまり、ロイヤルティ取引の取り消し。キャンセルまたは無効化とも呼ばれます) を処理するには、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 | 顧客のアカウントで利用可能なポイント、マイル、その他のロイヤルティ通貨の数 (ネストされた項目については、共通データ 金額 の表を参照) |