Google Play Developer API에는 결제 및 링크 프로그램의 거래를 보고하는 추가 기능이 포함되어 있습니다. 이 가이드에서는 이러한 결제 프로그램의 거래를 보고하는 방법을 설명합니다.
백엔드에서 외부 거래를 처리하는 데 필요한 몇 가지 구성요소가 있습니다. 이러한 구성요소를 빌드하려면 Google Play Developer API 구성에 설명된 대로 백엔드 통합을 설정해야 합니다. 결제 및 링크 프로그램에만 적용되는 것이 아닌 개발자 백엔드 기능을 빌드하려면 Google Play 결제 시스템을 참고하세요.
용어집
이 가이드에서는 다음과 같은 용어가 사용됩니다.
- 결제 및 링크 프로그램: Google Play 외부에서 디지털 콘텐츠 구매 또는 앱 다운로드를 용이하게 하는 프로그램입니다. 여기에는 개발자 제공 결제 및 외부 콘텐츠 프로그램이 포함됩니다.
- 외부 거래 API: 대상 결제 및 링크 프로그램의 거래를 보고하는 데 사용되는 API입니다.
- 외부 거래: 개발자 제공 결제 및 외부 콘텐츠 프로그램에 정의된 대로 앱 외부에서 이루어지는 적격 거래입니다.
- 외부 거래 토큰: 사용자가 외부 거래를 시작할 때 사용할 수 있도록 Play Billing Library를 통해 제공되는 토큰입니다. 이 토큰은 Google Play에 승인된 외부 거래를 알리는 데 사용됩니다.
- 외부 거래 ID: 외부 거래를 식별하기 위해 개발자가 생성하는 고유 식별자입니다.
Google Play에 새로운 외부 거래 보고
지원되는
국가에서 Google Play 결제 시스템 외부에서 이루어지는 거래(무료 체험판 구매 및
앱 설치로 인한 $0 거래 포함)를 보고
하려면 externaltransactions API와 통합합니다. 개발자 제공 결제 및 링크
프로그램에서 허용하는 대로 대상 사용자 국가에 대해서만 결제 및 링크
프로그램의 거래를 시작하고 보고해야 합니다. 그러지 않으면 API
호출이 거부됩니다. 이는 신규 구매, 갱신, 충전, 업그레이드, 다운그레이드, 앱 다운로드를 비롯한 모든 거래에 적용됩니다.
외부 거래 보고
결제 및 링크 프로그램을 통해 결제가 승인된 후에는 externaltransactions API를 호출하여 외부 거래를 보고해야 합니다.
이는 최초 청구, 갱신, 환불을 비롯한 모든 거래에 적용됩니다. 보고 요구사항은 각 결제 및 링크 프로그램의 가이드라인을 참고하세요.
각 외부 거래는 외부 거래 ID와 함께 보고됩니다. 반복 구매(예: 자동 갱신 정기 결제)의 경우 반복 구매의 첫 번째 거래에 연결된 외부 거래 ID를 후속 거래(환불 포함)의 매개변수로 전달해야 합니다. 이렇게 하면 해당 구매에 관해 일련의 거래가 기록됩니다. 제품이 변경되거나 (예: 업그레이드 또는 다운그레이드) 반복 거래가 취소 또는 만료된 후 나중에 동일한 제품이 다시 구매되는 경우 개발자는 새 외부 거래 ID를 전송합니다. 이 외부 거래 ID의 일부로 개인 식별 정보나 독점 또는 기밀 정보를 포함해서는 안 됩니다.
최초 거래 보고
결제 및 링크
프로그램에서 신규 구매 또는 앱 다운로드가 승인될 때마다 externaltransactions API를 호출해야 합니다.
Google Play Billing Library를 통해 앱에서 수신한 externalTransactionToken은 앱 다운로드, 일회성 구매, 반복 구매 (예: 정기 결제) 중 최초 거래를 위한 요청 본문의 일부로 요구됩니다. 이를 최초 거래 라고 합니다. 최초 거래 후에는 새로운 고유 externalTransactionId를 제공하여 후속 거래 (예: 정기 결제 갱신)를 보고합니다. 자세한 내용은
구매의 후속 거래 보고를 참고하세요.
예:
- 개발자가 앱에서 개발자 제공 결제를 구성하고 사용 설정합니다.
- 사용자 1은 지원되는 국가인 대한민국에 거주하며 1개월 무료 체험 혜택이 있는
product1을 월 12,634.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"
}
}
최초 거래를 보고할 때는 다음 사항에 유의하세요.
subscriptionType은RECURRING(자동 갱신 정기 결제) 또는PREPAID(선불 정기 결제)일 수 있습니다.OtherRecurringProduct는 여러 결제 또는 지연된 결제가 필요한 일회성 구매를 나타내는 데 사용해야 합니다. 예를 들어 사전 주문에는 최초 $0 거래가 발생한 후 사전 주문이 처리될 때 SKU 가격에 대한 두 번째 거래가 나중에 발생할 수 있습니다. 후속 거래를 보고하는 방법에 관한 자세한 내용은 구매의 후속 거래 보고를 참고하세요.- 최초 외부 제안 거래를 보고할 때는
ExternalOfferDetails를 제공해야 합니다. 후속 거래에는 필요하지 않습니다 .
세금이
행정 구역 (예: 주 또는 도)에 따라 다른 인도에 거주하는 사용자와 거래하는 경우 해당 구역을
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"
}
}
외부 제안
보고되는 거래가 외부 제안 프로그램에 속하는 경우 거래가 일회성 거래이거나 반복되는 일련의 거래 중 첫 번째 거래인 경우 externalOfferDetails 필드를 설정해야 합니다.
- 앱 다운로드 거래를 보고할 때는
linkType을LINK_TO_APP_DOWNLOAD로 설정하고installedAppPackage및installedAppCategory에 적절한 값을 제공합니다. 자세한 내용은 앱 다운로드 보고를 참고하세요. - 디지털 콘텐츠 제안 거래를 보고할 때는
linkType을LINK_TO_DIGITAL_CONTENT_OFFER로 설정합니다. - 외부 제안 프로그램을 통해 외부 앱이 설치된 후에는 외부 앱에서 이루어진 거래를 보고해야 합니다. 이러한 거래를 보고할 때는 이러한 거래를 원래 앱 다운로드 이벤트에 연결합니다.
- 앱 다운로드 이벤트에서
externalTransactionToken을 제공합니다. externalOfferDetails필드에서appDownloadEventExternalTransactionId를 앱 다운로드 이벤트의externalTransactionId로 설정합니다.externalOfferDetails의 다른 필드는 필요하지 않습니다.
- 앱 다운로드 이벤트에서
외부 제안을 통해 다운로드한 외부 앱의 거래 요청 예시:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI
Body
{
"originalPreTaxAmount" : {
"priceMicros" : "990000", # 0.99 EUR
"currency" : "EUR"
},
"originalTaxAmount" : {
"priceMicros" : "90000", # 0.09 EUR
"currency" : "EUR"
},
"transactionTime" : "2025-11-22T12:45:00Z",
"oneTimeTransaction" : {
"externalTransactionToken" : "my_external_transaction_token_for_link_to_download_event"
},
"userTaxAddress" : {
"regionCode" : "DE"
},
"externalOfferDetails" : {
"appDownloadEventExternalTransactionId" : "my_external_transaction_id_for_link_to_download_event"
}
}
다양한 거래 유형에 관한 업데이트된 Play 서비스 수수료 세부정보는 유럽 경제 지역 (EEA) 사용자를 위한 외부 제안 프로그램 변경사항에서 확인할 수 있습니다.
구매의 후속 거래 보고
동일한 외부 구매에 연결된 사용자 결제가 두 건 이상인 경우가 있습니다(예: 정기 결제 갱신 또는 선불 요금제 충전).
이러한 후속 거래는 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", # 12634 KRW
"currency" : "KRW"
},
"originalTaxAmount" : {
"priceMicros" : "1263000000", # 1263 KRW
"currency" : "KRW"
},
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"initialExternalTransactionId" : "123-456-789",
"externalSubscription" : {
"subscriptionType" : "RECURRING"
}
},
"userTaxAddress" : {
"regionCode" : "KR"
}
}
업그레이드 또는 다운그레이드 보고
사용자가 개발자 제공 결제 시스템에서 정기 결제를 소유한 경우 업그레이드 또는 다운그레이드를 보고하려면 Externaltransactions API에서 동일한 엔드포인트 및 함수를 사용하여 업그레이드 또는 다운그레이드 거래에 대해 앱에 제공된 externalTransactionToken을 전송합니다. 방식은
신규 구매 보고와 비슷합니다.
앱 다운로드 보고
외부 제안 결제 시스템에서 앱 설치를 보고하려면 앱에 제공된
externalTransactionToken을 전송하여 Externaltransactions.createexternaltransaction을 호출해야 합니다. 이를
무료 일회성 거래로 보고합니다. 이 프로세스는
최초 거래를 보고하는 것과 비슷합니다. 요청 본문에 ExternalOfferDetails를 포함해야 합니다.
요청 예시:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros" : "0",
"currency" : "USD"
},
"originalTaxAmount" : {
"priceMicros" : "0",
"currency" : "USD"
},
"transactionTime" : "2025-12-22T12:45:00Z",
"oneTimeTransaction" : {
"externalTransactionToken" : "my_token",
},
"userTaxAddress" : {
"regionCode" : "US"
},
"externalOfferDetails" : {
"linkType" : "LINK_TO_APP_DOWNLOAD",
"installedAppPackage" : "my.external.app",
"installedAppCategory" : "APP"
}
}
개발자 제공 결제 거래의 수동 보고에서 이전
자동 보고 없이 개발자 제공 결제를 제공하는 동안 시작된 활성 정기 결제를 이전하려면 initialExternalTransactionId 또는 externalTransactionToken을 지정하는 대신 migratedTransactionProgram 필드를 사용하여 새로운 무료 거래를 만드세요. transactionTime을 사용자가 활성 상태의 각 정기 결제에 처음 가입한 시간으로 설정합니다. 그런 다음 갱신 거래를 만드는 데 이전에 사용한 initialExternalTransactionId를 제공하여 API를 통해 이러한 정기 결제의 후속 거래를 정상적으로 보고합니다.
정기 결제가 이전되면 이 페이지에 설명된 자동화된 방법을 통해 보고되는 경우 정기 결제의 후속 거래를 더 이상 수동으로 보고할 필요가 없습니다.
정기 결제를 이전하는 동안 이전으로 인해 할당량 중단이 발생하지 않도록 할당량 한도에 유의해야 합니다. 이전해야 하는 정기 결제가 많은 경우 여러 날에 걸쳐 분산하거나 할당량 증가를 요청하세요.
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를 제공해야 합니다. 자격 요건을 충족하는 개발자인 경우 비즈니스 개발 관리자에게 문의하여 이 필드를 설정하는 방법을 자세히 알아보세요.
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에는 Google Play Developer API의 다른 모든 엔드포인트와 마찬가지로 API 할당량이
모든 호출에 적용됩니다.
또한 Externaltransactions API의 경우 Externaltransactions.createexternaltransaction 또는
Externaltransactions.refundexternaltransaction 호출에 분당 쿼리 수
(QPM) 1,200이 적용됩니다. Externaltransactions.getexternaltransaction 호출은 1,200개 QPM 한도에 포함되지 않습니다.