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

기본 정보

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

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

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

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

• Client의 재처리는 SDK가이드 확인 후 구현하셔야합니다.(ex. 결제 중간에 앱 종료 등의 대응을 위한 재결제)

• 해당 API는 게임 서버에서 빌링 서버 API로 완료 요청의 누락에 대한 재처리 기능 구현에 사용되는 API입니다.

항목	내용	비고
호출주체	게임서버(s2s API)
도메인	각 환경별 도메인
인증 방식	HTTP 헤더 인증 정보
HTTP 메소드	POST
Content-Type	application/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 으로 호출하면 됩니다.

이름	데이터 타입	설명	예
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	description	example
retryAbleList		list	재 처리 가능한 리스트
	boid	String(20)	빌링 시스템의 주문ID	4
	playerId	String(50)	결제를 진행했던 유저의 ID
	payment	String(20)	결제가 진행된 스토어(돈을 지급한 행위가 발생한 스토어)
	appStore	String(20)	앱을 다운로드한 플랫폼 스토어(개발사 입장에서는 배포한 스토어)
	productId	String(200)	구매 예약 시점에 전달된 상품ID
	purchaseStatus	String(30)	빌링시스템에 구매 상태	코드 표 참고
	totalPrice	Decimal(14,4)	구매 금액 Decimal(14,4)정밀도
	totalMicroPrice	Long	구매 금액 micro단위
	currency	String(10)	구매 금액의 화폐 단위 3글자 포맷의 ISO-4217
	completedAt	String	구매 완료 일시 ISO 8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX 포맷	2023-11-26T14:56:38.000+09:00
	completedAtUnixTS	Long	구매 완료 일시의 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_AUTH	API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생

• 아래 에러 코드들은 해당 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'