포인트 뱅크 API
고객이 적립한 포인트를 활용해 여행을 예약할 수 있도록 합니다
화이트 라벨 여행 플랫폼 사이트를 귀사의 로열티 프로그램과 연동하여 로열티 포인트를 적립하거나 사용(또는 둘 다)할지 여부는 귀하가 결정합니다. 귀사의 로열티 프로그램은 템플릿 사이트에서 이루어진 구매를 포함하여, 어떤 구매가 로열티 화폐(프로그램에서 포인트, 달러 등 어떤 형태로든 제공되는 것)를 적립할 수 있는 대상인지 정의합니다. 템플릿 사이트에서 누적된 적립금을 여행 예약에 사용하도록 허용할 수도 있습니다.
고객은 적립된 로열티 포인트를 두 가지 방법 중 하나로 사용할 수 있습니다. 하나는 귀사의 템플릿 사이트를 통해 직접 사용하는 것이고, 다른 하나는 전화로 ‘ Expedia ’ 상담원과 상담하여 사용하는 것입니다. 포인트 뱅크 API를 통해 고객은 다음과 같은 기능을 이용할 수 있습니다:
- 적립된 로열티 통화 사용
- 여행 상품 구매 롤백(취소 또는 무효화라고도 함)
- 취소된 여행 계획에 대한 로열티 총액의 전액 또는 부분 환불 받기
- 로열티 계정 잔액 확인
>> 자세한 내용은 ‘공통 데이터 및 응답’ 페이지를 참조하십시오.
템플릿 사이트의 헤더에 고 객의 로열티 잔액을 표시할 수 있습니다. 하지만 API 호출은 페이지 로드 시 발생하므로 표시된 포인트는 페이지를 새로고침할 때까지 업데이트되지 않습니다. 즉, 다른 로열티 사용이 반영되지 않을 수 있습니다.
포인트 뱅크 API에는 로열티 통화의 사용, 롤백 및 환불을 처리하는 엔드포인트가 있습니다. 또한 계정 잔액 엔드포인트를 호출할 수 있습니다. 정확성을 위해 이 API는 거래 시점에 쿼리되어야 합니다. 각 엔드포인트는 아래 탭에 자세히 설명되어 있으며, 모든 엔드포인트(및 계정 잔액 엔드포인트)는 동일한 헤더 필드를 공유합니다.
헤더 변수
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
partnerId | Expedia에서 제공하는 비즈니스의 고유 식별자 | 파트너사의 브랜드 | String, 최대 20자 | 예 |
Authorization | Expedia가 승인 서버로부터 받은 액세스 토큰을 팀에서 검증함 | 표준 JSON 웹 토큰(JWT) | String, 표준 JWT 길이 | — |
Authorization2 | Expedia에서 전송한 JSON 웹 토큰(JWT), 파트너사 측에서 서명 및 클레임을 검증함 | 표준 JWT | String, 표준 JWT 길이 | — |
>> 페이로드에 대한 자세한 내용은 샘플 요청 및 응답 페이지를 확인해 주세요
사용
이 one-step 커밋 절차를 통해 고객은 포인트 뱅크를 이용하여 로열티 리워드를 사용할 수 있습니다 POST /redeem.
요청
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
requestId | 거래 요청의 고유 식별자 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, 최대 40자 | 예 |
membershipId | SSO를 통해 수신된 고유 고객 식별자 | a6fgju7he1bf | String, 최대 40자 | 예 |
loyaltyAccountNumber | 고객의 로열티 계정 번호( programAccountNumber 라고도 함); | 234986576 | String, 최대 40자 | — |
programId | 고객이 가입한 로열티 프로그램의 식별자 또는 로열티 프로그램과 관련된 등급 이름 | Silver Gold Platinum | String, 최대 20자 | — |
sourceConfirmationId | Expedia 측의 확인 식별자(orderId라고도 함). 이는 사용, 환불 및 무효화 요청으로 전송되며 응답 페이로드의 일부이자 일일 포인트 조정 파일의 일부로 다시 전송되어야 합니다. | 9223371998507503799 | String, 최대 50자 | 예 |
itineraryId | 예약은ItineraryId 에서 하실 수 있습니다. | 7610133766295 | String, 최대 20자 | — |
totalproductCost | 총 예약 비용(소수점 이하 두 자리까지). 포인트로 결제한 금액 + 현금 또는 카드로 결제한 금액에 해당하는 현금 등가물과 동일합니다. | 230.09 | String, 최대 10자 | 예 |
PaymentDetails | 로열티 포인트 및 현금 또는 카드 결제 정보; 대상에 대한 자세한 내용은 아래 ‘ PaymentDetails ’ 섹션을 참조해 주십시오. | 예 | ||
pointsPurchaseDetails | 포인트 구매 시에만 필요합니다. 객체에 대한 자세한 내용은 아래 ‘ PointsPurchaseDetails ’ 섹션을 참조해 주십시오. | — |
응답
| 필드 | 설명 | 샘플 값 |
|---|---|---|
status | 거래 상태(값: Approved 또는 Declined) | Declined |
requestId | 거래 요청의 고유 식별자(요청 페이로드부터) | a5783c58-c5ce-4ff9-b83c-58c5cedff9 |
transactionDateTime | 파트너 시스템에 기록된 거래 날짜 및 시간 | 2023-04-20T12:01:23.203057Z |
sourceConfirmationId | Expedia 측의 주문 식별자(orderId라고도 함). 사용, 환불 및 무효화 요청으로 전송되었으며 응답 페이로드와 일일 포인트 조정 파일에 포함되어야 합니다. | 9223371998507503799 |
redemptionDetails | 사용된 로열티 보상 확인; 대상에 대한 자세한 내용은 아래 ‘ RedemptionDetails ’ 섹션을 참조해 주십시오. |   |
DeclineReason | 거래가 거부된 이유; 개체에 대한 자세한 내용은 ‘ DeclineReason ’ 테이블의 공통 데이터를 참조하십시오. |
PaymentDetails
| 필드 | 설명 | 필수 여부 |
|---|---|---|
redemptionDetails | 로열티 적립 및 사용에 대한 상세 정보: 상품에 대한 자세한 내용은 아래 ‘ RedemptionDetails ’ 섹션을 참조해 주십시오. | 예 |
amountPaidInCash | 고객이 예약 대금을 현금 또는 카드로 지불한 금액입니다. 객체에 대한 자세한 내용은 공통 데이터 Amount 테이블을 참조하십시오. | 예 |
RedemptionDetails
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
amountPaidInLoyaltyCurrency | 예약에 사용된 총 포인트, 마일리지(또는 기타 로열티 포인트) 수; 중첩된 필드에 대해서는 공통 데이터 Amount 테이블을 참조하십시오. | 예 | ||
redemptionConfirmationId | 사용 작업을 위한 식별자. Expedia에서 환불 또는 무효화 요청으로 전송되며, 사용 거래를 위해 "파트너 확인 ID"로 일일 포인트 조정 보고서에 채워져야 합니다. | expedia-a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, 최대 50자 | 예 |
loyaltyRedemptionCode | 일부 구현에 필요한 사용 코드(일반적으로 요청에 채워짐). 필요한 경우 상품에 대한 일회성 암호 또는 사전 정의된 사용 코드입니다. | SKU | String, 최대 20자 | — |
promotionId | PromotionId (사용 요청에 연결된 프로모션 ID가 있는 경우) | String, 최대 50자 | — |
PointsPurchaseDetails
| 필드 | 설명 | 필수 여부 |
|---|---|---|
pointsPurchaseValue | 그리드 가격을 적용하여 예약하기 위해 구매해야 하는 총 포인트 수; 객체 세부 정보는 ‘ Amount ’ 공통 데이터 테이블을 참조하십시오. | 예 |
amountPaidForPointsPurchase | 필요한 포인트를 구매하기 위해 지불한 총 현금 금액. 이 값은 또한 basePriceForPointsPurchase + taxesAndFeesForPointsPurchase 입니다. 중첩된 항목에 대해서는 공통 데이터 Amount 테이블을 참조하십시오. | 예 |
basePriceForPointsPurchase | 구매할 포인트의 기본 가격. 예를 들어, 구매할 포인트가 2000포인트이고, 포인트당 $0.02 에 구매할 경우, 기본 가격은 $40; 가 됩니다. 중첩된 항목에 대해서는 Amount 테이블의 공통 데이터를 참조하십시오. | — |
taxesAndFeesForPointsPurchase | 포인트 구매 시 기본 가격에 적용되는 세금 및 수수료(해당하는 경우); 중첩된 항목에 대해서는 ‘ Amount ’ 표의 공통 데이터를 참조하십시오. | — |
롤백
포인트 뱅크에서 롤백(로열티 거래 취소, 취소 또는 무효화라고도 함)을 처리하려면 POST /rollback 엔드포인트를 사용합니다.
이 API는 사용 작업이 성공했지만 공급 실패 등의 이유(예: 고객이 예약을 시도하는 동안 호텔이 매진됨)로 인해 Expedia가 이를 취소해야 할 때 트리거됩니다. 이는 사용을 롤백하는 것이므로 로열티 적립금을 다시 사용할 수 있으려면 조정이 필요합니다.
참고: 일일 포인트 조정 보고서에는 사용 거래 또는 롤백 거래는 모두 포함되어서는 안 됩니다.
요청
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
requestId | 거래 요청의 고유 식별자 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, 최대 40자 | 예 |
membershipId | 귀사의 로열티 프로그램에 등록된 고객의 고유 식별자 | a6fgju7he1bf | String, 최대 40자 | 예 |
sourceConfirmationId | Expedia 측의 주문 식별자(orderId라고도 함). 사용, 환불 및 무효화 요청으로 전송되었으며 응답 페이로드와 일일 포인트 조정 파일에 포함되어야 합니다. | 9223371998507503799 | String, 최대 50자 | 예 |
CancellationDetails | 롤백 거래에 대한 세부 정보. 중첩된 항목은 CancellationDetails 표를 참조해 주세요. |
응답
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
status | 취소 성공 여부를 나타내는 롤백 거래 상태(값: Approved 또는 Declined) | Approved | String | 예 |
requestId | 거래 요청의 고유 식별자(요청 페이로드부터) | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, 최대 40자 | 예 |
transactionDateTime | 시스템에 기록된 거래 날짜 및 시간 | 2023-04-20T12:01:23.203057Z | String, 최대 40자 | 예 |
sourceConfirmationId | Expedia 측의 주문 식별자(orderId라고도 함). 사용, 환불 및 무효화 요청으로 전송되었으며 응답 페이로드와 일일 포인트 조정 파일에 포함되어야 합니다. | 9223371998507503799 | String, 최대 50자 | 예 |
CancellationDetails | 롤백 거래에 대한 세부 정보(status 값이 Approved인 경우 필수). 중첩된 항목은 CancellationDetails 표를 참조해 주세요. | |||
Balance | 고객 계정에 적립된 포인트, 마일리지 또는 기타 로열티 포인트의 수; 중첩된 항목에 대해서는 공통 데이터 Amount 테이블을 참조하십시오. | |||
DeclineReason | 거래가 거부된 이유; 중첩된 항목에 대해서는 ‘ DeclineReason ’ 테이블의 공통 데이터를 참조하십시오. | |||
reasonMessage | 거절 응답과 함께 표시될 사용자 지정 메시지; 중첩된 항목에 대해서는 공통 데이터 DeclineReason 테이블을 참조하십시오. |
>> ‘Amount’에 대해 자세히 알아보기
>> #에 대해 자세히 알아보기 >>DeclineReason
CancellationDetails
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
redemptionConfirmationId | 사용을 위한 확인 식별자. 사용 응답으로 전송되고, 롤백된 경우 일일 포인트 보고서에 채워져서는 안 됩니다. | a5783c58-c5ce-4ff9-b83c-58c5cedff991 | String, 최대 50자 | 예 |
cancellationConfirmationId | 롤백 작업을 위한 확인 식별자(status 값이 Approved인 경우 필수). 일일 포인트 보고서에 채워져서는 안 됩니다. | a5783c58-c5ce-4ff9-b83c-58c5cedff993 | String, 최대 50자 | — |
환불
이 API는 POST /refund를 통해 포인트 뱅크에 대한 로열티 환불을 처리하는 데 사용됩니다. 이는 고객이 이미 로열티 적립금을 사용하여 예약한 후 요금제를 취소해야 할 때 트리거됩니다. 로열티 적립금에 대한 환불이므로 고객 계정에서 환불된 통화를 사용하려면 먼저 조정이 필요합니다.
요청
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
requestId | 환불 요청의 고유 식별자 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, 최대 40자 | 예 |
membershipId | 고유 고객 식별자 | a6fgju7he1bf | String, 최대 40자 | 예 |
sourceConfirmationId | Expedia 측의 주문 식별자(orderId라고도 함). 사용, 환불 및 무효화 요청으로 전송되었으며 응답 페이로드와 일일 포인트 조정 파일에 포함되어야 합니다. | 9223371998507503799 | String, 최대 50자 | 예 |
RefundDetails | 환불 거래에 대한 세부 정보. 중첩된 항목은 RefundDetails 표를 참조해 주세요. |
응답
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
status | 환불 상태(값: Approved 또는 Declined) | Approved | String | 예 |
requestId | 환불 요청의 고유 식별자(요청 페이로드부터) | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, 최대 40자 | 예 |
transactionDateTime | 시스템에 기록된 거래 날짜 및 시간 | 2023-04-20T12:01:23.203057Z | String, 최대 40자 | 예 |
sourceConfirmationId | Expedia 측의 주문 식별자(orderId라고도 함). 사용, 환불 및 무효화 요청으로 전송되었으며 응답 페이로드와 일일 포인트 조정 파일에 포함되어야 합니다. | 9223371998507503799 | String, 최대 50자 | 예 |
RefundDetails | 환불 요청에 대한 세부 정보. 중첩된 항목은 RefundDetails 표를 참조해 주세요. | |||
Balance | 고객 계정에 적립된 포인트, 마일리지 또는 기타 로열티 포인트의 수; 중첩된 항목에 대해서는 공통 데이터 ‘Amount’ 테이블을 참조하십시오. | |||
DeclineReason | 거래가 거부된 이유; 중첩된 항목에 대해서는 ‘ DeclineReason ’ 테이블의 공통 데이터를 참조하십시오. | |||
reasonMessage | 거부 응답에 수반되는 사용자 지정 메시지. 일반적인 데이터 DeclineReason 표를 참조해 주세요. |
>> Amount에 대해 자세히 알아보기
>> #에 대해 자세히 알아보기 >>DeclineReason
RefundDetails
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
loyaltyRefundAmount | 환불된 포인트, 마일리지 또는 기타 모든 로열티 포인트의 총 수; 중첩된 항목에 대해서는 ‘ Amount ’의 공통 데이터 표를 참조하십시오. | |||
redemptionConfirmationId | 사용 작업의 식별자. 사용 응답으로 전송되었습니다. | a5783c58-c5ce-4ff9-b83c-58c5cedff918 | String, 최대 50자 | 예 |
refundConfirmationId | 환불 작업을 위한 식별자. Expedia에서 환불 또는 무효화 요청으로 전송되며, 환불 거래를 위해 "파트너 확인 ID"로 일일 포인트 조정 파일에 채워져야 합니다. | a324554f03-c5ce-4ff9-b83c-58c5cedff988 | String, 최대 50자 | — |
계정 잔액
고객의 로열티 계정 잔액을 가져오려면 POST /balance 엔드포인트를 사용합니다.
요청
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
requestId | 거래 요청의 고유 식별자 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, 최대 40자 | 예 |
membershipId | 귀사의 로열티 프로그램에 등록된 고객의 고유 식별자 | a6fgju7he1bf | String, 최대 40자 | 예 |
loyaltyAccountNumber | 고객의 로열티 계정 번호(programAccountNumber라고도 함). 이는 로열티 작업에 membershipId 외의 식별자가 필요한 경우에만 채워져야 합니다. | 234986576 | String, 최대 40자 | — |
programId | 고객이 가입한 로열티 프로그램의 식별자 또는 로열티 프로그램과 관련된 등급 이름 | Platinum | String, 최대 20자 | — |
응답(성공)
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
requestId | 거래 요청의 고유 식별자 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, 최대 40자 | 예 |
Balance | 고객 계정에 적립된 포인트, 마일리지 또는 기타 로열티 포인트의 수; 중첩된 항목에 대해서는 공통 데이터 Amount 테이블을 참조하십시오. |