PlayCamp Partner Gateway가 게임 서버와 PlayCamp SDK API 사이에서 인증, 웹훅 변환, 결제 동기화를 중계하는 방식입니다. 게임 서버의 기존 API 규격을 유지하면서 PlayCamp와 연동할 수 있습니다.
Partner Gateway 연동은 PlayCamp 기술 엔지니어의 사전 설정 작업이 필요합니다. 연동 시작 전에 PlayCamp 담당자와 먼저 논의해주세요. 인증 방식, 웹훅 페이로드 형식, 결제 API 연동 규격 등을 사전에 협의해야 합니다.
이 방식이 적합한 경우
- 게임 서버에 이미 자체 API 규격이 있어 PlayCamp 표준 형식으로 변환이 필요한 경우
- 인증 방식이 PlayCamp 표준(Bearer Token)과 다른 경우 (예: SHA256 커스텀 서명)
- 결제 데이터를 게임 서버에서 직접 전송하지 않고, Gateway가 폴링하여 동기화하는 방식을 원하는 경우
- 기존 시스템 변경을 최소화하면서 PlayCamp를 연동하고 싶은 경우
전체 흐름
게임사 개발 작업
| # | 작업 | 담당 | 설명 |
|---|
| 1 | 게임 내 진입점 배치 | 게임 클라이언트 | 후원하기 아이콘/버튼 |
| 2 | 인증 데이터 생성 | 게임 서버 | Gateway 인증용 서명 생성 |
| 3 | Gateway URL 호출 | 게임 클라이언트 | 서명 포함하여 브라우저 오픈 |
| 4 | 웹훅 수신 엔드포인트 | 게임 서버 | Gateway에서 변환된 이벤트 수신 |
| 5 | 결제 조회 API 제공 | 게임 서버 | Gateway가 폴링할 결제 내역 API |
작업 2, 4, 5의 구체적인 규격은 PlayCamp 기술 엔지니어와 사전 협의 시 확정됩니다.
Step 1: WebView 진입 (Gateway 경유)
직접 PlayCamp WebView를 호출하는 대신, Partner Gateway URL을 경유합니다. Gateway가 인증을 검증한 후 PlayCamp WebView로 리다이렉트합니다.
진입 URL
GET https://{gateway-domain}/api/{partner}/sponsor?usn={userId}&camp_code={campaignId}&custom_data={signature}
| 파라미터 | 필수 | 설명 |
|---|
usn | O | 게임 유저 고유 ID |
camp_code | - | PlayCamp 캠페인 ID |
custom_data | O | 인증용 서명 데이터 |
파라미터명(usn, camp_code, custom_data)은 게임사별로 달라질 수 있습니다. 실제 파라미터명은 PlayCamp 기술 엔지니어와 협의 시 확정됩니다.
인증 방식
게임 서버에서 서명 데이터를 생성하여 클라이언트에 전달합니다. 일반적으로 SHA256 기반 서명 + timestamp 만료 검증 방식을 사용합니다.
- 사전에 공유한 비밀키(sharedKey)로 서명 생성
- timestamp 유효 범위 검증으로 리플레이 공격 방지
구체적인 서명 생성 방식과 파라미터 구조는 PlayCamp 기술 엔지니어와 협의 시 제공됩니다.
| HTTP | 설명 |
|---|
| 302 | 인증 성공 → PlayCamp WebView로 리다이렉트 |
| 401 | 인증 실패 (서명 불일치, timestamp 만료 등) |
Step 2: 웹훅 수신 (Gateway → 게임 서버)
유저가 WebView에서 크리에이터를 선택하면, PlayCamp → Gateway → 게임 서버 순서로 이벤트가 전달됩니다. Gateway가 PlayCamp 표준 형식을 게임 서버가 처리할 수 있는 형식으로 변환합니다.
이벤트 종류
| PlayCamp 이벤트 | 게임 서버 전달 |
|---|
sponsor.created | 부스트 등록 (1건) |
sponsor.ended | 부스트 해제 (1건) |
sponsor.changed | 부스트 해제 + 부스트 등록 (2건으로 분할) |
게임 서버가 받는 페이로드 (예시)
{
"events": [
{
"custom_data": "100001|1700000000|a1b2c3d4...",
"usn": 100001,
"creator_usn": 17324966,
"event": "sponsor.created",
"timestamp": 1741588200
}
]
}
페이로드 형식은 게임 서버의 기존 규격에 맞춰 협의합니다. 위 예시는 참고용이며, 실제 필드명과 형식은 사전 협의 시 확정됩니다.
게임 서버 응답
성공 시 HTTP 200과 결과를 반환합니다.
실패 응답 시 Gateway가 자동으로 재시도합니다 (최대 5회, 점진적 간격 증가).
callbackId 활용
WebView 진입 시 전달한 custom_data가 PlayCamp에 callbackId로 저장됩니다. 웹훅 이벤트에 동일한 값이 포함되어 돌아오므로, 게임 서버에서 원래 진입 요청과 웹훅 이벤트를 매칭할 수 있습니다.
Step 3: 결제 동기화 (Gateway가 폴링)
게임 서버가 PlayCamp로 결제를 직접 전송하는 대신, Gateway가 게임 서버의 결제 API를 주기적으로 폴링하여 PlayCamp에 일괄 등록합니다.
게임 서버에서 결제 내역을 조회할 수 있는 API를 제공하면, Gateway가 이를 주기적으로 폴링하여 PlayCamp에 자동 등록합니다.
- 게임 서버 역할: 기간별 결제 내역을 반환하는 조회 API 제공
- Gateway 역할: 게임 서버 응답을 PlayCamp Bulk Payment API 형식으로 자동 변환 및 전송
- 중복 방지: 거래 ID를 기준으로 PlayCamp에서 자동 중복 제거
- 자동 재시도: 전송 실패 시 점진적 간격으로 재시도
결제 조회 API의 엔드포인트, 인증 방식, 요청/응답 형식은 PlayCamp 기술 엔지니어와 협의 시 확정됩니다. 게임 서버의 기존 결제 조회 API가 있다면 해당 규격을 그대로 활용할 수 있습니다.
Step 4: 정산
결제 데이터를 기반으로 월 단위 정산이 진행됩니다.
- 매출 마감 — 매월 말 기준으로 결제 데이터 집계
- 매출 대사 — PlayCamp에서 제공하는 정산 내역과 게임사 내부 데이터 대사
- 정산 입금 — 대사 확인 후 정산 금액 입금
- 크리에이터 정산 — PlayCamp가 크리에이터에게 수익 분배
상세: 정산
| 구간 | 인증 방식 |
|---|
| 게임 클라이언트 → Gateway | SHA256 서명 + timestamp 만료 검증 |
| PlayCamp → Gateway (웹훅) | HMAC-SHA256 서명 검증 |
| Gateway → 게임 서버 (웹훅) | 사전 협의 (게임 서버 자체 검증) |
| Gateway → 게임 서버 (결제 API) | IP 화이트리스트 + SHA256 fingerprint |
| 비밀키 저장 | AES-256-GCM 암호화 |
WebView 직접 연동과의 비교
| 항목 | WebView 직접 연동 | Partner Gateway 연동 |
|---|
| 인증 | PlayCamp 표준 (Bearer Token) | 게임사 기존 방식 유지 가능 |
| 웹훅 형식 | PlayCamp 표준 JSON | 게임 서버 형식으로 변환 |
| 결제 등록 | 게임 서버가 직접 API 호출 | Gateway가 폴링하여 자동 동기화 |
| 게임 서버 변경 | PlayCamp API 호출 로직 추가 | 결제 조회 API만 제공하면 됨 |
| 사전 협의 | 불필요 (문서 기반 셀프 연동) | PlayCamp 기술 엔지니어와 필수 |