인앱 결제 참조

이 문서에서는 In-app Billing API를 사용하기 위한 기술 참고 정보를 확인할 수 있습니다.

서버 응답 코드

다음 표에는 Google Play에서 애플리케이션으로 전송되는 모든 서버 응답 코드가 나열되어 있습니다. Google Play는 응답 코드를 응답 BundleRESPONSE_CODE 키에 매핑되는 정수로 동기 방식을 사용하여 보냅니다. 애플리케이션은 이러한 응답 코드를 모두 처리해야 합니다.

표 1. In-app Billing API 호출의 응답 코드 요약.

응답 코드 설명
BILLING_RESPONSE_RESULT_OK 0 완료되었습니다.
BILLING_RESPONSE_RESULT_USER_CANCELED 1 사용자가 뒤로를 눌렀거나 대화를 취소했습니다.
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE 2 네트워크 연결이 끊겼습니다.
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE 3 Billing API 버전이 요청된 유형을 지원하지 않습니다.
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE 4 요청한 제품을 구매할 수 없습니다.
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR 5 API에 제공된 인수가 잘못되었습니다. 이 오류는 Google Play에서 애플리케이션이 인앱 결제용으로 올바르게 서명 또는 설정되지 않았거나 매니페스트에 필요한 권한이 없다는 의미일 수도 있습니다.
BILLING_RESPONSE_RESULT_ERROR 6 API 작업 중 치명적인 오류가 발생했습니다.
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED 7 항목을 이미 소유하고 있기 때문에 구매할 수 없습니다.
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED 8 항목을 소유하고 있지 않기 때문에 소비할 수 없습니다.

Billing Support API 참조

이 섹션에서는 앱에 사용할 수 있는 인앱 결제 지원 유형에 관한 정보를 가져오기 위한 메서드를 확인할 수 있습니다.

isBillingSupported() 메서드

이 메서드는 다음을 나타냅니다.

  • API 버전이 앱에서 지원되는지 여부
  • Google Play가 사용자 국가에서 결제를 지원하는지 여부
  • 앱 패키지에 결제가 사용 설정되어 있는지 여부
  • 앱에서 결제 목적으로 해당 유형의 항목을 사용할 수 있는지 여부

표 2. isBillingSupported() 매개변수

유형 설명
apiVersion int 앱에서 사용 중인 In-app Billing API의 버전 번호입니다.
packageName String 이 메서드를 호출하는 앱의 패키지 이름입니다.
type String 값은 인앱 상품의 경우 inapp, 구독의 경우 subs여야 합니다.

이 메서드는 In-app Billing API 버전 3 이상에서 사용할 수 있습니다.

isBillingSupportedExtraParams() 메서드

이 메서드는 isBillingSupported()와 동일합니다. 단, 추가 매개변수를 포함할 수 있는 네 번째 인수 Bundle을 전달할 수 있다는 점이 다릅니다.

표 3. isBillingSupportedExtraParams() 매개변수

유형 설명
apiVersion int 앱에서 사용 중인 In-app Billing API의 버전 번호입니다.
packageName String 이 메서드를 호출하는 앱의 패키지 이름입니다.
type String 값은 인앱 상품의 경우 inapp, 구독의 경우 subs여야 합니다.
extraParams Bundle

앱에서 지원하는 인앱 결제 유형을 추가로 지정하는 추가 매개변수의 집합입니다.

이 번들은 부울 값을 갖는 vr이라는 선택적 키를 포함할 수 있습니다. 이 플래그는 앱에서 가상 현실(VR) 구매 절차를 지원할지 여부를 지정합니다.

이 메서드는 In-app Billing API 버전 7 이상에서 사용할 수 있습니다.

Billing Details API 참조

In-app Billing API는 버전 3 샘플 애플리케이션에 포함되어 있는 IInAppBillingService.aidl 파일에 정의되어 있습니다.

getSkuDetails() 메서드

getSkuDetails() 메서드를 사용하면 관련 제품 ID 목록의 제품 세부정보를 가져올 수 있습니다.

표 4. GetSkuDetails() 매개변수

유형 설명
apiVersion int 앱에서 사용 중인 In-app Billing API의 버전 번호입니다.
packageName String 이 메서드를 호출하는 앱의 패키지 이름입니다.
type String 인앱 항목 유형(일회성 구매의 경우 'inapp', 구독의 경우 'subs')입니다.
skusBundle Bundle 키가 ITEM_ID_LIST인 SKU의 StringArrayList를 포함하는 번들입니다.

getSkuDetails() 메서드가 성공하면 Google Play에서 응답 Bundle을 보냅니다. 쿼리 결과는 DETAILS_LIST 키에 매핑된 문자열 ArrayListBundle에 저장됩니다. 세부정보 목록의 각 문자열에는 단일 제품에 관한 JSON 형식의 제품 세부정보가 포함됩니다. 제품 세부정보를 포함한 JSON 문자열의 필드는 표 5에 요약되어 있습니다.

표 5. getSkuDetails() 요청에서 반환된 제품 항목 세부정보가 포함된 JSON 필드에 관한 설명

설명
productId 제품의 제품 ID입니다.
type 값은 인앱 상품의 경우 inapp, 구독의 경우 subs여야 합니다.
price 형식이 지정된 항목 가격(통화 기호 포함)입니다. 세금을 제외한 가격입니다.
price_amount_micros 마이크로 단위 가격입니다. 1,000,000마이크로 단위는 실제 통화의 1단위와 같습니다. 예를 들어 price"€7.99"일 때 price_amount_micros"7990000"입니다. 이 값은 특정 통화의 현지화된 반올림 가격을 나타냅니다.
price_currency_code priceISO 4217 통화 코드입니다. 예를 들어 price가 영국 파운드로 지정되어 있으면 price_currency_code"GBP"입니다.
title 제품 이름입니다.
description 제품 설명입니다.
subscriptionPeriod ISO 8601 형식으로 지정된 구독 기간입니다. 예를 들어 P1W는 1주, P1M은 1개월, P3M은 3개월, P6M은 6개월, P1Y는 1년에 해당합니다.

참고: 구독의 경우에만 반환됩니다.

freeTrialPeriod Google Play Console에서 설정된 평가판 기간에 ISO 8601 형식을 지정한 것입니다. 예를 들어 P7D는 7일에 해당합니다. 무료 평가판 자격에 관해 자세히 알아보려면 인앱 구독을 참조하세요.

참고: 평가판 기간이 설정된 구독의 경우에만 반환됩니다.

introductoryPrice €3.99와 같이 통화 기호가 포함되었으며 형식이 지정된 초기 구독 가격입니다. 세금을 제외한 가격입니다.

참고: 초기 기간이 설정된 구독의 경우에만 반환됩니다.

introductoryPriceAmountMicros 초기 가격은 마이크로 단위로 되어 있습니다. 통화는 price_currency_code와 같습니다.

참고: 초기 기간이 설정된 구독의 경우에만 반환됩니다.

introductoryPricePeriod ISO 8601 형식이 지정된 초기 가격 결제 기간입니다.

참고: 초기 기간이 설정된 구독의 경우에만 반환됩니다.

introductoryPriceCycles 사용자에게 초기 가격이 주어지는 구독 결제 기간 수입니다(예: 3).

참고: 초기 기간이 설정된 구독의 경우에만 반환됩니다.

getBuyIntent() 메서드

이 메서드는 인앱 결제 구현에 설명된 것과 같이 RESPONSE_CODE 키에 매핑된 응답 코드 정수 및 PendingIntent를 반환하여 BUY_INTENT 키에 매핑된 인앱 항목의 구매 절차를 시작합니다. 이 메서드가 PendingIntent를 수신하면 Google Play가 그 구매주문서에 관한 데이터를 포함한 응답 Intent를 보냅니다. 응답 Intent에서 반환되는 데이터는 표 6에 요약되어 있습니다.

참고: 이 메서드를 사용하는 대신 추가 기능을 갖춘 getBuyIntentExtraParams()를 사용하는 것이 좋습니다.

표 6. 인앱 결제 구매 요청의 응답 데이터

설명
RESPONSE_CODE 구매에 성공하면 값이 0, 그러지 않으면 오류입니다.
INAPP_PURCHASE_DATA 구매주문서의 세부정보가 포함된 JSON 형식의 문자열입니다. JSON 필드에 관한 설명은 표 7을 참조하세요.
INAPP_DATA_SIGNATURE 개발자의 개인 키로 서명된 구매 데이터의 서명이 포함된 문자열입니다. 데이터 서명에는 RSASSA-PKCS1-v1_5 스키마가 사용됩니다.

표 7에는 구매주문서의 응답 데이터에서 반환되는 JSON 필드가 설명되어 있습니다.

표 7. INAPP_PURCHASE_DATA의 JSON 필드에 관한 설명

필드 설명
autoRenewing 구독이 자동으로 갱신되는지 여부를 나타냅니다. true인 경우 구독이 활성 상태이며, 다음 결제 날짜에 자동으로 갱신됩니다. false인 경우 사용자가 구독을 취소했다는 의미입니다. 사용자는 다음 결제 날짜까지 구독 콘텐츠에 액세스할 수 있으며, 자동 갱신을 다시 활성화하거나 수동 갱신에 설명되어 있는 것처럼 수동으로 갱신하지 않으면 결제 날짜에 액세스 권한을 잃게 됩니다. 유예 기간을 제공하면 유예 기간이 지나지 않는 한 모든 구독에서 이 값이 true로 유지됩니다. 유예 기간이 끝나거나 사용자가 결제 수단 문제를 해결할 때까지는 다음 결제 날짜가 매일 동적으로 연장됩니다.
orderId 거래의 고유 주문 식별자입니다. 이 식별자는 Google 결제 주문 ID에 대응됩니다.
packageName 구매가 시작된 애플리케이션 패키지입니다.
productId 항목의 제품 식별자입니다. 항목마다 제품 ID가 있는데, Google Play Console의 애플리케이션 제품 목록에서 이 ID를 지정해야 합니다.
purchaseTime 제품이 구매된 시간을 Epoch 기준 시간(1970년 1월 1일) 이후 밀리초 단위로 나타낸 것입니다.
purchaseState 주문의 구매 상태입니다. 항상 0(구매함)이 반환됩니다.
developerPayload 주문의 추가 정보가 포함된 개발자 지정 문자열입니다. getBuyIntent 요청을 할 때 이 필드의 값을 지정할 수 있습니다.
purchaseToken 특정 항목과 사용자 쌍의 구매를 고유하게 식별하는 토큰입니다.

consumePurchase() 메서드

주어진 구매 토큰에 해당하는 구매를 사용합니다. 이렇게 하면 이 항목이 getPurchases()에 관한 이후의 모든 응답에서 삭제되며, 같은 SKU의 항목을 재구매할 수 있도록 허용됩니다.

표 8. consumePurchase() 매개변수

유형 설명
apiVersion int 앱에서 사용 중인 In-app Billing API의 버전 번호입니다.
packageName String 이 메서드를 호출하는 앱의 패키지 이름입니다.
purchaseToken String 사용될 구매를 식별하는 구매 정보 JSON의 토큰입니다.

이 메서드는 성공한 사용의 RESULT_OK(0)를 반환하고, 실패 시 적절한 응답 코드를 반환합니다.

getBuyIntentToReplaceSkus() 메서드

이 메서드는 구독 구매를 업그레이드하거나 다운그레이드하는 데 사용됩니다. 구매 중인 SKU로 대체될 기존 구매 SKU가 정확히 1개가 포함된 목록이 필요하다는 점을 제외하면 getBuyIntent()와 유사합니다. 사용자가 구매를 완료하면 Google Play는 이전의 SKU를 교환하고, 비례 계산을 통해 사용하지 않은 구독 시간 만큼의 금액을 사용자에게 크레딧으로 돌려줍니다. Google Play는 이 크레딧을 신규 구독에 적용하고, 크레딧이 소진될 때까지 사용자에게 신규 구독 금액을 청구하지 않습니다.

참고: 이 메서드를 사용하는 대신 추가 기능을 갖춘 getBuyIntentExtraParams()를 사용하는 것이 좋습니다.

이 메서드는 In-app Billing API의 버전 5에서 추가되었습니다. 메서드가 보고되었는지 확인하려면 isBillingSupported AIDL 요청을 보내세요.

참고: 구독 구매에만 이 메서드를 사용할 수 있습니다. 전달된 type 매개변수가 "subs"가 아니라면 메서드가 BILLING_RESPONSE_RESULT_DEVELOPER_ERROR를 반환합니다. 또한 전달된 SKU에는 시즌 구독의 SKU가 포함되어 있지 않을 수 있습니다.

이 메서드는 인앱 결제 구현에 설명된 것과 같이 RESPONSE_CODE 키에 매핑된 응답 코드 정수 및 PendingIntent를 반환하여 BUY_INTENT 키에 매핑된 인앱 구독의 구매 절차를 시작합니다. 이 메서드가 PendingIntent를 수신하면 Google Play가 그 구매주문서에 관한 데이터를 포함한 응답 Intent를 보냅니다. 응답 Intent에서 반환되는 데이터는 표 9에 요약되어 있습니다.

표 9. 인앱 결제 버전 5 구매 요청의 응답 데이터.

설명
RESPONSE_CODE 구매에 성공하면 값은 0입니다. 구매에 실패할 경우에는 오류 코드를 포함합니다.
INAPP_PURCHASE_DATA 구매주문서의 세부정보가 포함된 JSON 형식의 문자열입니다. JSON 필드에 관한 설명은 표 6을 참조하세요.
INAPP_DATA_SIGNATURE 개발자의 개인 키로 서명된 구매 데이터의 서명이 포함된 문자열입니다. 데이터 서명에는 RSASSA-PKCS1-v1_5 스키마가 사용됩니다.

getBuyIntentExtraParams() 메서드

이 메서드는 구매 요청으로 시작됩니다. 또한 getBuyIntent() 메서드의 변형이며, 추가 extraParams 매개변수가 필요합니다. 이 매개변수는 표 10에 제시된 메서드의 실행에 영향을 주는 선택적 키 및 값의 Bundle입니다.

표 10. getBuyIntentExtraParams() 추가 매개변수

유형 설명
skusToReplace List<String> 사용자가 업그레이드 또는 다운그레이드하는 SKU가 정확히 1개 포함된 선택적 목록입니다. 구매가 기존 구독을 업그레이드 또는 다운그레이드하는 경우 이 필드를 전달합니다. 지정된 SKU는 사용자가 구매 중인 SKU로 대체됩니다. Google Play는 다음 결제 주기가 시작될 때 지정된 SKU를 대체합니다.
replaceSkusProration boolean

사용자가 업그레이드 또는 다운그레이드하는 SKU에서 사용하지 않은 구독 기간과 관련하여 사용자에게 크레딧을 제공할지 여부를 지정합니다. 이 필드를 true로 설정하면 Google Play는 이전의 SKU를 교환하고, 비례 계산을 통해 사용하지 않은 구독 시간 만큼의 금액을 사용자에게 크레딧으로 돌려줍니다. Google Play는 이 크레딧을 신규 구독에 적용하고, 크레딧이 소진될 때까지 사용자에게 신규 구독 금액을 청구하지 않습니다.

이 필드를 false로 설정하면 사용자가 사용하지 않은 구독 기간의 크레딧을 받지 못하며, 갱신 날짜도 변경되지 않습니다.

기본값은 true입니다. skusToReplace를 전달하지 않으면 무시됩니다.

accountId String

앱에서 사용자 계정과 고유하게 연결된 선택적 난독화 문자열입니다. 이 값을 전달하면 Google Play에서 이 값을 사용하여 짧은 기간 내에 같은 계정에서 여러 기기로 구매하는 등의 비정상적인 활동을 감지할 수 있습니다.

이 필드에 개발자 ID나 사용자의 Google ID를 사용하지 마세요. 또한 이 필드에는 사용자의 ID를 일반 텍스트로 포함해서는 안 됩니다. 사용자의 ID에서 문자열을 생성할 때는 단방향 해시를 사용하고 이 필드에는 해시된 문자열을 저장하는 것이 좋습니다.

vr boolean

제공된 인텐트가 가상 현실(VR) 구매 절차의 시작을 나타내는지 여부를 지정합니다.

참고: 이 추가 매개변수가 앱에 영향을 미치려면 In-app Billing API 버전 7 이상을 사용해야 합니다.

이 메서드는 In-app Billing API 버전 6 이상에서 사용할 수 있습니다.

getPurchases() 메서드

이 메서드는 구매 항목과 프로모션 코드를 사용해 획득한 항목을 모두 포함하여 사용자가 소유하고 있지만 현재 사용되지 않은 제품을 반환합니다. 표 11에는 Bundle에서 반환되는 응답 데이터가 나열되어 있습니다.

표 11. getPurchases 요청의 응답 데이터

설명
RESPONSE_CODE 요청에 성공하면 값은 0이고, 성공하지 못하면 오류입니다.
INAPP_PURCHASE_ITEM_LIST 이 앱에서 구매한 항목의 productid 목록이 포함된 StringArrayList입니다.
INAPP_PURCHASE_DATA_LIST 이 앱에서 구매한 항목의 세부정보가 포함된 StringArrayList입니다. 목록에 있는 각 INAPP_PURCHASE_DATA 항목에 저장되는 세부정보의 목록은 표 6을 참조하세요.
INAPP_DATA_SIGNATURE_LIST 이 앱에서 구매한 항목의 서명이 포함된 StringArrayList입니다.
INAPP_CONTINUATION_TOKEN 사용자가 소유한 다음 인앱 상품 집합을 가져오기 위한 연속 토큰이 포함된 문자열입니다. 이 문자열은 사용자가 소유한 제품 개수가 매우 많을 경우 Google Play 서비스에 의해서만 설정됩니다. 응답에 연속 토큰이 있을 때는 getPurchases를 따로 호출해서 수신한 연속 토큰을 전달해야 합니다. 후속 getPurchases 호출은 더 많은 구매 항목을 반환하고 다른 연속 토큰도 반환할 수 있습니다.

getPurchaseHistory() 메서드

이 메서드는 각 SKU와 관련하여 사용자가 가장 최근에 완료한 구매를 반환합니다. 구매 항목이 만료, 취소, 사용된 경우에도 마찬가지입니다. 표 12에는 Bundle에서 반환되는 응답 데이터가 나열되어 있습니다.

표 12. getPurchaseHistory 요청의 응답 데이터

설명
RESPONSE_CODE 요청에 성공하면 값은 0이고, 성공하지 못하면 오류입니다.
INAPP_PURCHASE_ITEM_LIST 이 앱에서 구매한 항목의 productid 목록이 포함된 StringArrayList입니다.
INAPP_PURCHASE_DATA_LIST 이 앱에서 최근에 구매한 항목의 세부정보가 포함된 StringArrayList입니다. 목록에 있는 각 INAPP_PURCHASE_DATA 항목에 저장되는 세부정보의 목록은 표 6을 참조하세요.
INAPP_DATA_SIGNATURE_LIST 이 앱에서 구매한 항목의 서명이 포함된 StringArrayList입니다.
INAPP_CONTINUATION_TOKEN 사용자가 소유한 다음 인앱 상품 집합을 가져오기 위한 연속 토큰이 포함된 문자열입니다. 이 문자열은 사용자가 소유한 제품 개수가 매우 많을 경우 Google Play 서비스에 의해서만 설정됩니다. 응답에 연속 토큰이 있을 때는 getPurchases를 따로 호출해서 수신한 연속 토큰을 전달해야 합니다. 후속 getPurchases 호출은 더 많은 구매 항목을 반환하고 다른 연속 토큰도 반환할 수 있습니다.

표 13. getPurchaseHistory()에서 반환된 구매 내역의 JSON 필드에 관한 설명입니다.

필드 설명
productId 항목의 제품 식별자입니다. 항목마다 제품 ID가 있는데, Google Play Console의 애플리케이션 제품 목록에서 이 ID를 지정해야 합니다.
purchaseTime 제품이 구매된 시간을 Epoch 기준 시간(1970년 1월 1일) 이후 밀리초 단위로 나타낸 것입니다.
developerPayload 주문의 추가 정보가 포함된 개발자 지정 문자열입니다. getBuyIntent 요청을 할 때 이 필드의 값을 지정할 수 있습니다.
purchaseToken 특정 항목과 사용자 쌍의 구매를 고유하게 식별하는 토큰입니다.

참고: getPurchaseHistory() 메서드의 오버헤드는 Google Play 서버를 호출해야 하므로 getPurchases()보다 큽니다. 사용자의 구매 내역이 실제로 필요하지 않은 경우에는 getPurchases()를 사용해야 합니다.

이 메서드는 In-app Billing API 버전 6 이상에서 사용할 수 있습니다.