ONE Store 구매 검증 요청

기본 정보

1. ONE Store 관리상품의 소모성 결제에 대한 유저 구매 검증 API입니다.

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

Request

HTTP Request end point

POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/onestore/inapp/managed/verify

HTTP Request Header

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

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

HTTP Request Parameter

• 아래의 공통 파라미터 외에 하단의 각 결제 스토어 특화 파라미터들도 같이 요청해야 합니다.

• Content-Type: application/json 으로 요청되어야 합니다.

  • 검증에는 영수증 관련 정보나 escape 등의 문제 때문에 사용측에서 body로 전송하는게 용이한 경우가 많음

이름	데이터 타입	필수 Y/N	설명	예
reqId	String(100)	Y	중복 요청을 막거나 요청 추적을 위한 값	userId_UUID 등과 같은 방식으로 생성
pjid	String(20)	Y	프로젝트ID 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음	1004
boid	String(20)	Y	빌링 시스템 구매 예약 API를 통해서 생성된 ID	1234
playerId	String(50)	Y	주문 완료를 진행하는 유저ID
purchaseToken	String(20)	Y	구매후 획득한 클라이언트에서 획득한 구매 토큰 - ONE Store 참고 링크
productId	String(200)	Y	구매한 상품ID - 예약 시점과 동일값으로 전달을 통해 빌링서버에서 어뷰징 추가 체크 진행

Response

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

Sample

Success sample

{
    "resultCode": "SUCCESS",
    "resultMessage": "Verification successful. Status: VERIFY_SUCCESS"
}

Error sample

• boid 오류

  {
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "Reserved purchase not found for boid: 1",
    "traceId": "b_7e95e568d4f7"
  }

• 구매 완료하지 않은 boid에 대한 요청

  {
      "resultCode": "INVALID_PARAMETER",
      "resultMessage": "The purchase is not complete.: 1"
  }

에러 코드 정의

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

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

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

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

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

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

에러코드	비고
INVALID_PARAMETER
EXTERNAL_API_ERROR	빌링 API가 호출하는 외부 API가 에러인 경우 예) 구글 API 장애로 구매의 상태 정보를 받아오지 못하는 경우 게임 서버는 지수 백오프 알고리즘으로 재 시도하거나 클라이언트의 미 처리 영수증 처리 기능으로 처리할 수 있음

요청 curl 샘플

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

curl -X 'POST' \
  'https://API도메인/billing/api-game/v1/purchase/onestore/inapp/managed/verify' \
  -H 'accept: application/json;charset=UTF-8' \
  -H 'X-Req-Pjid: PJID값' \
  -H 'X-Auth-Access-Key: API인증키' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
  "reqId": "userId_verify_98b50907-0928-493b-a816-dac8dbca1f54",
  "boid": "1",
  "playerId": "playerId",
  "pjid": "PJID값",
  "productId": "onestore_test_gem_01",
  "purchaseToken": "SDK를 통해 전달받은 ONE Store 구매토큰 값"
}'