Voided Purchases API

Google Play Voided Purchases API는 사용자가 무효화한 구매와 관련된 인앱 주문 목록을 제공합니다. 이 목록의 정보를 통해 사용자가 인앱 주문에서 제품에 액세스하지 못하도록 차단하는 취소 시스템을 구현할 수 있습니다.

이 API는 구매에 적용됩니다. 구독에 관한 사항은 실시간 개발자 알림을 참조하세요.

사용자가 구매를 무효화하는 방법은 다음과 같습니다.

  • 사용자가 주문에 관한 환불을 요청합니다.
  • 사용자가 주문을 취소합니다.
  • 주문에 관한 지불을 거절합니다.

특히 게임 앱에서는 이 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

응답에 표시하려는 무효화된 가장 오래된 인앱 상품 구매 시간(Unix Epoch 시간 이후, 밀리초)입니다. 기본적으로   startTime은 30일 전으로 설정됩니다.

이 API에는 지난 30일 동안의 무효화된 구매만 표시됩니다. 제공한 startTime 값에 상관없이 그 이전에 무효화된 구매는 응답에 표시되지 않습니다.

endTime

응답에 표시하려는 무효화된 최신 인앱 상품 구매 시간(Unix Epoch 시간 이후, 밀리초)입니다. 기본적으로   endTime은 현재 시간으로 설정됩니다.

maxResults
각 응답에 표시되는 무효화된 구매의 최대 수입니다. 기본적으로 이 값은 1,000입니다. 이 매개변수의 최대값도 1,000입니다.
token
이전 응답의 연속 토큰이며, 더 많은 결과를 볼 수 있습니다.

응답은 인앱 주문과 관련하여 무효화된 구매를 포함하는 JSON 문자열입니다. 결과가 maxResults 요청 매개변수에 지정된 수보다 더 많은 경우 응답에 nextPageToken 값이 포함됩니다. 이 값을 후속 요청에 전달하여 더 많은 결과를 볼 수 있습니다. 목록의 첫 번째 결과에는 무효화된 가장 오래된 인앱 제품 구매가 표시됩니다.

{
  "tokenPagination": {
    "nextPageToken": "next_page_token"
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_purchase_token",
      "purchaseTimeMillis": "1468825200000",
      "voidedTimeMillis": "1469430000000"
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_other_purchase_token",
      "purchaseTimeMillis": "1468825100000",
      "voidedTimeMillis": "1470034800000"
    },
  ]
}

할당량

Voided Purchases API는 다음 할당량을 패키지 단위로 설정합니다.

  • 쿼리 500개/일 (날짜는 태평양 표준시로 자정에 시작되고 종료됨)
  • 30초 주기 동안 쿼리 30개

초기 요청 가이드라인

초기 API 요청 중에 앱에 사용할 수 있는 모든 데이터를 가져올 수 있습니다. 드물지만 이 프로세스에서 일일 할당량이 소진될 수도 있습니다. 무효화된 구매 데이터를 더 안전하고 일관된 방식으로 가져오려면 다음 권장사항을 따르세요.

  • maxResults 매개변수에 기본값을 사용합니다. 이렇게 하면 일일 쿼리 할당량을 모두 사용했을 때 100,000개의 무효화된 구매에 관한 세부정보를 검색할 수 있습니다.
  • 응답에 nextPageToken 값이 포함되었을 때 다음 요청 중에 이 값을 token 매개 변수에 할당합니다.
  • 잘못된 요청도 할당량에 포함되므로 선택적 요청 매개변수 값을 통한 실험을 최소화하세요.

권장사항

앱에서 이 API를 사용하는 방법을 결정할 때 구매를 무효화하는 다양한 이유가 있으므로 모든 상황에 적용할 수 있는 하나의 해결 방법은 있을 수 없습니다. 취소 정책과 전략을 설계할 때 사용자를 염두에 두세요. 전략을 설계할 때 다음과 같은 권장 사용 방법을 적용할 수 있습니다.

  • 원치 않는 동작을 처리하기 위한 포괄적인 전략에서 다양한 요소 중 하나로써 이 API를 사용합니다. 인앱 제품 액세스 권한을 취소하는 것은 인앱 구매 가격이 합리적인 앱, 바람직하지 않은 동작을 권장하지 않는 앱 설계, 바람직하지 않은 동작을 거부하는 문화권의 강력한 사용자층, 반응이 빠르고 효율적인 사용자 지원 채널 등과 같은 조건에서 더 효과적입니다.
  • 모든 사용자에게 공정하게 적용되도록 취소 정책을 균일하게 관리합니다.
  • 원치 않는 동작을 처리할 때 단계별 정책을 작성하는 것이 좋습니다. 예를 들어, 초기 위반 사항에 인앱 경고로 응답한 다음 사용자의 원치 않는 행동이 지속되면 동일한 응답을 에스컬레이션합니다. 최후의 수단으로 사용자가 앱과 상호작용하지 못하도록 차단할 수도 있습니다.
  • 취소 정책을 도입한 후 정책을 업데이트할 때마다 앱의 대응 채널을 통해 변경 사항을 사용자에게 알립니다. 변경 사항을 앱에 적용하기 전에 사용자가 변경 사항을 명확하게 이해할 수 있는 시간을 제공합니다.
  • 인앱 제품에 관한 액세스 권한 취소 등과 같은 조치를 할 때마다 사용자에게 투명하게 알립니다. 사용자가 결정에 이의를 제기할 수 있어야 하며 이의 사항은 공정하게 처리해야 합니다.
  • 의견 양식과 커뮤니티 포럼을 모니터링하여 사용자가 바람직하지 않은 행동을 보이는 이유와 행동 방식을 파악합니다. 이러한 정보를 1차 방어선으로 활용하세요.