Google Play 유저의 구매 완료 요청에 대한 검증
기본 정보
Google Play에서 유저가 구매한 결제 건을 검증합니다.
영수증 검증 및 기본적인 어뷰징 체크가 진행됩니다.
영수증 변조 여부 확인
Request
HTTP Request end point
POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/google/play/consumable/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 등의 문제 때문
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만을 곱함)
결제 스토어 특화 파라미터
purchaseOriginalJson
String
구매 원본 Json
앱에서 구현시 참고 링크
base64 디코딩된 receiptData
{"orderId":"GPA.3339-8889-4444-64541","packageName":"com.hybeim.블라블라","productId":"google_com.hybeim.블라블라_gem55000\ .... 블라블라
Response
응답은 JSON형태로 전달됩니다.
Sample
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의 데이터를 검증 시도(동일 영수증 중복 사용 요청)
에러코드 ALREADY_EXIST_DATA로 응답하며 existPurchaseInfo가 추가로 응답됩니다.
게임 서버에서 추가로 기능 구현할 때 사용 가능합니다.
boid
String(20)
빌링 시스템의 주문ID
4
imid
String(40)
IMID
하이브IM의 IMID로 로그인 후 얻을 수 있음
PJID 내 사용자를 식별하는 고유 Key
aaaabbbb-ccccddd-fffccc-tttggg
playerId
String(50)
구매를 진행하는 유저의 ID
게임에서 결제 스콥을 관리하고 싶은 id값으로 사용
하이브 IM의 imid값이 될 수도 있음
paymentOrderId
String(100)
결제가 진행된 payment의 주문ID
스토어/마켓에서 발급한 주문ID
productId
String(200)
구매 진행하는 상품ID
SKU와 같은 값
{
"resultCode":"ALREADY_EXIST_DATA",
"resultMessage":"This receipt information has already been used. | paymentOrderId:'GPA.3322-9740-8007-41997' | request boid:'646' | exist boid:'645' | exist boid purchaseStatus:'VERIFY_SUCCESS'",
"traceId":"b_4766e9364f9b",
"resultData":{
"existPurchaseInfo":{
"boid":"645",
"purchaseStatus":"VERIFY_SUCCESS",
"imid":"EXCDQKKTBS5NYLTL53R3",
"playerId":"EXCDQKKTBS5NYLTL53R3",
"paymentOrderId":"GPA.3322-9740-8007-41997",
"productId":"google_com.hybeim.platform_test003"
}
}
}검증 성공한 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
ALREADY_EXIST_DATA
미 데이터가 존재
동일 영수증 정보로 이미 데이터가 존재와 같은 케이스
NOT_ALLOW_PURCHASE
구매 기능을 사용할 수 없는 상황
빌링 시스템에 스토어 관련 설정 누락
다른 유저의 결제 예약건을 완료 처리 시도
NOT_VALID_RECEIPT
구매 영수증 검증
영수증 변조 여부 검사와 같은 어뷰징 방지 검사
구글 API로부터 구매의 현재 상태를 검증
EXTERNAL_API_ERROR
빌링 API가 호출하는 외부 API가 에러인 경우
예) 구글 API 장애로 구매의 상태 정보를 받아오지 못하는 경우
게임 서버는 지수 백오프 알고리즘으로 재 시도하거나 클라이언트의 미 처리 영수증 처리 기능으로 처리할 수 있음
요청 curl 샘플
도메인 및 인증 헤더 등은 변경 필요
curl --location 'https://billing-game-api-dev.pub-dev.hybegames.io/billing/api-game/v1/purchase/google/play/consumable/verify' \
--header 'X-Req-Pjid: 9001' \
--header 'X-Auth-Access-Key: test-auth-key' \
--header 'Content-Type: application/json' \
--data '{
"reqId":"userId_verify_170083bf-8d85-433f-8bd2-67674b7482db-2023-11-24-04",
"pjid":"9001",
"boid":"1",
"microPrice":2200000000,
"currency":"JPY",
"playerId":"playerId",
"purchaseSignature":"Nk2aSXeM17GUiTBNax0dWhNb5nJEjvk1VTBzlfRh8tm5gEl78sof96oIFlrqCw9pFnZAxbVo7NjZyOBs9hzYWZDpMBicFADngJLYKcGY+7ni4+4YkmzDBHwlxWOTiJMmrAmCLHKDAOUWpZo9m3EH9BH3sZGoLsJiSLkgPv8p9D17lQi/U50bhG1NNDmiyX0TxC/sT6JuFWoLSFTQYno0Up/WcgqATK8fTJ+8A7yP7eOxKO+50gFOZ1XkF1fKUhcczi0t1yUKk8CjA+ZawghcNKhy1/pDBTLfU93b3/pr+x0j3GyJT45S/Yf1PxXrF2PjcUvXyV5TBdY6ztk6C1vwAg==",
"purchaseOriginalJson":"{\"orderId\":\"GPA.3323-4443-4781-42315\",\"packageName\":\"com.hybeim.intheseom\",\"productId\":\"seom_tany_100022\",\"purchaseTime\":1698116965733,\"purchaseState\":0,\"purchaseToken\":\"bkdcnncmkeegcekfcmjaeppj.AO-J1OxMzEQ0nV5GJvj1ytipiX90uRpWtyyn4cgozqFYeRp1euFxm2lFbH3XR8mPBPWeXgIIsxhkpMvDeey1_lRJ7WLmFMJdbg\",\"quantity\":1,\"acknowledged\":false}",
"productDetailsJson":"{\"some\":\"블라블라\"}"
}'Last updated