Reminder: By Aug 31, 2024, all new apps and updates to existing apps must use Billing Library version 6 or newer. If you need more time to update your app, you will be able to request an extension until Nov 1, 2024. Learn more.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Google Play 결제 외부에서 수익을 창출하기 위한 백엔드 통합 가이드

이제 Google Play Developer API에 개발자 제공 결제에서 이루어진 거래를 보고하는 기능 또는 외부 제안 시스템 이 가이드에서는 대체 콘텐츠를 신고하는 방법을 설명합니다. 결제 또는 외부 제안 거래를 처리할 수 있습니다

백엔드에서 인앱 구매를 처리하는 데 필요한 몇 가지 구성요소가 있습니다. 이러한 구성요소를 빌드하려면 Google Play Developer API 구성에 설명된 대로 백엔드 통합을 설정해야 합니다. 대상 개발자 제공 결제와 관련 없는 모든 개발자 백엔드 기능 외부 제안 API의 경우 Google Play 결제 시스템 문서가 적용됩니다.

Google Play에 새로운 외부 거래 보고

Externaltransactions APIs와 통합 Google Play 결제 시스템 외부에서 발생한 거래를 지원되는 국가(무료 체험판으로 인해 발생하는 $0 거래 포함) 구매. 개발자 제공 결제 시스템 또는 외부 제안 시스템에서 이루어진 거래 적격한 사용자 국가에 대해서만 허용됨에 따라 시작하고 보고해야 합니다. 개발자 제공 결제에서 또는 외부 제안 프로그램에 참여할 수 없으며, 그러지 않으면 API 호출이 거부되었습니다. 이는 신규 구매, 갱신, 정기 결제와 같은 모든 거래에 적용됩니다. 충전, 업그레이드, 다운그레이드 등이 있습니다.

외부 거래 보고

Externaltransactions API를 호출하여 외부 거래를 보고해야 합니다. 개발자 제공 결제를 통해 결제가 승인된 후 또는 있습니다. 이는 최초 주문 금액을 포함한 모든 거래에 적용됩니다. 청구, 갱신, 환불 등이 있습니다. 모든 거래는 필수 항목입니다. 거래 발생 후 24시간 이내에 보고됨

각 외부 거래는 외부 거래 ID와 함께 보고됩니다. 반복 구매(예: 자동 갱신 정기 결제)의 경우 반복 구매의 첫 번째 거래에 연결된 외부 거래 ID를 후속 거래(환불 포함)의 매개변수로 전달해야 합니다. 이렇게 하면 해당 구매에 관해 일련의 거래가 기록됩니다. 제품이 변경되거나(예: 업그레이드 또는 다운그레이드) 반복 거래가 취소 또는 만료된 후 나중에 동일한 제품이 다시 구매되는 경우 개발자는 새 외부 거래 ID를 전송합니다. 개인 식별 정보를 포함해서는 안 됩니다. 공개 또는 기밀 정보를 거래 ID입니다.

신규 구매 보고

개발자 제공 결제에서 신규 구매가 성공할 때마다 외부 제공 결제 시스템인 경우 Externaltransactions API 호출은 필요합니다. 신규 구매의 경우 고유한 백엔드에서 쿼리로 구매와 연결된 externalTransactionId 매개변수 값으로 사용됩니다. 이 externalTransactionId는 동일한 앱의 패키지 ID입니다.

앱에서 다음을 통해 수신한 externalTransactionToken UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener 또는 ExternalOfferReportingDetailsListener 콜백도 일회성 구매 및 첫 거래에 대한 요청 본문을 반복 구매 (예: 구독) 두 경우 모두 이를 최초 거래 중 하나입니다. 최초 거래 후에는 externalTransactionToken이(가) 더 이상 필요하지 않으며, 후속 조치를 보고합니다. 구독 갱신과 같은 새로운 거래 내역을 찾을 수 있도록 externalTransactionId 구매의 후속 거래 보고를 참고하세요. 를 참조하세요.

예:

개발자가 앱에서 개발자 제공 결제를 구성하고 사용 설정합니다.
사용자 1은 지원되는 국가인 대한민국에 거주하며 1개월 무료 체험 혜택이 있는 product1을 월 12634.10원에 구매하려고 합니다.
앱은 product1의 ProductDetails 및 사용자가 선택한 혜택을 사용하여 구매 흐름을 시작합니다.
사용자 1이 개발자의 개발자 제공 결제 시스템을 선택합니다.
UserChoiceBillingListener가 값 my_token을 externalTransactionToken으로 수신합니다.
개발자가 백엔드로 관련 정보(externalTransactionToken 값 및 구매가 진행 중인 제품)를 전송합니다. 그런 다음 개발자 제공 결제 시스템에서 product1의 구매 흐름을 시작합니다. 이 거래에 Google Play에 보고하는 데 사용되는 개발자 측에서 고유한 거래 ID 123-456-789가 할당됩니다. 거래 ID는 사용자가 무료 체험판을 받음에도 불구하고 필요합니다.
개발자 제공 결제 시스템에서 구매 거래가 이루어진 후에 개발자가 다음 요청을 사용하여 Google Play에 거래를 보고합니다. 사용자가 1개월 무료 체험을 받았으므로 처음에는 0달러 거래로 보고됩니다.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

세금이 행정 구역(예: 주 또는 도)에 따라 다른 인도에 거주하는 사용자와 거래하는 경우 userTaxAddress에 해당 구역을 포함해야 합니다. 관련 행정 구역은 API 참조 가이드에서 사전 정의된 문자열 목록을 참고하세요.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

구매의 후속 거래 보고

동일한 외부 구매에 연결된 사용자 결제가 두 건 이상인 경우가 있습니다(예: 정기 결제 갱신 또는 선불 요금제 충전). 이러한 후속 거래는 Externaltransactions에서 동일한 API를 사용하여 보고할 수 있습니다. 신규 구매 보고에 설명된 대로, 후속 거래에는 externalTransactionToken이 필요하지 않습니다. 대신 각 갱신 또는 충전 거래의 쿼리 매개변수로 새로운 고유 externalTransactionId가 initialExternalTransactionId 필드의 최초 거래 ID와 함께 전송됩니다.

앞에서 든 예를 이어서 설명하면 다음과 같습니다.

사용자 1의 첫 번째 갱신은 개발자 제공 결제 시스템에서 이루어집니다. 최초 거래 ID는 123-456-789였습니다.
개발자는 URL 쿼리 매개변수의 반복 거래를 새 거래의 외부 거래 ID로 보고하고, initialExternalTransactionId 필드에 있는 최초 거래의 외부 거래 ID를 참조합니다.

샘플 요청:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

업그레이드 또는 다운그레이드 보고

사용자가 개발자 제공 결제 시스템에서 정기 결제를 소유한 경우 업그레이드 또는 다운그레이드를 보고하려면 Externaltransactions API에서 동일한 엔드포인트 및 함수를 사용하여 업그레이드 또는 다운그레이드 거래에 대해 앱에 제공된 externalTransactionToken을 전송합니다. 방식은 신규 구매 보고와 비슷합니다.

개발자 제공 결제 거래의 수동 보고에서 이전

자동 보고 없이 개발자 제공 결제를 제공하는 동안 시작된 활성 정기 결제를 이전하려면 initialExternalTransactionId 또는 externalTransactionToken을 지정하는 대신 migratedTransactionProgram 필드를 사용하여 새로운 무료 거래를 만드세요. transactionTime을 사용자가 활성 상태의 각 정기 결제에 처음 가입한 시간으로 설정합니다. 그런 다음 API를 통해 이러한 정기 결제의 각 후속 거래를 정상적으로 보고하고 위에서 갱신 거래를 만드는 데 사용된 initialExternalTransactionId를 제공합니다. 정기 결제가 이전되면 이 페이지에 설명된 자동화된 방법을 통해 보고되는 경우 정기 결제의 후속 거래를 더 이상 수동으로 보고할 필요가 없습니다.

정기 결제를 이전하는 동안 이전으로 인해 할당량 중단이 발생하지 않도록 할당량 한도에 유의해야 합니다. 여러 구독이 필요한 경우 여러 날에 걸쳐 이전하거나 증가를 요청하세요. 할당량 에서 자세한 내용을 확인하실 수 있습니다.

migratedTransactionProgram 필드는 수동 보고에서 이전할 때만 사용될 수도 있습니다. 수동 보고가 더 이상 지원되지 않으면 지원 중단될 예정입니다.

샘플 요청:

# Note that the externalTransactionId specified here will used to report subsequent
# transactions.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

    "externalSubscription" {
      "subscriptionType": "RECURRING"
    }
  },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Play 파트너 프로그램 신고

다음과 같은 파트너 프로그램에 참여하는 개발자 Play 미디어 경험 프로그램에서는 외부 거래 보고 시 transaction_program_code 사용 만약 개발자라면 BD/계약 담당 관리자에게 문의하세요. 이 필드를 설정하는 방법에 대한 정보가 포함되어 있습니다.

Google Play에 구매 환불 보고

Google Play 결제 시스템 외부에서 사용자에게 환불된 거래를 보고하려면 Externaltransactions API와 통합합니다. Play가 환불된 거래를 올바르게 식별할 수 있도록 하려면 이전에 보고된 거래에 상응하는 externalTransactionId를 URL 매개변수의 일부로 포함해야 합니다.

정기 결제 구매의 환불을 보고할 때는 환불되는 정기 결제의 해당 반복 externalTransactionId를 참조해야 합니다.

예: 정기 결제에 다음과 같은 거래가 있다고 가정해 보겠습니다.

외부 거래 ID가 ABC.1234-5678-9012-34567인 최초 거래
외부 거래 ID가 ABC.1234-5678-9012-34567..0인 첫 번째 반복 거래
외부 거래 ID가 ABC.1234-5678-9012-34567..1인 두 번째 반복 거래

정기 결제와 관련된 모든 거래의 환불을 보고하려면 최초 거래 1건, 후속 거래 2건, 이렇게 3건의 개별적인 환불 요청을 진행해야 합니다.

이 방법으로는 전액 환불이 모두 가능합니다. (금액이 사용자가 원래 외부 결제 수단으로 지불한 금액과 동일한 경우 거래) 및 부분 환불 (금액이 사용자가 원래 외부 결제 단계에서 지불한 금액보다 적은 경우 합니다. 부분 환불의 경우 환불된 세전 금액을 지정해야 합니다.

API 할당량

Externaltransactions API에는 일일 API 할당량이 적용됩니다. 를 사용해야 합니다.

또한 Externaltransactions API의 경우 Externaltransactions.createexternaltransaction 또는 Externaltransactions.refundexternaltransaction 호출에 분당 쿼리 수(QPM) 1,200이 적용됩니다. Externaltransactions.getexternaltransaction 호출은 1,200개 QPM 한도에 포함되지 않습니다.