🔗 API Specification

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

Affiliate Point Integration API Specification

제휴포인트 연동이란 럭키박스 내에서 매체사 앱의 포인트 시스템을 사용하여 럭키박스 구매를 지원하기 위한 API 연동 작업입니다. 제휴 포인트 연동을 위해 ① 제휴포인트 조회 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) 포인트 예) pointName이 '캐시'이고 1캐시의 현금가치가 0.5원이라 가정할 때 cashToPoint = 1 / 0.5 = 2이며, 이 경우 캐시로 럭키박스 1,000원 1개를 구매 시 필요한 캐시 = 1,000원 × cashToPoint = 2,000캐시 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 내에서는 필요 포인트 계산 시 소숫점 절사 후 표시합니다. cashToPoint = 현금 1원에 대한 포인트 배율 (예: 1포인트가 0.5원의 가치인 경우 cashToPoint = 1 / 0.5 = 2)	차감 포인트 = amount × cashToPoint
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	요청 파라미터의 amount를 제휴포인트 값으로 변환하여 실제 차감한 값 ※ 제휴 포인트 구매의 취소 요청 시에 그대로 전달됩니다.

📄 응답 예시 (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 등)

③

제휴 포인트 사용 취소 API

이용자가 제휴 포인트를 통해 구매한 럭키박스를 주문 취소하는 경우, 제휴 포인트 사용 취소 요청이 전송됩니다.

📌

럭키박스 구매 취소 가능 조건 ① 구매일로부터 7일 이내
② 구매한 럭키박스를 사용하지 않은 경우
→ 럭키박스 구매 취소가 발생하는 경우 당월 정산 데이터에 해당 취소 내역 및 정산 금액이 반영됩니다.

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

📥 요청 인자 (Request Parameters)

파라미터명	데이터 타입	설명	비고
userId	string	럭키박스 접속 시 매체사에서 제공한 매체사 이용자의 ID
trId	string	제휴 포인트 사용 당시 매체사가 보내준 포인트 사용 이력 고유번호	중복 취소 방지 키
amount	string	취소되는 금액 (단위: 원)
point	string	제휴 포인트 사용 당시 실제 사용된 포인트의 양 제휴 포인트를 사용하여 구매할 당시 실제 차감된 포인트의 양입니다. 이 값을 이용자에게 다시 지급해 주시면 됩니다.
requestDate	string	YYYYMMDD 형식의 취소 요청일자(년월일)	KST 기준
hash	string	요청 유효성 검사 해시값 userId + trId + amount + point을 단순 문자열 합치기 후 매체사 비밀키로 HMAC-SHA256 해싱	requestDate 미포함

📤 API 호출 결과 (Response)

필드명	데이터 타입	설명
result	string	success invalidUser invalidHash invalidRequest duplicated failed success성공 invalidUser이용자 ID 오류 invalidHash해시값 오류 invalidRequest요청 파라미터 오류 duplicated이미 환불 처리 완료 failed포인트 환불 실패

🔄

취소 처리 순서 및 중복 요청 처리 럭키박스 서버는 이용자가 구매 취소를 요청하는 경우 조건을 판단하여 환불이 가능한 경우 먼저 제휴 포인트 취소 요청을 보내며, 취소 요청 성공 시에 이후 주문 취소가 처리됩니다.
럭키박스 서버와 매체사 서버 간 통신 오류 등으로 실제 매체사 서버에서는 취소되었지만 럭키박스 서버가 성공 결과를 받지 못하는 경우가 있을 수 있습니다.
→ 이런 경우를 줄이기 위해 럭키박스 서버는 같은 요청을 여러 번 보낼 수 있으므로, 이미 취소 완료 처리한 건에 대해서는(trId 기준) duplicated를 리턴해서 럭키박스 서버가 취소 절차를 마무리할 수 있게 처리 부탁드립니다.

📋

범례

● 필수

필수 파라미터

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

포인트 사용 요청 수신 시 매체사 서버 처리 순서

제휴 포인트 사용 취소 API

범례

IP 화이트리스트 설정

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