Google Play 미 완료 및 소모(Consume) 처리 누락된 리스트 조회

기본 정보

1. 빌링에 검증(verify)까지 완료 후 빌링 완료 및 consume(소모) 처리 누락된 리스트를 조회하는 API

   1. 유저에게 결제가 완료되어 돈은 청구되었지만, 상품 지급이 누락되었을 가능성이 높은 리스트

2. 소모성 상품의 경우 최종 소모(consume)처리를 진행하지 않는다면 유저는 해당 상품을 다시 구매할 수 없습니다.

   1. 3일간 방치되면 구글이 자동 환불 처리를 진행합니다.

   2. 게임은 해당 API로 리스트를 조회하여 상품 지급 누락인 경우 지급하거나 상품은 지급했지만 빌링 완료 및 소모 처리를 누락한 경우 재 처리를 구현할 수 있습니다.

      1. 예) 구글앱의 경우 인게임의 상점 진입 시점 등에 미 처리 데이터 존재 여부를 API로 확인

      2. 재 처리 기능을 구현할 때는 게임서버의 상품(아이템) 지급 결과와 비교하여 중복 지급되지 않도록 주의

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

Request

HTTP Request end point

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

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 으로 호출하면 됩니다.

이름	데이터 타입	설명	예
pjid	String(20)	프로젝트ID 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음	1004
playerId	String(50)	결제를 진행하는 유저의 ID 게임에서 결제 스콥을 관리하고 싶은 id값으로 사용 하이브 IM의 uid값이 될 수도 있음
maxLimit	Integer	최대 조회 건수: 최대 값 5 Google 단건 API를 추가로 호출해야해서 최대 건수 제한 필요 일반적으로 1건 이상 존재하면 안됨	1

Response

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

• 응답 데이터가 리턴되는 경우 resultData 필드에 셋팅되어 응답됩니다.

// API 요청이 성공했으며 추가 데이터 리턴되는 경우 json 구조 예
{
    "resultCode": "SUCCESS",
    "resultMessage": "success request",
    "resultData": {
        "키1": '값1',
        "키2": '값2',
    }
}

Response property

key(1 depth)	key(2 depth)	data type	not null Y/N	description	example
retryAbleList		list		재 처리 가능한 리스트
	boid	String(20)	Y	빌링 시스템의 주문ID	4
	playerId	String(50)	Y	결제를 진행했던 유저의 ID
	payment	String(20)	Y	결제가 진행된 스토어(돈을 지급한 행위가 발생한 스토어)
	appStore	String(20)	Y	앱을 다운로드한 플랫폼 스토어(개발사 입장에서는 배포한 스토어)
	purchaseStatus	String(30)	Y	빌링시스템에 구매 상태	코드 표 참고
	totalPrice	Decimal(14,4)	N 구매 상태 시점에 따라 없을 수 있음	구매 금액 Decimal(14,4)정밀도
	totalMicroPrice	Long	N 구매 상태 시점에 따라 없을 수 있음	구매 금액 micro단위
	currency	String(10)	N 구매 상태 시점에 따라 없을 수 있음	구매 금액의 화폐 단위 3글자 포맷의 ISO-4217
	completedAt	String	N 빌링 구매 완료 상태가 아니었었다면 null	구매 완료 일시 ISO 8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX 포맷	2023-11-26T14:56:38.000+09:00
	completedAtUnixTS	Long	N 빌링 구매 완료 상태가 아니었었다면 null	구매 완료 일시의 Unix Timestamp 타입	1707219996

Success sample

• 재 처리 가능한 리스트가 list로 리턴

  • 단, 해당 데이터로 다시 빌링 완료 및 Google 소모처리를 요청해도, 중간에 운영툴 등에서 소모 처리가 진행되었다면 실제 완료API에서는 에러가 리턴될 수 있음

  • Google API가 장애 등으로 요청 결과를 응답받지 못하면 해당 데이터는 응답 리스트에서 제외 됨

{
    "resultCode": "SUCCESS",
    "resultMessage": "success api request.",
    "resultData": {
        "retryAbleList": [
            {
                "boid": "1",
                "playerId": "playerId",
                "payment": "GOOGLE_PLAY",
                "appStore": "GOOGLE_PLAY",
                "purchaseStatus": "VERIFY_SUCCESS",                
                "totalPrice": 2200.0000,
                "totalMicroPrice": 2200000000,
                "currency": "JPY",
                "completedAt": "2023-11-26T16:28:08.000+09:00",
                "completedAtUnixTS": 1706528450
            }
        ]
    }
}

• API 요청이 성공했지만 대상 데이터 없는 경우

{
    "resultCode": "SUCCESS",
    "resultMessage": "success api request.",
    "resultData": {
        "retryAbleList": null
    }
}

Error sample

• 최대 조회 갯수인 5개보다 더 많은 수를 요청한 경우

{
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "'maxLimit' must be between 1 and 5"
}

에러 코드 정의

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

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

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

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

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

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

에러코드	비고
INVALID_PARAMETER
EXTERNAL_API_ERROR	빌링 API가 호출하는 외부 API가 에러인 경우

요청 curl 샘플

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

curl --location 'https://billing-game-api-dev.pub-dev.hybegames.io/billing/api-game/v1/purchase/google/play/consumable/consumable/beforeConsume/list' \
--header 'X-Req-Pjid: 9001' \
--header 'X-Auth-Access-Key: test-auth-key' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'pjid=9001' \
--data-urlencode 'playerId=playerId' \
--data-urlencode 'maxLimit=5'