Google Play PC 유저의 구매 완료 요청에 대한 검증

기본 정보

HTTP Request end point와 Request Parameter 를 제외하고는 Google Play 유저의 구매 완료 요청에 대한 검증 와 용도가 동일합니다.

1. Google Play PC에서 유저가 구매한 결제 건을 검증합니다.

2. 영수증 검증 및 기본적인 어뷰징 체크가 진행됩니다.

   1. Google 서버에 결제 상태 조회

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

Request

HTTP Request end point

POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/google/play/pc/consumable/verify

HTTP Request Header

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

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

HTTP Request Parameter

• Google PC결제는 모바일 결제와 다르게 결제 영수증 관련 Json이 존재하지 않습니다.

• purchaseToken을 기반으로 검증 작업이 진행됩니다.

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

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

  • 영수증 관련 정보 등의 길이 및 escape 등의 문제 때문

이름	데이터 타입	필수 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
microPrice	long	Y	구매 금액 micro단위 사용측의 부동 소수점 오차등을 방지하기 위해서 micro단위 사용	구매 금액 micro단위(예. $0.99는 990,000 µ$. 100만을 곱함)
currency	String(10)	Y	구매 금액의 화폐 단위 3글자 포맷의 ISO-4217	USD
productId	String	Y	결제완료 후 구글에서 획득한 productId
purchaseToken	String	Y	결제완료 후 구글에서 획득한 결제 토큰

Response

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

Success sample

• 성공으로 응답하면 게임 서버는 유저에게 아이템 및 재화를 지급하고, 이후 Google 소모처리와 빌링 완료처리 API를 호출해서 최종 완료해주시면 됩니다.

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

{
    "resultCode": "SUCCESS",
    "resultMessage": "success. boid:'1'. You must process product(or items) give to user 'playerId' and request completeWithConsume billing API."
}

Error sample

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

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

• 검증 성공한 boid에 다시 검증 요청

{
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "'boid: 1' purchaseStatus is not RESERVED. The current value is 'VERIFY_SUCCESS'"
}

• 변조된 영수증 데이터(purchaseOriginalJson)으로 요청

{
    "resultCode": "NOT_VALID_RECEIPT",
    "resultMessage": "The check for alteration of the receipt(purchaseOriginalJson) failed(not valid). reserved userId:'userId' | purchaseOriginalJson:'{\"1orderId\":\"GPA.3323-4443-4781-49315\",\"packageName\":\"com.hybeim.intheseom\",\"productId\":\"seom_tany_100022\",\"purchaseTime\":1698116965733,\"purchaseState\":0,\"purchaseToken\":\"bkdcnncmkeegcekfcmjaeppj.AO-J1OxMzEQ0nV5GJvj1ytipiX90uRpWtyyn4cgozqFYeRp1euFxm2lFbH3XR8mPBPWeXgIIsxhkpMvDeey1_lRJ7WLmFMJdbg\",\"quantity\":1,\"acknowledged\":false}'"
}

• 이미 완료처리에 사용했던 영수증 데이터로 재 완료 요청(영수증 재 사용 중복요청 어뷰징)

{
    "resultCode": "NOT_ALLOW_PURCHASE",
    "resultMessage": "This receipt information has already been used. | storeOrderId:'GPA.3323-4443-4781-49315' | request boid:'6' | exist boid:'1'"
}

에러 코드 정의

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

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

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

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

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

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

에러코드	비고
INVALID_PARAMETER
NOT_ALLOW_PURCHASE	구매 기능을 사용할 수 없는 상황 빌링 시스템에 스토어 관련 설정 누락 다른 유저의 결제 예약건을 완료 처리 시도
NOT_VALID_RECEIPT	구매 영수증 검증 영수증 변조 여부 검사와 같은 어뷰징 방지 검사 구글 API로부터 구매의 현재 상태를 검증
EXTERNAL_API_ERROR	빌링 API가 호출하는 외부 API가 에러인 경우 예) 구글 API 장애로 구매의 상태 정보를 받아오지 못하는 경우 게임 서버는 지수 백오프 알고리즘으로 재 시도하거나 클라이언트의 미 처리 영수증 처리 기능으로 처리할 수 있음

요청 curl 샘플

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

curl --location 'https://api-qa.pub-dev.hybegames.io/billing/api-game/v1/purchase/google/play/pc/consumable/verify' \
--header 'X-Req-Pjid: 1201' \
--header 'X-Auth-Access-Key: test-auth-key' \
--header 'Content-Type: application/json' \
--data '{
   "reqId":"userId_verify_1706578301",
   "pjid":"1201",   
   "boid":"1",
   "microPrice":2200000000,
   "currency":"JPY",   
   "playerId":"playerId",
   "productId": "productId",
   "purchaseToken": "cikmhljfnfoolndkmpidhkgp.AO-J1~~"
}'