Partner Gateway 연동

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과 결과를 반환합니다.

{ "result": "OK" }

실패 응답 시 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 기술 엔지니어와 필수

플랫폼

개발사 가이드

크리에이터 가이드

이 방식이 적합한 경우

전체 흐름

게임사 개발 작업

Step 1: WebView 진입 (Gateway 경유)

진입 URL

인증 방식

응답

Step 2: 웹훅 수신 (Gateway → 게임 서버)

이벤트 종류

게임 서버가 받는 페이로드 (예시)

게임 서버 응답

callbackId 활용

Step 3: 결제 동기화 (Gateway가 폴링)

Step 4: 정산

보안

WebView 직접 연동과의 비교

​이 방식이 적합한 경우

​전체 흐름

​게임사 개발 작업

​Step 1: WebView 진입 (Gateway 경유)

​진입 URL

​인증 방식

​응답

​Step 2: 웹훅 수신 (Gateway → 게임 서버)

​이벤트 종류

​게임 서버가 받는 페이로드 (예시)

​게임 서버 응답

​callbackId 활용

​Step 3: 결제 동기화 (Gateway가 폴링)

​Step 4: 정산

​보안

​WebView 직접 연동과의 비교

이 방식이 적합한 경우

전체 흐름

게임사 개발 작업

Step 1: WebView 진입 (Gateway 경유)

진입 URL

인증 방식

응답

Step 2: 웹훅 수신 (Gateway → 게임 서버)

이벤트 종류

게임 서버가 받는 페이로드 (예시)

게임 서버 응답

callbackId 활용

Step 3: 결제 동기화 (Gateway가 폴링)

Step 4: 정산

보안

WebView 직접 연동과의 비교