🔗 API Specification

제휴 포인트 연동
API 구현 스펙

Affiliate Point Integration API Specification

제휴포인트 연동이란 럭키박스 내에서 매체사 앱의 포인트 시스템을 사용하여 럭키박스 구매를 지원하기 위한 API 연동 작업입니다. 제휴 포인트 연동을 위해 ① 제휴포인트 조회 API와 ② 포인트 사용 API를 매체사에서 구현해 주셔야 하며, 최종적으로 매체사 관리자 사이트의 앱설정에서 각 API 주소 설정 및 제휴포인트 지원 여부를 설정해 주셔야 합니다.

HTTP POST HMAC-SHA256 KST 기준 Timeout 3분 orderId 멱등성 보장 역정산 대상

💰 정산(역정산) 안내 반드시 확인

제휴포인트는 역정산 대상이므로, 반드시 현금성 포인트만 연동 가능합니다.

제휴포인트로 판매된 대금은 매체사의 현금(PG) 판매금액에서 마이너스 처리되어 최종 정산금 산출에 반영됩니다.

제휴포인트 판매액의 일정 퍼센트는 현금(PG) 판매분과 동일하게 매체사 몫으로 차감되어 최종 정산금이 산출됩니다.

현금 판매액보다 제휴 포인트 판매액이 많은 경우 정산금이 마이너스(-)가 될 수 있으며, 이 경우 매체사에서 브라보식스로 역정산을 해주셔야 합니다.

정산 내역은 매체사 관리자 사이트의 정산 신청 메뉴에서 확인하실 수 있습니다.

제휴포인트를 통해 결제한 내역은 구매 취소가 지원되지 않습니다.

제휴포인트 연동은 API방식으로 럭키박스를 연동한 경우에만 사용 가능합니다.

①

제휴포인트 조회 API

API 주소	매체사용 관리자 페이지의 앱설정에서 직접 설정해 주세요.
요청 타입	POST
Content-Type	application/x-www-form-urlencoded;charset=UTF-8
API 설명	매체사 이용자의 제휴 포인트 잔액을 조회합니다. 럭키박스 구매 시 결제 수단을 제휴 포인트로 선택한 경우, 이용자의 현재 포인트 잔액과 결제에 필요한 포인트 잔액 표시 등을 위해 호출됩니다.

📥 요청 인자 (Request Parameters)

파라미터명	데이터 타입	설명	비고
userId	string	럭키박스 접속 시 매체사에서 제공한 매체사 이용자의 ID입니다.
requestDateTime	string	YYYYMMDDhhmm 형식의 조회 요청일자(년월일시분) 예) 202604021000	KST 기준
hash	string	요청 유효성 검사를 위한 해시값 userId + requestDateTime를 단순 문자열 합치기 후 매체사 비밀키로 HMAC-SHA256 해싱 (해시 생성 방식은 럭키박스 사이트 접속 시 생성하는 방식과 동일)	아래 예제 참조

📤 API 호출 결과 (Response)

필드명	데이터 타입	설명
result	string	success invalidUser invalidHash invalidRequest failed timeOut success성공 invalidUser이용자 ID 오류 invalidHash해시값 오류 invalidRequest요청 파라미터 오류 failed조회 실패 timeOut요청 시간 초과 (requestDateTime 기준 3분 초과 시) ※ 럭키박스 서버와 매체사 서버의 시간 차이를 감안하여 처리 요망
point	number (int)	이용자의 보유 포인트 success 시에만 포함
cashToPoint	number (double)	현금을 포인트로 변환할 때 참조하는 비율 예) 현금 1000원 → Math.floor(1000 × cashToPoint) 포인트 success 시에만 포함
pointName	string	제휴사 포인트 이름 success 시에만 포함

📄 응답 예시 (JSON) — 응답은 반드시 Content-Type: application/json 형식으로 반환

{
  "result": "success",
  "point": 5000,
  "cashToPoint": 2.0,
  "pointName": "럭키포인트"
}

💻 Node.js — 조회 API 해시 생성 예제

const Crypto = require('crypto');

const appSecret       = '매체사에할당된앱시크릿';
const userId          = '이용자식별자';
const requestDateTime = '202604031030';

const getHash = (key, value) => {
  return Crypto.createHmac('sha256', key)
    .update(value, 'utf8').digest('hex');
};

// hash = HMAC-SHA256(appSecret, userId + requestDateTime)
const hash = getHash(appSecret,
  `${userId}${requestDateTime}`);

②

럭키박스 구매를 위한 제휴포인트 사용 요청 API

API 주소	매체사용 관리자 페이지의 앱설정에서 직접 설정해 주세요.
요청 타입	POST
Content-Type	application/x-www-form-urlencoded;charset=UTF-8
API 설명	럭키박스 구매에 필요한 포인트를 차감 요청합니다.

📥 요청 인자 (Request Parameters)

파라미터명	데이터 타입	설명	비고
userId	string	럭키박스 접속 시 매체사에서 제공한 매체사 이용자의 ID
requestDateTime	string	YYYYMMDDhhmm 형식의 요청일자(년월일시분) 예) 202604021000	KST 기준
hash	string	요청 유효성 검사 해시값 userId + requestDateTime + amount + orderId 순으로 합치기 후 매체사 비밀키로 HMAC-SHA256 해싱	아래 예제 참조
amount	string (max 7)	현금 기준 결제 금액 (단위: 원) 매체사별 현금↔포인트 비율이 다르므로 현금 기준으로 요청하며, 매체사에서 포인트로 변환 후 차감합니다. 포인트 계산 시 발생하는 소숫점 처리는 매체사 정책에 맞게 처리 부탁드리며, 럭키박스 UI 내에서는 필요 포인트 계산 시 소숫점 절사 후 표시합니다.
orderId	string (max 15)	럭키박스 주문 고유번호	중복 요청 방지 키
orderName	string (max 20)	주문 내용 예) 럭키박스 1개 구매

📤 API 호출 결과 (Response)

필드명	데이터 타입	설명
result	string	success invalidUser invalidHash invalidRequest insufficientPoint failed timeOut success성공 invalidUser이용자 ID 오류 invalidHash해시값 오류 invalidRequest요청 파라미터 오류 insufficientPoint포인트 잔액 부족 failed포인트 사용 실패 timeOut요청 시간 초과 (requestDateTime 기준 3분 초과 시)
trId	string	매체사 자체 제휴포인트 사용 이력의 고유번호 ※ 단순 참고용이며, 럭키박스 주문 정보에 함께 기록됩니다.
pointName	string	사용된 포인트의 이름
point	number	실제 사용된 포인트의 양

📄 응답 예시 (JSON) — 응답은 반드시 Content-Type: application/json 형식으로 반환

{
  "result": "success",
  "trId": "매체사_이력_고유번호",
  "point": 2000,
  "pointName": "포인트"
}

📐 포인트 변환 공식

차감 포인트 = Math.floor(amount × cashToPoint) 예) amount=1000원, cashToPoint=2 → Math.floor(1000 × 2) = 2,000 포인트 차감

🔄

재시도 정책 럭키박스 서버는 네트워크 오류 등으로 API 호출이 실패할 경우, 동일 요청을 최대 5회 재전송합니다.
→ 매체사는 orderId 기준으로 중복 처리 여부를 반드시 체크해야 합니다.
→ 이미 처리 완료된 orderId에 대한 재요청은 즉시 success를 리턴해야 합니다.

📅

월별 집계 기준 매체사에서 월별 포인트 사용 이력을 집계할 때는 requestDateTime의 YYYYMM(년월) 기준으로 집계하세요. 요청 수신 시점 기준으로 집계 시 날짜 변동으로 인해 럭키박스 월 집계 정보와 달라질 수 있습니다.

💻 Node.js — 포인트 사용 API 해시 생성 예제

const Crypto = require('crypto');

const appSecret       = '매체사에할당된앱시크릿';
const userId          = '이용자식별자';
const requestDateTime = '202604031030';
const amount          = '1000';
const orderId         = '100';

const getHash = (key, value) => {
  return Crypto.createHmac('sha256', key)
    .update(value, 'utf8').digest('hex');
};

// hash = HMAC-SHA256(appSecret, userId + requestDateTime + amount + orderId)
const hash = getHash(appSecret,
  `${userId}${requestDateTime}${amount}${orderId}`);

③

요청 수신 시 매체사 서버 처리 순서

해시 유효성 검사

요청에 전달된 해시값과 매체사에서 직접 생성한 해시값을 비교합니다.
→ 해시 불일치 시 요청을 무시합니다.

중복 요청 검사

orderId에 해당하는 포인트 사용 이력이 DB에 있는지 확인합니다.
→ 동일 orderId 이력이 있으면 중복 요청이므로, 포인트 차감 없이 즉시 success 리턴 후 종료

⚠ 중복인 경우라도 반드시 success를 리턴해야 합니다.

요청 시간 검사

현재 시간과 요청의 requestDateTime 사이의 경과 시간을 확인합니다.
→ 3분(180초) 이상 경과 시 timeOut을 리턴합니다.

⚠ 단, 중복 요청인 경우(Step 2에서 이미 처리된 orderId)에는 시간 검사 없이 즉시 success를 리턴합니다.

포인트 잔액 확인

신규 요청인 경우, userId의 포인트 잔액(userPoint) 조회
→ amountPoint = Math.floor(amount × 현금대포인트비율)
→ userPoint >= amountPoint 검사 후, 잔액 부족 시 insufficientPoint 리턴

포인트 차감

잔액이 충분하면 amountPoint를 이용자 포인트 잔액에서 차감하고, 이용자에게 표시할 포인트 사용 이력을 기록합니다.

이력 저장 및 성공 응답

럭키박스 포인트 구매 이력을 DB에 저장합니다.
저장 필드: orderId, orderName, userId, amount, amountPoint, requestDateTime
→ DB 저장 이력의 고유번호를 trId로 하여 success 리턴

오류 처리

포인트 사용 중 오류 발생 시 failed를 리턴합니다.
기타 오류는 적절한 리턴값 사용 (invalidUser, invalidRequest, invalidHash 등)

📋

범례

● 필수

필수 파라미터

success / failed

result 필드 리턴값

HMAC-SHA256

해시 알고리즘

KST

Korea Standard Time (UTC+9)

🔒

IP 화이트리스트 설정

럭키박스 서버에서 매체사 API를 호출할 때 사용하는 고정 IP입니다. 매체사 서버의 방화벽 또는 보안 그룹에서 아래 IP를 인바운드 허용(Whitelist) 처리해 주세요.

IP 주소	환경	비고
52.78.196.162	Production
16.184.19.23	Production
119.198.9.10	Test

⚠️

위 IP는 변경될 수 있으며, 변경 시 사전 안내 드립니다. TCP 443 (HTTPS) 포트 허용이 필요합니다.

제휴 포인트 연동API 구현 스펙

제휴포인트 조회 API

럭키박스 구매를 위한 제휴포인트 사용 요청 API

요청 수신 시 매체사 서버 처리 순서

범례

IP 화이트리스트 설정

제휴 포인트 연동
API 구현 스펙