ONE Store 검증 성공한 구매에 대해서 완료 및 소모처리 요청

기본 정보

1. 검증 성공한 구매 완료건에 대해서 빌링 시스템에 완료 및 ONE Store에 소모 처리를 요청하는 API

   1. 꼭, 게임 서버에서 상품 지급 성공 후 호출되어야 합니다.

2. ONE Store의 API를 중개 처리하여 호출하기 때문에 Timeout은 여유있게 설정하는게 좋습니다.(ex. 20초)

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

Request

HTTP Request end point

POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/onestore/inapp/managed/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 으로 요청되어야 합니다.

이름	데이터 타입	설명	예
reqId	String(100)	중복 요청을 막거나 요청 추적을 위한 값	userId_UUID 등과 같은 방식으로 생성
pjid	String(20)	프로젝트ID 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음	1004
boid	String(20)	빌링 시스템 구매 예약 API를 통해서 생성된 ID	1234
playerId	String(50)	결제를 진행하는 유저의 ID 게임에서 결제 스콥을 관리하고 싶은 id값으로 사용 회원 플랫폼의 IMID의 uid값을 사용할 수도 있음

Response

응답은 JSON형태로 전달됩니다.

Sample

Success sample

• 게임 서버에서도 필요 로그를 저장해두시는게 좋습니다.

{
  "resultCode": "SUCCESS",
  "resultMessage": "Purchase completion successful for boid: 9"
}

Error sample

• 구매 완료된 boid에 대해서 다시 완료 요청

{
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "'boid: 1' purchaseState is not BILLING_RESERVED. The current value is 'COMPLETED"
}

에러 코드 정의

• 아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)

• 아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.

  • 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.

  • 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.

에러코드	비고
SYSTEM_ERROR	빌링 API에서 발생한 시스템 에러 HTTP 상태코드 500 리턴
NOT_ALLOW_AUTH	API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생

• 아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.

에러코드	비고
INVALID_PARAMETER
EXTERNAL_API_ERROR	빌링 API가 호출하는 외부 API가 에러인 경우 예) ONE Store 서버 API 응답이 없음

요청 curl 샘플

• 도메인 및 인증 헤더 등은 변경 필요

curl -X 'POST' \
  'https://API도메인/billing/api-game/v1/purchase/onestore/inapp/managed/complete' \
  -H 'accept: application/json;charset=UTF-8' \
  -H 'X-Req-Pjid: PJID입력' \
  -H 'X-Auth-Access-Key: 인증키 입력' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'reqId=playerId_complete_12b50907-0928-493b-a816-dac8dbca1f53&pjid=1202&boid=1&playerId=playerId'