포인트 뱅크 API
고객이 로열티 적립금을 여행 예약에 사용할 수 있도록 지원
로열티 통화를 적립하거나 사용하기 위해(또는 둘 다) 화이트 레이블 템플릿 사이트를 로열티 프로그램에 연결할지 여부를 선택할 수 있습니다. 로열티 프로그램은 템플릿 사이트의 로열티를 포함하여 로열티 통화(포인트, 달러 등 프로그램에서 사용하는 모든 형태)를 적립할 수 있는 고객의 구매를 정의합니다. 템플릿 사이트에서 누적된 적립금을 여행 예약에 사용하도록 허용할 수도 있습니다.
고객은 두 가지 옵션, 즉 템플릿 사이트를 통해 직접 로열티 적립금을 사용하거나 Expedia 상담원을 통해 전화로 로열티 적립금을 사용할 수 있습니다. 포인트 뱅크 API를 사용하면 고객은 다음을 수행할 수 있습니다.
- 적립된 로열티 통화 사용
- 여행 상품 구매 롤백(취소 또는 무효화라고도 함)
- 취소된 여행 계획에 대한 로열티 총액의 전액 또는 부분 환불 받기
- 로열티 계정 잔액 확인
자세한 내용은 일반적인 데이터 및 응답 페이지를 참조해 주세요.
템플릿 사이트의 헤더에 고객의 로열티 잔액을 표시할 수 있습니다. 하지만 API 호출은 페이지 로드 시 발생하므로 표시된 포인트는 페이지를 새로고침할 때까지 업데이트되지 않습니다. 즉, 다른 로열티 사용이 반영되지 않을 수 있습니다.
포인트 뱅크 API에는 로열티 통화의 사용, 롤백 및 환불을 처리하는 엔드포인트가 있습니다. 또한 계정 잔액 엔드포인트를 호출할 수 있습니다. 정확성을 위해 이 API는 거래 시점에 쿼리되어야 합니다. 각 엔드포인트는 아래 탭에 자세히 설명되어 있으며, 모든 엔드포인트(및 계정 잔액 엔드포인트)는 동일한 헤더 필드를 공유합니다.
헤더 변수
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
partnerId | Expedia에서 제공하는 비즈니스의 고유 식별자 | 파트너사의 브랜드 | String, 최대 20자 | 예 |
Authorization | Expedia가 승인 서버로부터 받은 액세스 토큰을 팀에서 검증함 | 표준 JSON 웹 토큰(JWT) | String, 표준 JWT 길이 | 아니요 |
Authorization2 | Expedia에서 전송한 JSON 웹 토큰(JWT), 파트너사 측에서 서명 및 클레임을 검증함 | 표준 JWT | String, 표준 JWT 길이 | 아니요 |
페이로드 세부 정보는 샘플 요청 및 응답 페이지를 확인해 주세요.
사용
이 단일 단계 커밋 프로세스를 통해 고객은 POST /redeem을 사용하여 포인트 뱅크를 통해 로열티 리워드를 사용할 수 있습니다.
요청
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
requestId | 거래 요청의 고유 식별자 | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, 최대 40자 | 예 |
membershipId | SSO를 통해 수신된 고유 고객 식별자 | a6fgju7he1bf | String, 최대 40자 | 예 |
loyaltyAccountNumber | 고객의 로열티 계정 번호(programAccountNumber라고도 함). 이는 로열티 작업에 membershipId 외의 식별자가 필요한 경우에만 채워져야 합니다. | 234986576 | String, 최대 40자 | 아니요 |
programId | 고객이 가입한 로열티 프로그램의 식별자 또는 로열티 프로그램과 관련된 등급 이름 | Silver Gold Platinum | String, 최대 20자 | 아니요 |
sourceConfirmationId | Expedia 측의 확인 식별자(orderId라고도 함). 이는 사용, 환불 및 무효화 요청으로 전송되며 응답 페이로드의 일부이자 일일 포인트 조정 파일의 일부로 다시 전송되어야 합니다. | 9223371998507503799 | String, 최대 50자 | 예 |
totalproductCost | 총 예약 비용(소수점 이하 두 자리까지). 포인트로 결제한 금액 + 현금 또는 카드로 결제한 금액에 해당하는 현금 등가물과 동일합니다. | 230.09 | String, 최대 10자 | 예 |
PaymentDetails | 로열티 통화 및 현금 또는 카드 결제 정보. 중첩된 필드는 PaymentDetails 표를 참조해 주세요. | 예 |
응답
| 필드 | 설명 | 샘플 값 |
|---|---|---|
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 표를 참조해 주세요. | |
reasonMessage | 더 나은 로깅을 위한 거부 응답에 수반되는 사용자 지정 메시지. 중첩된 항목은 일반적인 데이터 DeclineReason 표를 참조해 주세요. |
PaymentDetails
| 필드 | 설명 | 필수 여부 |
|---|---|---|
redemptionDetails | 로열티 사용의 세부 정보. 중첩된 항목은 RedemptionDetails 표를 참조해 주세요. | 예 |
amountPaidInCash | 고객이 현금 또는 카드로 예약을 결제한 금액. 중첩된 항목은 일반적인 데이터 금액 표를 참조해 주세요. | 예 |
RedemptionDetails
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
amountPaidInLoyaltyCurrency | 예약을 위해 결제한 총 포인트, 마일(또는 기타 로열티 통화). 중첩된 필드는 일반적인 데이터 금액 표를 참조해 주세요. | 예 | ||
redemptionConfirmationId | 사용 작업을 위한 식별자. Expedia에서 환불 또는 무효화 요청으로 전송되며, 사용 거래를 위해 "파트너 확인 ID"로 일일 포인트 조정 보고서에 채워져야 합니다. | expedia-a5783c58-c5ce-4ff9-b83c-58c5cedff988 | String, 최대 50자 | 예 |
loyaltyRedemptionCode | 일부 구현에 필요한 사용 코드(일반적으로 요청에 채워짐). 필요한 경우 상품에 대한 일회성 암호 또는 사전 정의된 사용 코드입니다. | SKU | String, 최대 20자 | 아니요 |
롤백
포인트 뱅크에서 롤백(로열티 거래 취소, 취소 또는 무효화라고도 함)을 처리하려면 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 | 고객 계정에서 사용 가능한 포인트, 마일 또는 기타 로열티 통화. 중첩된 항목은 일반적인 데이터 금액 표를 참조해 주세요. | |||
DeclineReason | 거래가 거부된 이유. 중첩된 항목은 일반적인 데이터 DeclineReason 표를 참조해 주세요. | |||
reasonMessage | 거부 응답에 수반되는 사용자 지정 메시지. 중첩된 항목은 일반적인 데이터 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 | 고객 계정에서 사용 가능한 포인트, 마일 또는 기타 로열티 통화. 중첩된 항목은 일반적인 데이터 금액 표를 참조해 주세요. | |||
DeclineReason | 거래가 거부된 이유. 중첩된 항목은 일반적인 데이터 DeclineReason 표를 참조해 주세요. | |||
reasonMessage | 거부 응답에 수반되는 사용자 지정 메시지. 일반적인 데이터 DeclineReason 표를 참조해 주세요. |
RefundDetails
| 필드 | 설명 | 샘플 값 | 필드 유형 및 길이 | 필수 여부 |
|---|---|---|---|---|
loyaltyRefundAmount | 환불한 총 포인트, 마일 또는 기타 로열티 통화. 중첩된 항목은 일반적인 데이터 금액 표를 참조해 주세요. | |||
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 | 고객 계정에서 사용 가능한 포인트, 마일 또는 기타 로열티 통화. 중첩된 항목은 일반적인 데이터 금액 표를 참조해 주세요. |