Cashback Postback Integration API Specification
캐시백은 이용자가 럭키박스 구매 시 일정 금액을 매체사 이용자에게 포인트로 되돌려 주는 것을 말합니다. 매체사 수익 금액의 일정 퍼센트를 이용자에게 캐시백하며, 구매 발생 시 캐시백 금액을 적립하고 구매 취소 발생 시 회수 처리합니다. 캐시백이 가능하려면 아래 스펙에 따라 캐시백 연동 API를 구현해 주셔야 하며, 이후 매체사 관리자 페이지 앱목록에서 캐시백 관련 설정을 진행해 주셔야 합니다.
cashbackAmount는 원(₩) 단위이므로, 매체사 앱의 현금 대 포인트 변환 비율에 따라 포인트로 변환한 뒤 지급 또는 회수해야 합니다.| 파라미터명 | 데이터 타입 | 설명 | 비고 |
|---|---|---|---|
| pbId | string | 캐시백 리워드 고유번호. 중복 지급 확인용으로 사용합니다. | 최대 24자 |
| rewardDate | string | 리워드가 발생한 일자. YYYYMMDD 형식의 숫자(년월일 조합)입니다. | YYYYMMDD |
| rewardTime | string | 리워드가 발생한 시간. 유닉스 타임스탬프 값(밀리초 단위)입니다. Node.js 예) const t = new Date(rewardTime) 형태로 사용 가능 |
Unix ms |
| userId | string | 캐시백을 받을 이용자 ID. 럭키박스 주소 획득 시 제공된 이용자 ID입니다. | |
| postbackType | string |
구매/취소 구분값입니다.
0 구매 → 지급
1 구매취소 → 회수
구매인 경우 cashbackAmount만큼 지급, 구매취소인 경우 동일 금액을 회수합니다.
|
|
| count | string | 구매 또는 취소된 개수입니다. | |
| payType | string |
결제 수단입니다.
0 카드
1 가상계좌
3 제휴포인트
|
|
| totalAmount | string | 총 결제 금액입니다. | 단위 "원" |
| fee | string | 매체사 수수료. 구매/취소 시 매체사에 지급/회수되는 금액입니다. | |
| feeRate | string | 구매 당시 매체사 수수료율(백분율)입니다. | 백분율 % |
| cashbackAmount | string | 이용자에게 지급/회수해야 하는 금액입니다. 구매인 경우 지급, 구매취소인 경우 해당 금액만큼 회수합니다. 원 단위이므로, 매체사 앱의 현금 대 포인트 변환 비율에 따라 포인트로 변환 후 지급/회수 |
단위 "원" |
| cashbackRate | string | 매체사에서 설정한 캐시백 비율(백분율). 매체사 fee에 대해 cashbackRate 비율만큼 캐시백됩니다. | 백분율 % |
| hash | string | 포스트백 유효성 검증값(HMAC-SHA256 기반 해시). pbId + userId + cashbackAmount를 단순 문자열로 합친 뒤 HMAC-SHA256으로 해시하여 생성합니다. 비밀키는 매체사 앱에서 확인 가능하며, 생성 방식은 기존 사이트 접속정보 조회 시 해시 생성 방식과 동일합니다. |
아래 예제 참조 |
const crypto = require('crypto'); // 비밀키는 매체사 앱 설정에서 확인 가능 const secretKey = '<매체사 비밀키>'; // pbId + userId + cashbackAmount 단순 문자열 결합 const message = pbId + userId + cashbackAmount; const expected = crypto .createHmac('sha256', secretKey) .update(message) .digest('hex'); // 요청의 hash 와 다르면 포스트백을 무시 if (expected !== req.body.hash) return ignore();
JSON 형태로, 반드시 20x HTTP 상태로 반환해야 합니다. 다른 에러 코드로 리턴되는 경우 모두 요청 실패로 가정합니다.| 필드명 | 데이터 타입 | 설명 |
|---|---|---|
| result | string |
아래 값 중 하나입니다.
success
failed
userNotFound
duplicated
success요청 처리 성공
failed요청 처리 실패 (재전송 대상)
userNotFound해당 이용자가 존재하지 않음
duplicated이미 처리된 포스트백
|
| result | 의미 | 럭키박스 서버의 처리 |
|---|---|---|
| success | 요청 처리가 성공했습니다. | 포스트백 전송을 성공 처리하고 종료합니다. |
| failed | 요청 처리가 실패했습니다. | 같은 포스트백을 일정 간격으로 최대 10회 재시도합니다. |
| userNotFound | 해당 이용자가 존재하지 않습니다. | 이용자 없음 처리 후 포스트백 전송을 종료합니다. |
| duplicated | 이미 해당 포스트백이 처리되었습니다. | 포스트백 전송을 성공 처리하고 종료합니다. |
{ "result": "success" }
포스트백 수신 엔드포인트에서는 다음 순서대로 처리가 필요합니다.
hash를 비교합니다.userId에 해당하는 이용자가 존재하는지 확인합니다.{ result: "userNotFound" }를 리턴합니다.
pbId와 일치하는 처리 내역이 이미 있는지 확인합니다.{ result: "duplicated" }를 리턴합니다.
postbackType에 따라 userId 이용자에게 처리합니다.0): cashbackAmount만큼 지급 / 구매취소(1): 동일 금액 회수cashbackAmount는 원 단위이므로, 앱의 현금 대 포인트 비율에 따라 포인트로 변환하여 지급/회수합니다.
{ result: "success" }를 리턴합니다.
{ result: "failed" }를 리턴합니다.failed와 동일하게 처리합니다.