Google Play Developer API bao gồm chức năng bổ sung để báo cáo các giao dịch từ chương trình thanh toán và liên kết. Hướng dẫn này mô tả cách báo cáo giao dịch từ các chương trình thanh toán này.
Trong phần phụ trợ có thể có một vài thành phần cần thiết để xử lý các giao dịch bên ngoài. Để tạo các thành phần như vậy, bạn cần thiết lập quy trình tích hợp phần phụ trợ theo chỉ dẫn trong phần Định cấu hình API Nhà phát triển Google Play. Để xây dựng chức năng phụ trợ dành cho nhà phát triển nhưng không liên quan đến chương trình thanh toán và liên kết, hãy xem phần Hệ thống thanh toán của Google Play.
Bảng chú giải thuật ngữ
Sau đây là hướng dẫn về quy ước sử dụng thuật ngữ:
- Chương trình thanh toán và đường liên kết: Các chương trình hỗ trợ việc mua nội dung kỹ thuật số hoặc tải ứng dụng xuống bên ngoài Google Play. Trong đó có chương trình hệ thống thanh toán thay thế và chương trình nội dung bên ngoài.
- API giao dịch bên ngoài: Các API dùng để báo cáo giao dịch cho những chương trình thanh toán và liên kết đủ điều kiện.
- Giao dịch bên ngoài: Giao dịch đủ điều kiện diễn ra bên ngoài ứng dụng theo định nghĩa của chương trình hệ thống thanh toán thay thế và chương trình nội dung bên ngoài.
- Mã thông báo giao dịch bên ngoài: Mã thông báo được cung cấp thông qua Thư viện Play Billing để bạn sử dụng khi người dùng bắt đầu một giao dịch bên ngoài. Mã thông báo này được dùng để thông báo cho Google Play về một giao dịch bên ngoài được uỷ quyền.
- Mã giao dịch bên ngoài: Giá trị nhận dạng riêng biệt do bạn tạo ra để xác định một giao dịch bên ngoài.
Định cấu hình quyền trên Play Console
Để gọi API externaltransactions nhằm báo cáo hoặc hoàn tiền cho các giao dịch bên ngoài, hãy cấp cho tài khoản dịch vụ của bạn quyền Quản lý đơn đặt hàng và gói thuê bao trong Google Play Console. Bạn có thể cấp
quyền này ở cấp tài khoản hoặc cho các ứng dụng cụ thể.
Để biết hướng dẫn về cách tạo tài khoản dịch vụ và cấp quyền trong Play Console, hãy xem bài viết Sử dụng tài khoản dịch vụ. Để biết thêm thông tin về các quyền trong Play Console, hãy xem bài viết Thêm người dùng tài khoản nhà phát triển và quản lý quyền.
Báo cáo giao dịch mới bên ngoài cho Google Play
Hãy tích hợp với API externaltransactions để báo cáo các giao dịch do người dùng tại những quốc gia được hỗ trợ thực hiện bên ngoài hệ thống thanh toán của Google Play (kể cả giao dịch 0 đồng khi mua bản dùng thử miễn phí và cài đặt ứng dụng). Bạn chỉ được bắt đầu và báo cáo giao dịch trong các chương trình thanh toán và liên kết cho người dùng đủ điều kiện ở những quốc gia đủ điều kiện theo quy định của chương trình hệ thống thanh toán thay thế và nội dung bên ngoài, nếu không lệnh gọi API sẽ bị từ chối. Quy định này áp dụng cho tất cả các giao dịch, bao gồm cả giao dịch mua mới, gia hạn, nạp tiền, nâng cấp, hạ cấp và tải ứng dụng xuống.
Báo cáo giao dịch bên ngoài
Bạn phải gọi API externaltransactions để báo cáo giao dịch bên ngoài sau khi khoản thanh toán được uỷ quyền thông qua một chương trình thanh toán và liên kết.
API này áp dụng cho tất cả giao dịch, bao gồm cả các khoản phí ban đầu, gia hạn, hoàn tiền và các giao dịch khác. Hãy xem nguyên tắc về chương trình thanh toán và liên kết tương ứng để biết
các yêu cầu về báo cáo.
Mỗi giao dịch bên ngoài sẽ được báo cáo bằng một mã giao dịch bên ngoài. Đối với các giao dịch mua định kỳ (chẳng hạn như các gói thuê bao tự động gia hạn), bạn cần gửi mã giao dịch bên ngoài liên kết với giao dịch đầu tiên trong giao dịch mua định kỳ dưới dạng tham số cho mọi giao dịch tiếp theo (kể cả giao dịch hoàn tiền). Việc này sẽ ghi lại chuỗi giao dịch của giao dịch mua ban đầu đó. Khi sản phẩm thay đổi (chẳng hạn như khi nâng cấp/hạ cấp) hoặc nếu giao dịch mua định kỳ bị huỷ hay hết hạn và sau đó, người dùng mua lại cùng một sản phẩm, thì bạn nên gửi một mã giao dịch bên ngoài mới cho những giao dịch mua như vậy. Bạn không được đưa bất kỳ thông tin nhận dạng cá nhân hay thông tin mật/thông tin thuộc quyền sở hữu riêng nào vào mã giao dịch bên ngoài này.
Báo cáo giao dịch ban đầu
Mỗi khi một giao dịch mua hoặc lượt tải ứng dụng mới được uỷ quyền trong các chương trình thanh toán và liên kết, bạn phải gọi API externaltransactions.
externalTransactionToken mà ứng dụng nhận được thông qua Thư viện Google Play Billing là yêu cầu bắt buộc có trong nội dung yêu cầu đối với lượt tải ứng dụng xuống, giao dịch mua hàng một lần và giao dịch đầu tiên đối với dạng giao dịch mua định kỳ (chẳng hạn như gói thuê bao). Đây được gọi là giao dịch ban đầu. Sau giao dịch ban đầu, hãy báo cáo các giao dịch tiếp theo (chẳng hạn như gia hạn gói thuê bao) bằng cách cung cấp một externalTransactionId mới duy nhất. Để biết thêm thông tin, hãy xem phần Báo cáo giao dịch tiếp theo của một giao dịch mua.
Ví dụ:
- Nhà phát triển định cấu hình và bật hệ thống thanh toán thay thế trong ứng dụng của mình.
- Người dùng 1 ở Hàn Quốc (một quốc gia được hỗ trợ) đang tìm cách mua
product1với giá 12.634,1 KRW/tháng, với ưu đãi dùng thử miễn phí một tháng. - Ứng dụng sẽ bắt đầu quy trình mua bằng
ProductDetailschoproduct1và ưu đãi mà người dùng đã chọn. - Người dùng 1 chọn hệ thống thanh toán thay thế của nhà phát triển.
UserChoiceBillingListenernhận giá trịmy_tokendưới dạngexternalTransactionToken.- Sau đó, nhà phát triển sẽ gửi thông tin liên quan đến phần phụ trợ của họ (giá trị
externalTransactionTokenvà sản phẩm đang được mua). Sau đó, họ sẽ bắt đầu quy trình mua đối vớiproduct1trong hệ thống thanh toán thay thế. Giao dịch này sẽ được gán một mã giao dịch duy nhất ở phía nhà phát triển, dùng để báo cáo cho Google Play: 123-456-789. Mã giao dịch là bắt buộc, mặc dù người dùng sẽ nhận được một bản dùng thử miễn phí. - Sau khi giao dịch mua được thực hiện trong hệ thống thanh toán thay thế, nhà phát triển sẽ báo cáo giao dịch này cho Google Play bằng yêu cầu sau đây. Ban đầu, giá trị này được báo cáo là giao dịch trị giá 0 đồng vì người dùng được sử dụng miễn phí một tháng.
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"
}
}
Khi báo cáo giao dịch ban đầu, hãy lưu ý những điều sau:
subscriptionTypecó thể làRECURRING(đối với gói thuê bao tự động gia hạn) hoặcPREPAID(đối với gói thuê bao trả trước).- Bạn phải sử dụng
OtherRecurringProductđể thể hiện các giao dịch mua hàng một lần yêu cầu nhiều lần thanh toán hoặc thanh toán chậm. Ví dụ: một đơn đặt hàng trước có thể có giao dịch ban đầu là 0 USD, sau đó là giao dịch thứ hai vào một ngày sau đó với giá của SKU khi đơn đặt hàng trước được thực hiện. Xem phần Báo cáo giao dịch tiếp theo của một giao dịch mua để biết thêm thông tin chi tiết về cách báo cáo các giao dịch tiếp theo. - Bạn phải cung cấp
ExternalOfferDetailskhi báo cáo giao dịch ban đầu cho ưu đãi bên ngoài. Bạn không cần làm việc này cho các giao dịch tiếp theo.
Nếu bạn đang giao dịch với một người dùng ở Ấn Độ, nơi thuế phụ thuộc vào khu vực hành chính của họ (chẳng hạn như tiểu bang hoặc tỉnh), hãy đưa khu vực đó vào bên dưới userTaxAddress. Tham khảo danh sách các chuỗi được xác định trước trong hướng dẫn tham chiếu API cho khu vực hành chính áp dụng.
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"
}
}
Chào bán bên ngoài
Nếu giao dịch được báo cáo thuộc chương trình chào bán bên ngoài, thì bạn phải đặt trường externalOfferDetails nếu giao dịch đó là giao dịch một lần hoặc giao dịch đầu tiên trong một chuỗi giao dịch định kỳ:
- Khi báo cáo giao dịch tải ứng dụng xuống, hãy đặt
linkTypethànhLINK_TO_APP_DOWNLOADvà cung cấp các giá trị thích hợp choinstalledAppPackagevàinstalledAppCategory. Hãy xem bài viết Báo cáo lượt tải ứng dụng xuống để biết thông tin chi tiết. - Khi báo cáo giao dịch chào bán nội dung kỹ thuật số, hãy đặt
linkTypethànhLINK_TO_DIGITAL_CONTENT_OFFER. - Sau khi một ứng dụng bên ngoài được cài đặt thông qua chương trình chào bán bên ngoài, bạn
phải báo cáo các giao dịch được thực hiện trong ứng dụng bên ngoài đó. Khi báo cáo những
giao dịch này, hãy liên kết các giao dịch này với sự kiện tải ứng dụng xuống ban đầu:
- Cung cấp
externalTransactionTokentừ sự kiện tải ứng dụng xuống. - Trong trường
externalOfferDetails, hãy đặtappDownloadEventExternalTransactionIdthànhexternalTransactionIdcủa sự kiện tải ứng dụng xuống. Các trường khác trongexternalOfferDetailskhông bắt buộc.
- Cung cấp
Ví dụ về yêu cầu giao dịch trong một ứng dụng bên ngoài được tải xuống thông qua ưu đãi bên ngoài:
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"
}
}
Bạn có thể xem thông tin cập nhật về phí dịch vụ của Dịch vụ Play cho các loại giao dịch khác nhau trong bài viết Những thay đổi đối với chương trình chào bán bên ngoài cho người dùng ở Khu vực kinh tế Châu Âu (EEA).
Báo cáo các giao dịch tiếp theo của một giao dịch mua
Trong một số trường hợp, người dùng thực hiện nhiều khoản thanh toán được liên kết với cùng một giao dịch mua bên ngoài, ví dụ: gia hạn gói thuê bao hoặc nạp tiền gói trả trước.
Bạn có thể báo cáo các giao dịch tiếp theo bằng cách sử dụng cùng một API trong Externaltransactions. Như mô tả trong phần Báo cáo giao dịch mua mới, bạn không cần externalTransactionToken cho các giao dịch tiếp theo. Thay vào đó, một externalTransactionId mới duy nhất sẽ được gửi dưới dạng tham số truy vấn cho mỗi giao dịch gia hạn hoặc nạp tiền, kèm theo mã của giao dịch ban đầu có trong trường initialExternalTransactionId.
Tiếp nối ví dụ trước:
- Lần gia hạn đầu tiên của người dùng 1 diễn ra trên hệ thống thanh toán thay thế. Mã giao dịch ban đầu là 123-456-789.
- Đối với giao dịch mới này, nhà phát triển sẽ báo cáo việc lặp lại giao dịch trong tham số truy vấn URL ở dạng mã giao dịch bên ngoài, đồng thời tham chiếu đến mã giao dịch bên ngoài của giao dịch ban đầu trong trường
initialExternalTransactionId.
Ví dụ về yêu cầu:
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"
}
}
Báo cáo giao dịch nâng cấp hoặc hạ cấp
Khi người dùng có một gói thuê bao, để báo cáo một giao dịch nâng cấp hoặc hạ cấp trong hệ thống thanh toán thay thế, hãy sử dụng cùng một điểm cuối và hàm trong Externaltransactions API, qua đó gửi externalTransactionToken được cung cấp cho ứng dụng để thực hiện giao dịch nâng cấp hoặc hạ cấp đó. Phương thức này hoạt động tương tự như cách báo cáo giao dịch mua mới.
Báo cáo lượt tải ứng dụng xuống
Để báo cáo một lượt cài đặt ứng dụng trong hệ thống thanh toán ưu đãi bên ngoài, bạn phải gọi Externaltransactions.createexternaltransaction, gửi externalTransactionToken được cung cấp cho ứng dụng. Hãy báo cáo giao dịch này dưới dạng giao dịch một lần, không tốn phí; quy trình này tương tự như báo cáo giao dịch ban đầu. Hãy nhớ đưa ExternalOfferDetails vào nội dung yêu cầu.
Ví dụ về yêu cầu:
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"
}
}
Di chuyển khỏi báo cáo thủ công về giao dịch qua hệ thống thanh toán thay thế
Để di chuyển các gói thuê bao đang hoạt động được bắt đầu khi bạn cung cấp hệ thống thanh toán thay thế (không có tính năng báo cáo tự động), hãy tạo một giao dịch mới có mức phí bằng 0 thông qua trường migratedTransactionProgram thay vì chỉ định initialExternalTransactionId hoặc externalTransactionToken. Đặt transactionTime thành thời điểm khi người dùng bắt đầu đăng ký cho mỗi gói thuê bao đang hoạt động. Sau đó, hãy báo cáo từng giao dịch tiếp theo của các gói thuê bao này như bình thường thông qua API, cung cấp initialExternalTransactionId đã dùng trước đó để tạo giao dịch gia hạn.
Sau khi di chuyển gói thuê bao, bạn sẽ không cần báo cáo các giao dịch tiếp theo của gói thuê bao này theo cách thủ công nữa, miễn là các giao dịch đó được báo cáo thông qua các phương thức tự động được mô tả trên trang này.
Trong khi di chuyển gói thuê bao, hãy lưu ý đến các giới hạn về hạn mức được áp dụng để đảm bảo việc di chuyển không làm vượt quá hạn mức. Nếu cần di chuyển nhiều gói thuê bao, hãy thực hiện việc này trong nhiều ngày hoặc yêu cầu tăng hạn mức.
Bạn chỉ có thể sử dụng trường migratedTransactionProgram khi di chuyển từ báo cáo thủ công. Tính năng báo cáo thủ công sẽ không được dùng nữa khi không còn được hỗ trợ.
Ví dụ về yêu cầu:
# 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"
}
}
Yêu cầu đối với các chương trình Đối tác của Play
Nhà phát triển tham gia các chương trình đối tác như Chương trình trải nghiệm nội dung đa phương tiện của Play phải cung cấp transaction_program_code khi báo cáo giao dịch bên ngoài. Nếu bạn là nhà phát triển đủ điều kiện, hãy liên hệ với Nhà quản lý phát triển kinh doanh để biết thêm thông tin về cách đặt trường này.
Báo cáo hoàn tiền cho giao dịch mua trên Google Play
Hãy tích hợp với API externaltransactions để báo cáo các giao dịch được hoàn tiền cho người dùng bên ngoài hệ thống thanh toán của Google Play. Để Play xác định chính xác giao dịch nào được hoàn tiền, bạn phải thêm externalTransactionId tương ứng của giao dịch đã báo cáo trước đó trong các tham số URL.
Khi báo cáo các giao dịch hoàn tiền cho giao dịch mua gói thuê bao, hãy tham chiếu đến externalTransactionId của giao dịch định kỳ cụ thể của gói thuê bao đang được hoàn tiền.
Ví dụ: Giả sử một gói thuê bao có các giao dịch sau:
Giao dịch ban đầu có mã giao dịch bên ngoài là ABC.1234-5678-9012-34567
Giao dịch định kỳ đầu tiên có mã giao dịch bên ngoài là ABC.1234-5678-9012-34567..0
Giao dịch định kỳ thứ hai có mã giao dịch bên ngoài là ABC.1234-5678-9012-34567..1
Để báo cáo về việc hoàn tiền cho tất cả các giao dịch của gói thuê bao đó, bạn cần thực hiện 3 yêu cầu hoàn tiền riêng biệt: 1 yêu cầu cho giao dịch ban đầu và 2 yêu cầu cho các giao dịch tiếp theo.
Phương thức này chấp nhận cả giao dịch hoàn tiền toàn bộ (số tiền hoàn bằng với số tiền mà người dùng đã thanh toán trong giao dịch bên ngoài ban đầu) và giao dịch hoàn tiền một phần (số tiền hoàn nhỏ hơn số tiền mà người dùng đã thanh toán trong giao dịch bên ngoài ban đầu). Đối với giao dịch hoàn tiền một phần, bạn cần chỉ định số tiền trước thuế được hoàn lại.
Hạn mức API
API Externaltransactions phải tuân theo hạn mức API cho tất cả các lệnh gọi, giống như mọi điểm cuối khác trong Google Play Developer API.
Ngoài ra, Externaltransactions API có giới hạn là 1.200 truy vấn mỗi phút (QPM) trên các lệnh gọi đến Externaltransactions.createexternaltransaction hoặc Externaltransactions.refundexternaltransaction. Các lệnh gọi đến Externaltransactions.getexternaltransaction sẽ không được tính vào giới hạn 1.200 QPM này.