개요 - Playcamp Docs

아키텍처

PlayCamp SDK API는 게임 서버를 통해 연동됩니다.

역할 분담

구성 요소	역할
게임 클라이언트	유저 인터페이스 (크리에이터 선택 UI, 쿠폰 입력 화면 등)
게임 서버	API 호출, 비즈니스 로직 처리, Server Key 보관
PlayCamp SDK API	데이터 저장, 정산 계산, 통계 집계, 웹훅 발송

데이터 흐름 예시

크리에이터 선택

유저가 게임에서 크리에이터를 선택

부스트 등록

게임 서버가 POST /v1/server/sponsors 호출

인게임 결제

유저가 인게임 결제 진행

결제 등록

게임 서버가 POST /v1/server/payments 호출

자동 귀속

SDK API가 해당 결제를 크리에이터에게 자동 귀속

정산

월말 정산 시 크리에이터별 수익 계산

시작하기

필수 연동 API

캠페인 진행을 위해 반드시 연동해야 하는 Server API 3개입니다.

기능	API	설명
부스트 등록	`POST /sponsors`	유저가 크리에이터를 부스트. 결제 귀속의 핵심
쿠폰 검증	`POST /coupons/validate`	쿠폰 코드 유효성 검사
결제 등록	`POST /payments`	인게임 결제 등록. 정산의 기초 데이터

캠페인 게시를 위해 연동 검증이 필요합니다. 위 3개 API를 각각 최소 1번 이상 Live 환경에서 호출해야 캠페인을 게시할 수 있습니다. 이 검증이 완료되지 않으면 캠페인 승인 화면에 다음 메시지가 표시됩니다:“게임과 PlayCamp가 연동되어 있지 않습니다. API를 통해 연동이 필요합니다.”검증 호출 시 isTest: true를 사용할 수 있습니다. 테스트 모드 요청도 연동 검증으로 인정되며, 실제 데이터는 저장되지 않습니다.

연동 검증 흐름:

API 연동

게임 서버에 필수 API 3개를 구현합니다

Live 환경에서 호출

각 API를 Live 환경(https://sdk-api.playcamp.io)에서 최소 1번씩 호출합니다. isTest: true 사용이 가능합니다.

캠페인 승인 요청

3개 API 검증이 완료되면 PlayCamp 관리자에게 승인을 요청합니다

캠페인 게시

승인 후 연동 경고 메시지가 사라지고 캠페인이 최종 게시 상태로 전환됩니다

캠페인/크리에이터 조회, 웹훅 등은 선택적으로 연동하면 됩니다.

API 키 발급

PlayCamp 플랫폼에서 프로젝트 생성 후 API 키를 발급받습니다.

키 타입	용도	보관 위치
Server Key	모든 API 호출 (읽기/쓰기)	게임 서버 (안전하게 보관)
Client Key	조회 API만 (읽기 전용)	게임 클라이언트 (선택적 사용)

Server Key는 절대 클라이언트에 노출하지 마세요.

인증 방식

모든 API 요청에 Bearer Token 인증을 사용합니다.

Authorization: Bearer {keyId}:{secret}

예시:

Authorization: Bearer ak_server_abc123def456:xyz789secretkey

서버 환경

환경	URL	용도
Sandbox	`https://sandbox-sdk-api.playcamp.io`	개발/테스트
Live	`https://sdk-api.playcamp.io`	실제 서비스

개발 중에는 Sandbox 환경을 사용하세요. Sandbox는 Live와 완전히 격리되어 있습니다.

연동 순서

POST /sponsors          → 유저가 크리에이터 선택 (부스트)
POST /coupons/validate  → 쿠폰 코드 검증
POST /payments          → 인게임 결제 발생 시 등록

SDK

타입 안전한 연동을 위해 HTTP 직접 호출 대신 공식 SDK를 사용할 수 있습니다:

Node SDK
Go SDK

npm install @playcamp/node-sdk

import { PlayCampServer } from '@playcamp/node-sdk';

const server = new PlayCampServer('your_server_key:your_secret', {
  environment: 'sandbox',
});

자세한 내용은 Node SDK 가이드를 참조하세요.

go get github.com/playcamp/playcamp-go-sdk

import playcamp "github.com/playcamp/playcamp-go-sdk"

server, err := playcamp.NewServer("your_server_key:your_secret",
    playcamp.WithEnvironment(playcamp.EnvironmentSandbox),
)

자세한 내용은 Go SDK 가이드를 참조하세요.

테스트 모드

캠페인 시작 전 isTest: true 파라미터를 사용하여 API 연동을 테스트할 수 있습니다.

cURL
Node SDK
Go SDK

curl -X POST "https://sandbox-sdk-api.playcamp.io/v1/server/payments" \
  -H "Authorization: Bearer ak_server_xxx:secret" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "test_user",
    "transactionId": "test_txn_001",
    "productId": "gem_pack_100",
    "amount": 9900,
    "currency": "KRW",
    "platform": "Android",
    "distributionType": "MOBILE_STORE",
    "purchasedAt": "2024-01-15T10:30:00.000Z",
    "isTest": true
  }'

const server = new PlayCampServer('your_server_key:your_secret', {
  environment: 'sandbox',
  isTest: true,
});

const payment = await server.payments.create({
  userId: 'test_user',
  transactionId: 'test_txn_001',
  productId: 'gem_pack_100',
  amount: 9900,
  currency: 'KRW',
  platform: 'Android',
  distributionType: 'MOBILE_STORE',
  purchasedAt: new Date('2024-01-15T10:30:00Z'),
});

server, err := playcamp.NewServer("your_server_key:your_secret",
    playcamp.WithEnvironment(playcamp.EnvironmentSandbox),
    playcamp.WithTestMode(true),
)

purchasedAt, _ := time.Parse(time.RFC3339, "2024-01-15T10:30:00Z")

payment, err := server.Payments.Create(ctx, playcamp.CreatePaymentParams{
    UserID:           "test_user",
    TransactionID:    "test_txn_001",
    ProductID:        "gem_pack_100",
    Amount:           9900,
    Currency:         "KRW",
    Platform:         playcamp.PaymentPlatformAndroid,
    DistributionType: playcamp.String("MOBILE_STORE"),
    PurchasedAt:      purchasedAt,
})

테스트 모드 특징:

요청 파라미터 검증은 실제와 동일하게 수행
데이터는 DB에 저장되지 않음
Mock 응답 반환

권장: 캠페인 시작 전 연동 시에는 isTest: true를 사용하여 테스트하세요. isTest는 Sandbox와 Live 환경 모두에서 사용 가능합니다. 실제 캠페인 운영 시에는 isTest 파라미터를 제거하세요.

자세한 내용은 테스트 모드를 참조하세요.

플랫폼

개발사 가이드

크리에이터 가이드

개요

아키텍처

역할 분담

데이터 흐름 예시

시작하기

필수 연동 API

API 키 발급

인증 방식

서버 환경

연동 순서

SDK

테스트 모드

​아키텍처

​역할 분담

​데이터 흐름 예시

​시작하기

​필수 연동 API

​API 키 발급

​인증 방식

​서버 환경

​연동 순서

​SDK

​테스트 모드

아키텍처

역할 분담

데이터 흐름 예시

시작하기

필수 연동 API

API 키 발급

인증 방식

서버 환경

연동 순서

SDK

테스트 모드