Google Play Developer API에는 결제 및 연결 프로그램의 거래를 보고하는 추가 기능이 포함되어 있습니다. 이 가이드에서는 이러한 결제 프로그램의 거래를 보고하는 방법을 설명합니다.
백엔드에서 외부 거래를 처리하는 데 필요한 몇 가지 구성요소가 있습니다. 이러한 구성요소를 빌드하려면 Google Play Developer API 구성에 설명된 대로 백엔드 통합을 설정해야 합니다. 결제 및 링크 프로그램에만 적용되는 것이 아닌 개발자 백엔드 기능을 빌드하려면 Google Play 결제 시스템을 참고하세요.
용어집
이 가이드에서는 다음과 같은 용어가 사용됩니다.
- 결제 및 링크 프로그램: Google Play 외부에서 디지털 콘텐츠 구매 또는 앱 다운로드를 지원하는 프로그램입니다. 여기에는 개발자 제공 결제 및 외부 제안 프로그램이 포함됩니다.
- 외부 거래 API: 자격 요건을 충족하는 결제 및 연결 프로그램의 거래를 보고하는 데 사용되는 API입니다.
- 외부 거래: 프로그램 요구사항에 정의된 대로 앱 외부에서 발생하는 적격 거래입니다. 여기에는 디지털 콘텐츠 구매 및 앱 다운로드가 포함됩니다.
- 외부 거래 토큰: 사용자가 외부 거래를 완료할 때 사용할 수 있도록 Play 결제 라이브러리를 통해 제공되는 토큰입니다. 이 토큰은 Google Play에 성공적인 외부 거래를 알리는 데 사용됩니다.
- 외부 거래 ID: 외부 거래를 식별하기 위해 사용자가 생성하는 고유 식별자입니다.
Google Play에 새로운 외부 거래 보고
externaltransactions API와 통합하여 지원되는 국가에서 Google Play 결제 시스템 외부에서 이루어지는 거래(무료 체험판 구매 및 앱 설치로 인한 $0 거래 포함)를 보고합니다. 개발자 제공 결제 또는 외부 제안 가이드라인에 따라 대상 사용자 국가의 결제 및 링크 프로그램에 대한 거래만 시작하고 보고해야 합니다. 그러지 않으면 API 호출이 거부됩니다. 이는 신규 구매, 갱신, 충전, 업그레이드, 다운그레이드, 앱 다운로드를 비롯한 모든 거래에 적용됩니다.
외부 거래 보고
결제 및 연결 프로그램을 통해 결제가 승인된 후에는 externaltransactions API를 호출하여 외부 거래를 보고해야 합니다.
이는 최초 청구, 갱신, 환불을 비롯한 모든 거래에 적용됩니다. 보고 요구사항은 각 청구 및 연결 프로그램의 가이드라인을 참고하세요.
각 외부 거래는 외부 거래 ID와 함께 보고됩니다. 반복 구매(예: 자동 갱신 정기 결제)의 경우 반복 구매의 첫 번째 거래에 연결된 외부 거래 ID를 후속 거래(환불 포함)의 매개변수로 전달해야 합니다. 이렇게 하면 해당 구매에 관해 일련의 거래가 기록됩니다. 제품이 변경되거나 (예: 업그레이드 또는 다운그레이드) 반복 거래가 취소 또는 만료된 후 나중에 동일한 제품이 다시 구매되는 경우 개발자는 새 외부 거래 ID를 전송해야 합니다. 이 외부 거래 ID의 일부로 개인 식별 정보, 독점 정보 또는 기밀 정보를 포함해서는 안 됩니다.
초기 거래 신고
결제 및 연결 프로그램에서 신규 구매 또는 앱 다운로드가 성공할 때마다 externaltransactions API를 호출해야 합니다.
UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener 또는 BillingProgramReportingDetailsListener 콜백을 통해 앱에서 수신한 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"
}
}
초기 거래를 신고할 때는 다음 사항에 유의하세요.
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로 설정하세요. - 외부 앱이 외부 제안 프로그램을 통해 설치된 후에는 외부 앱에서 이루어진 거래를 보고해야 합니다. 이러한 거래를 보고할 때는 거래를 원래 앱 다운로드 이벤트에 연결하세요.
- 앱 다운로드 이벤트에서
externalTransactionToken를 제공합니다. externalOfferDetails필드에서appDownloadEventExternalTransactionId을 앱 다운로드 이벤트의externalTransactionId로 설정합니다.externalOfferDetails의 다른 필드는 필수가 아닙니다.
- 앱 다운로드 이벤트에서
외부 제안을 통해 다운로드한 외부 앱의 트랜잭션 요청 예시:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI
Body
{
"originalPreTaxAmount" : {
"priceMicros": "100000",
"currency": "EUR"
},
"originalTaxAmount" : {
"priceMicros": "10000",
"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",
"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을 전송합니다. 방식은 신규 구매 보고와 비슷합니다.
앱 다운로드 신고
외부 제안 결제 시스템에서 앱 설치를 보고하려면 앱에 제공된 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을 사용자가 활성 상태의 각 정기 결제에 처음 가입한 시간으로 설정합니다. 그런 다음 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를 제공해야 합니다. 자격 요건을 충족하는 개발자인 경우 이 필드를 설정하는 방법에 관한 자세한 내용은 비즈니스 개발 관리자에게 문의하세요.
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 한도에 포함되지 않습니다.