데이터 보상 API

POST https://www.playus.app/v1/publisher/rewards

게임 서버가 확정한 보상만 보냅니다. 클라이언트의 점수나 MB를 검증 없이 전달하지 마세요. Basic 인증(client_id:client_secret), Content-Type: application/json과 User-Agent를 사용합니다.

요청#

{"items":[{"key":"run:123:clear","sub":"pu_ExamplePlayer123","mb":5,"reason":"stage-clear","occurredAt":"2026-10-21T00:00:00Z"}]}

필드	규칙
key	필수. 앱 전체에서 유일한 이벤트 식별자. 1~120자, 영숫자·밑줄·콜론·점·하이픈·슬래시·@
sub	필수. 로그인에서 얻은 해당 앱의 가명
mb	필수. 1~1000 사이 정수. 앱별 한 건·하루 상한 추가 적용
reason	선택. 기록용 설명, 40자까지 저장
occurredAt	선택. 이벤트 시각. ISO 8601 권장

items는 1~100건입니다. 재전송은 같은 key를 사용합니다. 사용자마다 key=stage-1을 재사용하지 말고 회원·판·이벤트를 구분하는 값을 만드세요.

응답#

{"items":[{"key":"run:123:clear","status":"granted","grantedMb":5,"remainingTodayMb":45}]}

status	처리 방법
granted	지급 완료. 실제 금액은 grantedMb
capped	한 건 또는 하루 상한으로 일부/전부 제한. grantedMb는 0일 수도 있음
held	위험 검토로 보류. 즉시 사용 가능한 잔액으로 표시하지 않음
duplicate	이미 처리한 key. 기존 grantedMb를 반환하므로 추가 적립하지 않음
rejected	미지급. reason을 확인하고 항목별 처리

HTTP 200이어도 모든 항목이 성공한 것은 아닙니다. 항목별 status를 반드시 저장하세요. duplicate도 원래 지급이 held였을 수 있으므로 새 지급 알림을 만들지 않습니다.

상한과 날짜#

PLAYUS가 maxGrantMb와 dailyMbCapPerUser를 적용합니다. 하루 상한 0은 운영자가 허용한 무제한 설정입니다. 보류 금액도 상한 계산에 포함됩니다. 보상은 서버 수신 시점의 PLAYUS 게임 날짜 기준으로 계산되며 occurredAt으로 과거 날짜 상한을 복원하지 않습니다.

항목 거절#

reason	의미
invalid_key / invalid_sub / invalid_mb	입력 형식 오류
unknown_sub	해당 앱의 활성 연결 없음
rewards_off	앱 보상 비활성
paused	플랫폼 적립 중단
blocked / inactive_user	회원 상태 또는 위험 정책

paused와 rewards_off 같은 일시적 운영 상태는 무한 재전송 대신 대기·운영 확인 정책을 정합니다. 원본 이벤트를 보관하고 재개 시 정책에 맞게 처리하세요.

Node.js 예시#

const results = await playus.sendRewards([
  { key: 'run:123:clear', sub, mb: 5, reason: 'stage-clear' },
]);
for (const item of results) {
  // 항목별 결과를 outbox에 기록. grantedMb 기준으로 화면을 갱신합니다.
}

게임의 자체 MB 잔액과 PLAYUS 지갑에 동시에 적립하지 않습니다. PLAYUS 회원의 eSIM 교환은 트립톡 앱으로 안내하세요.