API Nhà phát triển Google Play nay được bổ sung chức năng để báo cáo các giao dịch thực hiện qua hệ thống thanh toán thay thế. Hướng dẫn này mô tả cách sử dụng chức năng mới để báo cáo các giao dịch thực hiện qua hệ thống thanh toán thay thế.
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 mua hàng trong ứng dụng. Để 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. Đối với mọi chức năng phụ trợ khác dành cho nhà phát triển nhưng không liên quan đến API về hệ thống thanh toán thay thế, hãy xem hướng dẫn trong phần Tài liệu về hệ thống thanh toán của Google Play
Báo cáo giao dịch mới bên ngoài cho Google Play
Hãy tích hợp với Externaltransactions APIs để báo cáo giao dịch do người dùng tại Hàn Quốc 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í).
Bạn chỉ được báo cáo giao dịch trên các hệ thống thanh toán thay thế do người dùng ở các quốc gia đủ điều kiện thực hiện; trong các trường hợp khác thì lệnh gọi API sẽ không thực hiện được. Quy tắc giới hạn này áp dụng cho tất 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.v.
Báo cáo giao dịch bên ngoài
Bạn phải gọi Externaltransactions API để 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 hệ thống thanh toán thay thế.
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. Bạn phải báo cáo tất cả giao dịch trong vòng 24 giờ kể từ khi giao dịch đó phát sinh.
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ư tự động gia hạn gói thuê bao), 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 một 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 (ví dụ: nâng cấp hoặc hạ cấp gói thuê bao), hoặc nếu giao dịch định kỳ bị huỷ hoặc hết hạn và sau đó người dùng mua lại sản phẩm đó, thì bạn sẽ gửi 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 cứ thông tin nhận dạng cá nhân nào vào mã giao dịch bên ngoài này.
Báo cáo giao dịch mua mới
Mỗi khi thực hiện thành công một giao dịch mua mới trong hệ thống thanh toán thay thế, bạn bắt buộc phải gọi Externaltransactions API. Đối với các giao dịch mua mới này, bạn cần cung cấp một externalTransactionId duy nhất liên kết với giao dịch mua trong phần phụ trợ dưới dạng tham số truy vấn. Bạn không thể sử dụng lại externalTransactionId này trong cùng một mã gói của ứng dụng.
externalTransactionToken mà ứng dụng nhận được thông qua lệnh gọi lại AlternativeBillingListener cũng là yêu cầu bắt buộc có trong nội dung yêu cầu đối với 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). Trong cả hai trường hợp, đây được gọi là giao dịch ban đầu. Sau giao dịch ban đầu, externalTransactionToken không còn cần thiết nữa, và bạn sẽ 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 đưa ra một externalTransactionId mới riêng biệt. 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.
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 đang tìm cách mua
product1với giá 12634,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.
AlternativeBillingListenernhậ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ớiproducttrong 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 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",
"external_subscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
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 riêng biệt mới 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 phát sinh 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.
Yêu cầu minh hoạ:
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",
"external_subscription" {
"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 yêu cầu hoàn tiền cho giao dịch mua trên Google Play
Hãy tích hợp với Externaltransactions API để 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 về việc lặp lại gói thuê bao cụ thể đ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ả 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
Externaltransactions API phải tuân theo hạn mức API hằng ngày cho tất cả lệnh gọi, giống như mọi điểm cuối khác trong API Nhà phát triển Google Play.
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.