본문으로 건너뛰기

Google Play 미 완료 및 소모(Consume) 처리 누락된 리스트 조회 -게임서버 재처리 필요

기본 정보​

  1. 빌링에 검증(verify)까지 완료 후 빌링 완료 및 consume(소모) 처리 누락된 리스트를 조회하는 API
    1. 유저에게 결제가 완료되어 돈은 청구되었지만, 상품 지급이 누락되었을 가능성이 높은 리스트
  2. 소모성 상품의 경우 최종 소모(consume)처리를 진행하지 않는다면 유저는 해당 상품을 다시 구매할 수 없습니다.
    1. 3일간 방치되면 구글이 자동 환불 처리를 진행합니다.
    2. 게임은 해당 API로 리스트를 조회하여 상품 지급 누락인 경우 지급하거나 상품은 지급했지만 빌링 완료 및 소모 처리를 누락한 경우 재 처리를 구현할 수 있습니다.
      1. 예) 구글앱의 경우 인게임의 상점 진입 시점 등에 미 처리 데이터 존재 여부를 API로 확인
      2. 재 처리 기능을 구현할 때는 게임서버의 상품(아이템) 지급 결과와 비교하여 중복 지급되지 않도록 주의
위험
  • Client의 재처리는 SDK가이드 확인 후 구현하셔야합니다.
  • 해당 API는 게임서버에서 최종 완료 및 소모를 누락하여 3일 후 Google에 의한 자동 결제 취소 등을 방어하기 위한 기능 구현용 API입니다.
항목내용비고
호출주체게임서버(s2s API)
도메인각 환경별 도메인
인증방식HTTP 헤더 인증 정보
HTTP 메소드POST
Content-Typeapplication/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 으로 호출하면 됩니다.
이름데이터 타입설명예
pjidString(20)

프로젝트ID

  • 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음
1004
playerIdString(50)

결제를 진행하는 유저의 ID

  • 게임에서 결제 스콥을 관리하고 싶은 id값으로 사용

    • 드림에이지의 uid값이 될 수도 있음
maxLimitInteger

최대 조회 건수: 최대 값 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 typenot null Y/Ndescriptionexample
retryAbleList list 재 처리 가능한 리스트
boidString(20)Y빌링 시스템의 주문ID4
playerIdString(50)Y결제를 진행했던 유저의 ID
paymentString(20)Y결제가 진행된 스토어(돈을 지급한 행위가 발생한 스토어)
appStoreString(20)Y앱을 다운로드한 플랫폼 스토어(개발사 입장에서는 배포한 스토어)
productIdString(200)Y예약 시점에 요청된 상품ID
purchaseStatusString(30)Y빌링시스템에 구매 상태코드 표 참고
totalPriceDecimal(14,4)

N

  • 구매 상태 시점에 따라 없을 수 있음

구매 금액

  • Decimal(14,4)정밀도
totalMicroPriceLong

N

  • 구매 상태 시점에 따라 없을 수 있음
구매 금액 micro단위
currencyString(10)

N

  • 구매 상태 시점에 따라 없을 수 있음

구매 금액의 화폐 단위
completedAtString

N

  • 빌링 구매 완료 상태가 아니었었다면 null

구매 완료 일시

  • ISO 8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX 포맷
2023-11-26T14:56:38.000+09:00
completedAtUnixTSLong

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",
                "productId": "google_play_gem_01",
                "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_AUTHAPI 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생
  • 아래 에러 코드들은 해당 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'