Google Play Developer API에 개발자 제공 결제 또는 외부 혜택 시스템에서 이루어진 거래를 보고하는 추가 기능이 포함되었습니다. 이 가이드에서는 개발자 제공 결제 또는 외부 쿠폰 거래를 보고하는 방법을 설명합니다.
백엔드에서 인앱 구매를 처리하는 데 필요한 몇 가지 구성요소가 있습니다. 이러한 구성요소를 빌드하려면 Google Play Developer API 구성에 설명된 대로 백엔드 통합을 설정해야 합니다. 개발자 제공 결제 또는 외부 혜택 API에만 국한되지 않는 모든 개발자 백엔드 기능에는 Google Play 결제 시스템 문서의 안내가 적용됩니다.
Google Play에 새로운 외부 거래 보고
지원되는 국가에서 Google Play 결제 시스템 외부에서 이루어지는 거래(무료 체험판 구매로 인한 $0 거래 포함)를 보고하려면 Externaltransactions APIs와 통합합니다. 개발자 제공 결제 또는 외부 혜택 시스템에서의 거래는 개발자 제공 결제 또는 외부 혜택 프로그램에서 허용되는 대로 대상 사용자 국가에 대해서만 시작하고 보고해야 합니다. 그러지 않으면 API 호출이 거부됩니다. 이는 신규 구매, 갱신, 충전, 업그레이드, 다운그레이드를 비롯한 모든 거래에 적용됩니다.
외부 거래 보고
개발자 제공 결제 또는 외부 혜택 시스템을 통해 결제가 승인된 후에는 Externaltransactions API를 호출하여 외부 거래를 보고해야 합니다. 이는 최초 청구, 갱신, 환불을 비롯한 모든 거래에 적용됩니다. 모든 거래는 거래 발생 후 24시간 이내에 보고해야 합니다.
각 외부 거래는 외부 거래 ID와 함께 보고됩니다. 반복 구매(예: 자동 갱신 정기 결제)의 경우 반복 구매의 첫 번째 거래에 연결된 외부 거래 ID를 후속 거래(환불 포함)의 매개변수로 전달해야 합니다. 이렇게 하면 해당 구매에 관해 일련의 거래가 기록됩니다. 제품이 변경되거나(예: 업그레이드 또는 다운그레이드) 반복 거래가 취소 또는 만료된 후 나중에 동일한 제품이 다시 구매되는 경우 개발자는 새 외부 거래 ID를 전송합니다. 이 외부 거래 ID의 일부로 개인 식별 정보, 독점 또는 기밀 정보를 포함해서는 안 됩니다.
신규 구매 보고
개발자 제공 결제 또는 외부 혜택 시스템에서 신규 구매가 성공할 때마다 Externaltransactions API를 호출해야 합니다. 이러한 새 구매의 경우 백엔드에서 구매와 연결된 고유
externalTransactionId를 쿼리 매개변수로 제공해야 합니다. 이 externalTransactionId는 동일한 앱의 패키지 ID 내에서 재사용할 수 없습니다.
UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener 또는 ExternalOfferReportingDetailsListener 콜백을 통해 앱에서 수신한 externalTransactionToken도 일회성 구매 및 반복 구매 (예: 정기 결제)의 최초 거래에 관한 요청 본문의 일부로 필요합니다. 두 경우 모두 이를 초기 거래라고 합니다. 최초 거래 후에는 더 이상 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"
}
}
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 한도에 포함되지 않습니다.