본문으로 건너뛰기

Apple 미 완료 상태인 재 처리 리스트 조회(게임서버 재처리 필요)

기본 정보​

  1. 빌링에 검증(verify)까지 완료 후 빌링 완료 누락된 리스트를 조회하는 API
    1. 유저에게 결제가 완료되어 돈은 청구되었지만, 상품 지급이 누락되었을 가능성이 높은 리스트
  2. 게임은 해당 API로 리스트를 조회하여 상품 지급 누락인 경우 지급하거나 상품은 지급했지만 빌링 완료 및 소모 처리를 누락한 경우 재 처리를 구현할 수 있습니다.
    1. 재 처리 기능을 구현할 때는 게임서버의 상품(아이템) 지급 결과와 비교하여 중복 지급되지 않도록 주의
위험
  • Client의 재처리는 SDK가이드 확인 후 구현하셔야합니다.(ex. 결제 중간에 앱 종료 등의 대응을 위한 재결제)
  • 해당 API는 게임 서버에서 빌링 서버 API로 완료 요청의 누락에 대한 재처리 기능 구현에 사용되는 API입니다.
항목내용비고
호출주체게임서버(s2s API)
도메인각 환경별 도메인
인증 방식HTTP 헤더 인증 정보
HTTP 메소드POST
Content-Typeapplication/x-www-form-urlencoded

Request​

HTTP Request end point​

POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/apple/appstore/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 typedescriptionexample
retryAbleList list재 처리 가능한 리스트
boidString(20)빌링 시스템의 주문ID4
playerIdString(50)결제를 진행했던 유저의 ID
paymentString(20)결제가 진행된 스토어(돈을 지급한 행위가 발생한 스토어)
appStoreString(20)앱을 다운로드한 플랫폼 스토어(개발사 입장에서는 배포한 스토어)
productIdString(200)구매 예약 시점에 전달된 상품ID
purchaseStatusString(30)빌링시스템에 구매 상태코드 표 참고
totalPriceDecimal(14,4)

구매 금액

  • Decimal(14,4)정밀도
totalMicroPriceLong구매 금액 micro단위
currencyString(10)

구매 금액의 화폐 단위
completedAtString

구매 완료 일시

  • ISO 8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX 포맷
2023-11-26T14:56:38.000+09:00
completedAtUnixTSLong구매 완료 일시의 Unix Timestamp 타입1707219996

Success sample​

  • 재 처리 가능한 리스트가 list로 리턴
{
    "resultCode": "SUCCESS",
    "resultMessage": "request success",
    "resultData": {
        "retryAbleList": [
            {
                "boid": "1",
                "playerId": "playerId",
                "payment": "APPLE_APP_STORE",
                "appStore": "APPLE_APP_STORE",
                "productId": "apple_app_store_gem_01",
                "purchaseStatus": "VERIFY_SUCCESS",
                "totalPrice": 0.9900,
                "totalMicroPrice": 990000,
                "currency": "USD",
                "completedAt": "2024-01-29T11:40:50.000Z",
                "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

요청 curl 샘플​

  • 도메인 및 인증 헤더 등은 변경 필요
curl --location 'https://billing-game-api-dev.pub-dev.hybegames.io/billing/api-game/v1/purchase/apple/appstore/consumable/retry/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'