PSN 검증 성공한 구매에 대해서 완료 및 소모(Consume) 처리 요청

기본 정보

1. 빌링 완료 처리와 PSN entitlement 소모(consume) 처리를 함께 수행하는 API입니다.

위험

이 API의 성공 응답을 받은 후에 아이템을 지급해야 합니다.(PSN 규정)

• consume 성공 전 아이템 지급 금지 — 구글/애플과 순서가 반대입니다.

항목	내용	비고
호출주체	게임서버(s2s API)
도메인	각 환경별 도메인
인증 방식	HTTP 헤더 인증 정보
HTTP 메소드	POST
Content-Type	application/x-www-form-urlencoded

Request

HTTP Request end point

POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/psn/complete

HTTP Request Header

• 아래의 HTTP Header들을 API 요청에 포함시켜야합니다.

이름	값	비고
X-Req-Pjid	프로젝트ID	기술 PM 등에게 전달받은 프로젝트ID
X-Auth-Access-Key	인증용 키	기술 PM 등에게 전달받은 해당 게임용 인증 키

HTTP Request Parameter

• 아래 파라미터들을 Content-Type: application/x-www-form-urlencoded 으로 호출하면 됩니다.

key	type	required	설명
reqId	String	Y	요청 유니크 ID - 예: {playerId}_complete_{UUID}
pjid	String	Y	프로젝트ID
boid	String	Y	빌링 주문ID
playerId	String	Y	결제 유저 ID

Response

• 별도 resultData 없이 성공 메시지에 transactionId가 포함됩니다.

Success sample

{
  "resultCode": "SUCCESS",
  "resultMessage": "Success complete boid:'...' | transactionId:'...'"
}

실패 응답

• 비즈니스 실패도 HTTP 200으로 응답됩니다. HTTP status가 아닌 resultCode로 분기하세요. SYSTEM_ERROR(500)·NOT_ALLOW_AUTH(인증 헤더 오류)는 전 API 공통.
• 이미 COMPLETED 처리된 boid로 재호출하면 SUCCESS로 응답되므로 재호출은 안전합니다.

resultCode	HTTP	발생 케이스	게임서버 대응
USER_ACCESS_TOKEN_NOT_VALID	200	PSN 유저 토큰 미발급/만료/무효(303112), 또는 토큰 계정이 verify 당시 계정과 다름	인가코드 재취득 후 PSN 유저 토큰 발급(auth/token) 재호출 → complete 재시도
INVALID_PARAMETER	200	VERIFY_SUCCESS 상태의 boid 없음(미검증·취소 등), 필수값 누락	구매 상태 확인. 미검증이면 verify부터 진행
EXTERNAL_API_CONSUME_FAIL	200	PSN consumeEntitlement 실패(통신 오류·PSN 오류). 빌링 상태는 VERIFY_SUCCESS 유지	아이템 지급 금지. 재시도 또는 재처리 리스트 조회(retry/list)로 재처리

{
  "resultCode": "EXTERNAL_API_CONSUME_FAIL",
  "resultMessage": "PSN consumeEntitlement communication error.",
  "traceId": "billing_01H..."
}

요청 curl 샘플

• 샘플 curl 커맨드입니다. 요청 정보에 맞게 변경해서 호출하세요.

curl -X 'POST' \
  'https://API도메인/billing/api-game/v1/purchase/psn/complete' \
  -H 'X-Req-Pjid: PJID값' \
  -H 'X-Auth-Access-Key: API 인증키' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'reqId=tester01_complete_98b50911-0928-493b-a816-dac8dbca1f53' \
  --data-urlencode 'pjid=1201' \
  --data-urlencode 'boid=발급된 boid' \
  --data-urlencode 'playerId=tester01'