> ## Documentation Index
> Fetch the complete documentation index at: https://playcamp.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner Gateway 연동

> PlayCamp Partner Gateway를 통한 중계 방식 연동

PlayCamp Partner Gateway가 게임 서버와 PlayCamp SDK API 사이에서 인증, 웹훅 변환, 결제 동기화를 중계하는 방식입니다. 게임 서버의 기존 API 규격을 유지하면서 PlayCamp와 연동할 수 있습니다.

<Warning>
  Partner Gateway 연동은 PlayCamp 기술 엔지니어의 **사전 설정 작업이 필요**합니다. 연동 시작 전에 PlayCamp 담당자와 먼저 논의해주세요. 인증 방식, 웹훅 페이로드 형식, 결제 API 연동 규격 등을 사전에 협의해야 합니다.
</Warning>

## 이 방식이 적합한 경우

* 게임 서버에 이미 자체 API 규격이 있어 PlayCamp 표준 형식으로 변환이 필요한 경우
* 인증 방식이 PlayCamp 표준(Bearer Token)과 다른 경우 (예: SHA256 커스텀 서명)
* 결제 데이터를 게임 서버에서 직접 전송하지 않고, Gateway가 폴링하여 동기화하는 방식을 원하는 경우
* 기존 시스템 변경을 최소화하면서 PlayCamp를 연동하고 싶은 경우

## 전체 흐름

```mermaid theme={null}
sequenceDiagram
    participant U as 게임 유저
    participant C as 게임 클라이언트
    participant S as 게임 서버
    participant G as Partner Gateway
    participant P as PlayCamp SDK API

    rect rgb(40, 40, 60)
    Note over U,P: 1. WebView 진입 (Gateway 경유)
    U->>C: 후원하기 버튼 터치
    C->>S: 인증 데이터 요청
    S-->>C: 서명 데이터 전달
    C->>G: Gateway URL 호출 (유저ID + 서명)
    G->>G: 서명 검증
    G->>P: OTT 발급
    P-->>G: OTT 반환
    G-->>C: WebView로 리다이렉트
    U->>P: 크리에이터 선택 → 부스트 등록
    end

    rect rgb(40, 60, 40)
    Note over U,P: 2. 웹훅 중계 (Gateway → 게임 서버)
    P-->>G: 웹훅: sponsor.created
    G->>G: 페이로드 변환
    G-->>S: 게임 서버 형식으로 전달
    end

    rect rgb(60, 40, 40)
    Note over U,P: 3. 결제 동기화 (Gateway가 폴링)
    G->>S: 결제 내역 조회 (주기적 폴링)
    S-->>G: 결제 데이터 반환
    G->>P: Bulk 결제 등록
    end

    rect rgb(60, 60, 40)
    Note over U,P: 4. 정산
    Note over P: 월말 정산 → 크리에이터별 수익 계산
    end
```

## 게임사 개발 작업

| # | 작업             | 담당       | 설명                     |
| - | -------------- | -------- | ---------------------- |
| 1 | 게임 내 진입점 배치    | 게임 클라이언트 | 후원하기 아이콘/버튼            |
| 2 | 인증 데이터 생성      | 게임 서버    | Gateway 인증용 서명 생성      |
| 3 | Gateway URL 호출 | 게임 클라이언트 | 서명 포함하여 브라우저 오픈        |
| 4 | 웹훅 수신 엔드포인트    | 게임 서버    | Gateway에서 변환된 이벤트 수신   |
| 5 | 결제 조회 API 제공   | 게임 서버    | Gateway가 폴링할 결제 내역 API |

<Info>
  작업 2, 4, 5의 **구체적인 규격**은 PlayCamp 기술 엔지니어와 사전 협의 시 확정됩니다.
</Info>

***

## 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  | 인증용 서명 데이터      |

<Note>
  파라미터명(`usn`, `camp_code`, `custom_data`)은 게임사별로 달라질 수 있습니다. 실제 파라미터명은 PlayCamp 기술 엔지니어와 협의 시 확정됩니다.
</Note>

### 인증 방식

게임 서버에서 서명 데이터를 생성하여 클라이언트에 전달합니다. 일반적으로 SHA256 기반 서명 + timestamp 만료 검증 방식을 사용합니다.

* 사전에 공유한 비밀키(sharedKey)로 서명 생성
* timestamp 유효 범위 검증으로 리플레이 공격 방지

<Note>
  구체적인 서명 생성 방식과 파라미터 구조는 PlayCamp 기술 엔지니어와 협의 시 제공됩니다.
</Note>

### 응답

| HTTP | 설명                              |
| ---- | ------------------------------- |
| 302  | 인증 성공 → PlayCamp WebView로 리다이렉트 |
| 401  | 인증 실패 (서명 불일치, timestamp 만료 등)  |

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

유저가 WebView에서 크리에이터를 선택하면, PlayCamp → Gateway → 게임 서버 순서로 이벤트가 전달됩니다. Gateway가 PlayCamp 표준 형식을 **게임 서버가 처리할 수 있는 형식**으로 변환합니다.

### 이벤트 종류

| PlayCamp 이벤트      | 게임 서버 전달                  |
| ----------------- | ------------------------- |
| `sponsor.created` | 부스트 등록 (1건)               |
| `sponsor.ended`   | 부스트 해제 (1건)               |
| `sponsor.changed` | 부스트 해제 + 부스트 등록 (2건으로 분할) |

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

```json theme={null}
{
  "events": [
    {
      "custom_data": "100001|1700000000|a1b2c3d4...",
      "usn": 100001,
      "creator_usn": 17324966,
      "event": "sponsor.created",
      "timestamp": 1741588200
    }
  ]
}
```

<Note>
  페이로드 형식은 게임 서버의 기존 규격에 맞춰 협의합니다. 위 예시는 참고용이며, 실제 필드명과 형식은 사전 협의 시 확정됩니다.
</Note>

### 게임 서버 응답

성공 시 HTTP 200과 결과를 반환합니다.

```json theme={null}
{ "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에서 자동 중복 제거
* **자동 재시도**: 전송 실패 시 점진적 간격으로 재시도

<Note>
  결제 조회 API의 엔드포인트, 인증 방식, 요청/응답 형식은 PlayCamp 기술 엔지니어와 협의 시 확정됩니다. 게임 서버의 기존 결제 조회 API가 있다면 해당 규격을 그대로 활용할 수 있습니다.
</Note>

## Step 4: 정산

결제 데이터를 기반으로 월 단위 정산이 진행됩니다.

1. **매출 마감** — 매월 말 기준으로 결제 데이터 집계
2. **매출 대사** — PlayCamp에서 제공하는 정산 내역과 게임사 내부 데이터 대사
3. **정산 입금** — 대사 확인 후 정산 금액 입금
4. **크리에이터 정산** — PlayCamp가 크리에이터에게 수익 분배

> 상세: [정산](/ko/guides/developers/settlement)

## 보안

| 구간                       | 인증 방식                          |
| ------------------------ | ------------------------------ |
| 게임 클라이언트 → 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 기술 엔지니어와 필수** |