Google Play Voided Purchases API는 사용자가 무효화한 구매와 관련된 주문 목록을 제공합니다. 이 목록의 정보를 사용하여 사용자가 무효화한 주문의 제품에 액세스하지 못하도록 방지하는 취소 시스템을 구현할 수 있습니다.
Voided Purchases API는 일회성 인앱 주문과 앱 정기 결제에 적용됩니다.
다음과 같은 경우에 구매가 무효화됩니다.
- 사용자가 주문의 환불을 요청합니다.
- 사용자가 주문을 취소합니다.
- 주문에 대한 지불이 거절됩니다.
개발자가 주문을 취소하거나 환불합니다.
Google에서 주문을 취소하거나 환불합니다.
특히 게임 앱에서 Voided Purchases API를 사용하면 모든 앱 사용자를 위한 더욱 균형있고 공정한 환경을 마련할 수 있습니다.
액세스 권한 얻기
Voided Purchases API를 사용하려면 재무 정보를 볼 권한이 있어야 합니다. 권한을 제공하려면 OAuth 클라이언트 또는 서비스 계정을 사용하세요. 서비스 계정을 사용 중이면 이 계정에서 '재무 보고서 보기' 권한을 사용하도록 설정합니다.
Google Play Developer API에 관한 액세스 권한을 얻는 자세한 방법은 다음 가이드를 참조하세요.
무효화된 구매 보기
GET 메서드를 사용하여 무효화된 구매 목록을 요청합니다. 요청에 앱의 정규화된 패키지 이름(예: com.google.android.apps.maps)과 API에 대한 액세스 권한을 얻을 때 받은 승인 토큰을 포함합니다.
GET https://www.googleapis.com/androidpublisher/v3/applications/ your_package_name/purchases/voidedpurchases?access_token=your_auth_token
다음과 같은 매개변수를 요청에 포함할 수도 있습니다(선택사항).
- startTime
응답에 표시하려는 무효화된 구매 중 가장 오래된 구매의 시간(유닉스 시간 이후, 밀리초 단위)입니다. 기본적으로
startTime은 30일 전으로 설정됩니다.Voided Purchases API는 지난 30일 동안의 무효화된 구매만 표시합니다. 무효화된 구매 중 더 오래된 구매는
startTime에 제공한 값과 상관없이 응답에 포함되지 않습니다.- endTime
응답에 표시하려는 무효화된 구매 중 가장 최근 구매의 시간(유닉스 시간 이후, 밀리초 단위)입니다. 기본적으로
endTime은 현재 시간으로 설정됩니다.- maxResults
- 각 응답에 표시되는 무효화된 구매의 최대 수입니다. 기본적으로 이 값은 1,000입니다. 이 매개변수의 최댓값도 1,000입니다.
- token
- 이전 응답의 연속 토큰이며, 이를 통해 더 많은 결과를 볼 수 있습니다.
- type
각 응답에 표시되는 무효화된 구매의 유형입니다. 0으로 설정하면 무효화된 인앱 구매만 반환됩니다. 1로 설정하면 무효화된 인앱 구매와 무효화된 정기 결제 구매가 모두 반환됩니다. 기본값은 0입니다.
- includeQuantityBasedPartialRefund
수량 기반의 부분 환불 중 무효화된 구매가 포함되었는지 여부를 나타내며, 이는 다중 수량 구매에만 적용됩니다.
true인 경우, 수량 기반의 부분 환불 중 환불된 수량을 나타내는voidedQuantity를 사용해 무효화된 구매를 추가로 반환할 수 있습니다. 기본값은false입니다.
응답은 무효화된 구매 목록이 포함된 JSON 문자열입니다. 결과 개수가 maxResults 요청 매개변수에 지정된 수보다 많으면 응답에 nextPageToken 값이 포함됩니다. 이 값을 후속 요청에 전달하면 더 많은 결과를 볼 수 있습니다. 목록의 첫 번째 결과에는 무효화된 구매 중 가장 오래된 구매가 표시됩니다.
{
"tokenPagination": {
"nextPageToken": "next_page_token"
},
"voidedPurchases": [
{
"kind": "androidpublisher#voidedPurchase",
"purchaseToken": "some_purchase_token",
"purchaseTimeMillis": "1468825200000",
"voidedTimeMillis": "1469430000000",
"orderId": "some_order_id",
"voidedSource": "0",
"voidedReason": "4"
},
{
"kind": "androidpublisher#voidedPurchase",
"purchaseToken": "some_other_purchase_token",
"purchaseTimeMillis": "1468825100000",
"voidedTimeMillis": "1470034800000",
"orderId": "some_other_order_id",
"voidedSource": "2",
"voidedReason": "5"
},
]
}
할당량
Voided Purchases API는 패키지 단위로 다음 할당량을 설정합니다.
- 쿼리 6,000개/일 (날짜는 태평양 표준시 기준으로 자정에 시작되고 종료됨)
- 30초 주기 동안 쿼리 30개
초기 요청 가이드라인
초기 API 요청 중에 앱에 사용할 수 있는 모든 데이터를 가져오는 것이 좋습니다. 드물지만 이 과정에서 일일 할당량이 소진될 수 있습니다. 무효화된 구매 데이터를 더 안전하고 일관된 방식으로 가져오려면 다음 권장사항을 따르세요.
maxResults매개변수에 기본값을 사용합니다. 이렇게 하면 일일 쿼리 할당량을 모두 사용하여 무효화된 구매 600만 개에 관한 세부정보를 검색할 수 있습니다.- 응답에
nextPageToken값이 포함된 경우 다음 요청 중에 이 값을token매개변수에 할당합니다.
권장사항
앱에서 이 API를 사용할 때는 구매를 무효화하는 이유는 다양하며 모든 사례에 맞는 단 하나의 솔루션은 없다는 사실에 유의하세요. 취소 정책과 전략을 설계할 때 사용자를 염두에 두세요. 전략을 설계할 때 다음과 같은 권장 사용 방법을 적용할 수 있습니다.
- 원치 않는 동작을 처리하기 위한 포괄적인 전략에서 다양한 요소 중 하나로써 이 API를 사용합니다. 인앱 제품 액세스 권한을 취소하는 것은 인앱 구매 가격이 합리적인 앱, 바람직하지 않은 동작을 권장하지 않는 앱 설계, 바람직하지 않은 동작을 거부하는 문화를 가진 강력한 사용자층, 반응이 빠르고 효율적인 사용자 지원 채널 등과 같은 조건에서 더 효과적입니다.
- 모든 사용자에게 공정하게 적용되도록 취소 정책을 균일하게 관리합니다.
- 원치 않는 동작을 처리할 때 단계별 정책을 작성하는 것이 좋습니다. 예를 들어, 초기 위반 사항에는 인앱 경고로 대응한 다음 사용자의 원치 않는 행동이 지속되면 대응의 수준을 점점 높입니다. 최후의 수단으로 사용자가 앱과 상호작용하지 못하도록 차단할 수도 있습니다.
- 취소 정책을 도입한 후 정책을 업데이트할 때마다 앱의 대응 채널을 통해 변경 사항을 사용자에게 알립니다. 변경 사항을 앱에 적용하기 전에 사용자가 변경 사항을 명확하게 이해할 수 있는 시간을 제공합니다.
- 인앱 제품에 관한 액세스 권한 취소 등과 같은 조치를 할 때마다 사용자에게 투명하게 알립니다. 사용자가 결정에 이의를 제기할 수 있어야 하며 이의 사항은 공정하게 처리해야 합니다.
- 의견 양식과 커뮤니티 포럼을 모니터링하여 사용자가 바람직하지 않은 행동을 보이는 이유와 행동 방식을 파악합니다. 이러한 유용한 정보를 1차 방어선으로 활용하세요.