Nếu bạn từng đọc về CONSUMPTION_REQUEST ở bất cứ đâu trong vài năm gần đây, hẳn bạn đã thấy một danh sách mười hai trường: thời gian sử dụng tài khoản, tổng số tiền đã mua, thời gian chơi, nền tảng, v.v.
Danh sách đó thuộc về phiên bản cũ của endpoint. Endpoint hiện tại của Apple chỉ nhận năm trường, trong đó ba trường bắt buộc, và bao phủ nhiều loại sản phẩm hơn bản gốc. Không ít tích hợp đang chạy thực tế vẫn được xây dựng theo cấu trúc cũ.
Vì vậy bài viết này sẽ đi qua bản chất thực sự của thông báo này, Apple hiện muốn nhận lại gì, và cách xây dựng một luồng phản hồi đủ vững.
Điểm chính
• CONSUMPTION_REQUEST là một thông báo yêu cầu thông tin trong quá trình xem xét hoàn tiền. Nó không phải là hoàn tiền và cũng không phải là quyết định.
• Apple là bên đưa ra quyết định hoàn tiền. Phản hồi của bạn chỉ là một trong các yếu tố đầu vào.
• Endpoint hiện tại nhận năm trường, ba trường bắt buộc, và áp dụng cho mọi loại sản phẩm.
• Sự đồng ý của khách hàng là bắt buộc. Apple từ chối các yêu cầu chưa xác nhận sự đồng ý.
• Apple yêu cầu phản hồi trong vòng 12 giờ kể từ khi có thông báo.
• Tồn tại hai phiên bản endpoint. Hãy kiểm tra tích hợp của bạn đang gọi phiên bản nào.
Apple CONSUMPTION_REQUEST là gì?
Apple CONSUMPTION_REQUEST là một App Store Server Notification báo cho server của bạn biết rằng một khách hàng đã yêu cầu hoàn tiền, đồng thời mời bạn gửi consumption information về giao dịch mua đó. Thông báo được gửi tới URL nhận thông báo mà bạn đã cấu hình, kèm theo giao dịch liên quan, và cho bạn một khoảng thời gian giới hạn để phản hồi.
Đây không phải là thông báo hoàn tiền. Khi nó đến, chưa có gì được quyết định: Apple đang ở giữa quá trình đánh giá yêu cầu và thu thập bối cảnh trước khi kết luận. Với nhà phát triển, ý nghĩa thực tế khá hẹp: một công việc vừa rơi xuống backend của bạn, nó có thời hạn, và cần dữ liệu mà chỉ hệ thống của bạn nắm giữ.
Vì sao Apple gửi CONSUMPTION_REQUEST?
Vì Apple chỉ nhìn thấy một nửa giao dịch.
Apple biết thứ gì được mua, khi nào, bởi tài khoản nào, và lịch sử của tài khoản đó ra sao. Nhưng Apple không thể nhìn vào bên trong ứng dụng của bạn: số xu đã được cộng chưa, tính năng mở khóa có hoạt động không, hay khách hàng đã dùng bao nhiêu trước khi đòi lại tiền.
“Consumption” ở đây nghĩa là khách hàng đã dùng đến đâu thứ họ mua. Một gói subscription được dùng hằng ngày suốt ba tuần và một gói chưa từng mở trông giống hệt nhau trong mắt Apple. Nhưng với bạn thì không.
Cần nói rõ về giới hạn. Apple không chấp thuận hay từ chối chỉ dựa trên con số consumption. Thông tin này chỉ góp vào một quyết định cân nhắc nhiều yếu tố, và tỷ lệ consumption cao không phải là nút từ chối hoàn tiền.
Apple CONSUMPTION_REQUEST hoạt động như thế nào?
Trình tự diễn ra như sau:
Khách hàng gửi yêu cầu hoàn tiền
↓
Apple bắt đầu xem xét yêu cầu hoàn tiền
↓
CONSUMPTION_REQUEST được gửi tới endpoint nhận thông báo của bạn
↓
Bạn xác minh thông báo và xác định giao dịch
↓
Bạn kiểm tra sự đồng ý và thu thập dữ liệu sử dụng
↓
Bạn gửi consumption information, nếu đáp ứng các yêu cầu
↓
Apple cân nhắc thông tin
↓
Apple đưa ra quyết định hoàn tiền
↓
Bạn theo dõi trạng thái giao dịch sau đó
Một lưu ý. Tài liệu hiện tại của Apple mô tả thông báo này gắn với yêu cầu hoàn tiền trên mọi loại sản phẩm, rộng hơn so với những gì tài liệu cũ gợi ý. Nhưng Apple không công bố bất kỳ cam kết nào rằng thông báo sẽ đến trong mọi trường hợp, nên hãy xây dựng handler phản hồi khi có yêu cầu đến, thay vì logic mặc định rằng lúc nào cũng sẽ có.
Apple yêu cầu nhà phát triển cung cấp thông tin gì?
Endpoint Send Consumption Information hiện tại của Apple nhận năm trường. Ba trường bắt buộc và hai trường tùy chọn.
Trường | Bắt buộc | Ý nghĩa |
customerConsented | Có | Phải là true. Nếu không, Apple từ chối yêu cầu. |
deliveryStatus | Có | Ứng dụng của bạn đã giao giao dịch mua hoạt động bình thường chưa, và nếu chưa thì vì sao. |
sampleContentProvided | Có | Khách hàng có được dùng thử nội dung trước khi mua hay không. |
consumptionPercentage | Không | Mức đã tiêu thụ, tính bằng milliunit (50% là 50000). |
refundPreference | Không | Hoàn toàn bộ, từ chối, hoặc hoàn theo tỷ lệ — mong muốn của bạn, không phải quyết định. |
Hai quy tắc xác thực hay khiến người ta vấp. Nếu trạng thái giao hàng khác "delivered", tỷ lệ consumption phải bằng 0, nếu không yêu cầu sẽ thất bại. Và milliunit không phải phần trăm: đã dùng một nửa là 50000.
Refund preference là phần mới nhất và dễ bị hiểu sai nhất. Bạn có thể cho Apple biết mình muốn hoàn toàn bộ, từ chối, hay hoàn theo tỷ lệ, và Apple cân nhắc điều đó cùng mọi yếu tố khác. Kết quả có thể khác đi. Nếu hoàn tiền theo tỷ lệ được chấp thuận, phần bị thu hồi sẽ xuất hiện trong payload giao dịch, nên logic entitlement của bạn cần xử lý được trường hợp thu hồi một phần.
Khác biệt phiên bản đáng kiểm tra
Apple ghi nhận hai phiên bản của endpoint này, và cách đặt tên dễ gây nhầm. Send Consumption Information V1 là phiên bản cũ hơn, với body mười hai trường mà hầu hết bài viết bên thứ ba vẫn mô tả. Ghi chú của chính Apple trên trang đó hướng In-App Purchases tiêu chuẩn sang endpoint hiện tại, và giới hạn V1 cho các giao dịch mua dùng Advanced Commerce API.
| Endpoint hiện tại | Endpoint V1 |
Số trường trong request | 5 (3 bắt buộc) | 12 |
Loại sản phẩm | Cả bốn loại | Consumable và auto-renewable subscription |
Dùng cho | In-App Purchases tiêu chuẩn | Giao dịch mua qua Advanced Commerce API |
Nếu tích hợp của bạn có trước thay đổi này, hãy bắt đầu từ đây.
Consumption information là gì?
Consumption information là dữ liệu bạn gửi cho Apple mô tả điều gì đã xảy ra với giao dịch mua sau khi khách hàng thanh toán: đã được giao chưa, họ có được dùng thử trước không, và họ đã dùng bao nhiêu.
Nó quan trọng vì đây là phần duy nhất của bức tranh mà Apple không thấy được. Với ứng dụng subscription, nó mô tả khách hàng có dùng dịch vụ sau khi mua hay không. Với consumable, bao nhiêu phần số dư đã được tiêu. Với non-consumable, tính năng mở khóa có hoạt động không.
Từ khóa quan trọng là chính xác. Đây là dữ liệu bạn đã được đồng ý cho phép chia sẻ, lấy từ hồ sơ của mình. Nó không phải một lập luận bạn dựng lên, và việc uốn nắn nó theo kết quả mong muốn mang rủi ro thật sự mà không đem lại lợi ích chắc chắn nào.
Nhà phát triển nên phản hồi CONSUMPTION_REQUEST như thế nào?
Chín bước, và phần lớn công việc nằm ở trước khi bất kỳ yêu cầu nào đến.
1. Nhận thông báo
Yêu cầu được gửi tới URL bạn đặt cho App Store Server Notifications V2. Tài liệu App Store Server Notifications của Apple hướng dẫn cách thiết lập và cấu trúc payload. Một endpoint cấu hình sai đồng nghĩa yêu cầu không bao giờ tới được bạn, mà không hề có cảnh báo.
2. Xác thực thông báo
Payload được ký. Hãy xác minh theo chuỗi chứng chỉ của Apple và xác nhận bundle ID trước khi xử lý bất cứ nội dung nào bên trong.
3. Xác định giao dịch liên quan
Lấy các định danh giao dịch từ payload đã giải mã và đối chiếu với hồ sơ mua hàng của bạn. Không có bản ghi lưu trữ thì không thể tra cứu, và không có cơ sở để mô tả consumption.
4. Kiểm tra xem sự đồng ý có cho phép phản hồi hay không
Apple yêu cầu có sự đồng ý hợp lệ của khách hàng trước khi bạn chia sẻ dữ liệu của họ, và việc thu thập sự đồng ý đó là trách nhiệm của bạn. Thông báo không mang theo cờ đồng ý nào, nên bạn phải biết từ hồ sơ của chính mình. Apple cũng nêu rõ lời nhắc App Tracking Transparency không phải là cơ chế cho việc này: đây là một sự đồng ý riêng, được thu thập trong ứng dụng của bạn. Nếu không có sự đồng ý, hướng dẫn của Apple là không phản hồi. Bài viết của chúng tôi về appAccountToken và phòng vệ hoàn tiền Apple đề cập khía cạnh định danh giúp việc tra cứu này khả thi.
5. Thu thập consumption information liên quan
Đọc trạng thái giao hàng và mức sử dụng từ hệ thống của chính bạn. Nếu bạn theo dõi số dư consumable, con số đó đã có sẵn. Nếu một lần mở khóa thất bại, log của bạn biết điều đó.
6. Chuẩn bị phản hồi được hỗ trợ
Tập hợp các trường bắt buộc, thêm các trường tùy chọn khi bạn có giá trị thực, và kiểm tra các quy tắc xác thực trước.
7. Gửi trong khung thời gian của Apple
Gửi một request PUT tới endpoint consumption, dùng original transaction identifier từ thông báo.
8. Ghi lại phản hồi
Lưu lại bạn đã gửi gì, khi nào, và nhận về gì. Một lần gửi thất bại xác thực trông y hệt một lần thành công nếu bạn không ghi nhận kết quả.
9. Theo dõi kết quả hoàn tiền cuối cùng
Apple gửi quyết định dưới dạng một thông báo riêng. Hãy ghi nhận nó theo giao dịch và khách hàng.
Nhà phát triển có bao lâu để phản hồi?
Tài liệu hiện tại của Apple yêu cầu phản hồi trong vòng 12 giờ kể từ khi nhận thông báo.
Mười hai giờ nghe có vẻ rộng rãi cho đến khi bạn xét đến thời điểm thông báo đến. Yêu cầu đến lúc nửa đêm, vào cuối tuần, trong kỳ nghỉ, và đồng hồ không dừng lại. Một yêu cầu đến lúc 11 giờ đêm thứ Sáu đã hết hạn trước sáng thứ Hai.
Apple không nói rằng bỏ lỡ khung thời gian đồng nghĩa hoàn tiền tự động được chấp thuận, và khẳng định như vậy là sai. Điều nó thực sự có nghĩa đơn giản hơn: bạn đã không cung cấp thông tin mà Apple sẵn sàng cân nhắc, và quyết định được đưa ra mà không có nó.
Điều gì xảy ra sau khi nhà phát triển phản hồi?
Apple đưa thông tin vào quá trình xem xét và quyết định. Bạn sẽ thấy kết quả dưới dạng thông báo: chấp thuận, từ chối, hoặc sau đó bị đảo ngược nếu Apple hủy một khoản hoàn tiền đã chấp thuận trước đó.
Từ đây, công việc là của bạn. Thu hồi entitlement khi hoàn tiền được chấp thuận, khôi phục khi bị đảo ngược, và xử lý trường hợp hoàn theo tỷ lệ khi chỉ một phần giao dịch được hoàn lại.
Trạng thái subscription cũng cần chú ý, vì một kỳ đã hoàn tiền thường kết thúc subscription thay vì để nó tiếp tục chạy, và khoản hoàn tiền phải được phản ánh vào sổ sách doanh thu đúng kỳ.
Sự phân chia này đáng được nói thẳng: bạn cung cấp thông tin, Apple quyết định, rồi bạn giữ hệ thống của mình đồng bộ với kết quả. Ba trách nhiệm riêng biệt, và chỉ trách nhiệm ở giữa thuộc về Apple.
Vì sao xử lý CONSUMPTION_REQUEST thủ công lại khó?
Mọi ràng buộc trong quy trình này đều chống lại việc một người làm bằng tay.
Thông báo đến suốt ngày đêm. Khung thời gian là 12 giờ. Mỗi yêu cầu cần kiểm tra chữ ký, tra cứu giao dịch, đối chiếu người dùng, kiểm tra sự đồng ý, tính toán mức sử dụng, một lời gọi API có xác thực, và một kết quả được ghi log. Không bước nào khó. Nhưng tất cả đều bị giới hạn thời gian và lặp đi lặp lại, và khi mọi thứ suôn sẻ thì chẳng tạo ra gì nhìn thấy được.
Quy mô khiến mọi thứ tệ hơn: nhiều ứng dụng, dữ liệu giao dịch ở một hệ thống còn dữ liệu sử dụng ở hệ thống khác, log phản hồi ngày càng thiếu sót, trạng thái entitlement lệch khỏi trạng thái giao dịch mà không ai cảnh báo. Điều đó không có nghĩa xử lý thủ công lúc nào cũng khiến bạn mất tiền, nhưng rủi ro là có thật và nó âm thầm tích tụ.
Có thể tự động hóa Apple CONSUMPTION_REQUEST không?
Có, và chính hình thái của quy trình ủng hộ điều đó, vì gần như mọi bước đều có tính xác định.
Tự động hóa có thể giám sát và xác minh thông báo, nhận diện riêng các consumption request, ánh xạ giao dịch tới tài khoản, tập hợp phản hồi từ hồ sơ của bạn, theo dõi khung thời gian, gửi đi, ghi log kết quả, ghi nhận quyết định, và đẩy cập nhật entitlement.
Điều nó không thể làm là tác động đến quyết định của Apple. Không công cụ nào thay đổi được điều đó, và bất kỳ sản phẩm nào ngụ ý ngược lại đều đang mô tả sai quy trình. Điều tự động hóa thay đổi là liệu phần việc phía bạn có diễn ra nhất quán và trong khung thời gian hay không.
RefundSensor giúp nhà phát triển xử lý quy trình hoàn tiền Apple như thế nào
Quản lý hoàn tiền App Store là hạng mục mà công việc này thuộc về. RefundSensor đảm nhận phần việc phía nhà phát triển: giám sát các quy trình liên quan đến hoàn tiền của Apple, xử lý luồng phản hồi CONSUMPTION_REQUEST được hỗ trợ, và giữ các sự kiện cùng kết quả hoàn tiền ở một nơi thay vì rải rác trên nhiều dashboard và bảng tính.
Trên thực tế, phản hồi được gửi đi trong khung thời gian mà không cần ai canh thông báo, và hồ sơ hoàn tiền vẫn chính xác khi khối lượng tăng lên. Nó không ngăn được hoàn tiền và không thể đảm bảo bất kỳ quyết định cụ thể nào từ Apple. Nó giảm bớt việc giám sát thủ công và các bước bị bỏ sót.
Các quy tắc này được ghi ở đâu
Ba nguồn từ Apple làm nền cho mọi điều ở trên. Hãy đọc trực tiếp và kiểm tra lại thường xuyên — lĩnh vực này mới thay đổi gần đây và các nguồn thứ cấp thường đi sau.
Send Consumption Information — endpoint hiện tại. Yêu cầu về sự đồng ý, khung 12 giờ, body request năm trường, và các loại sản phẩm được áp dụng. Hãy xây dựng theo endpoint này cho In-App Purchases tiêu chuẩn.
Send Consumption Information V1 — endpoint cũ hơn với body mười hai trường. Hữu ích để xác định tích hợp của bạn đang ở phiên bản nào, và cho các đội dùng Advanced Commerce API.
App Store Server Notifications — cách thông báo tới backend của bạn, định dạng payload đã ký, và các loại thông báo bao gồm CONSUMPTION_REQUEST cùng các kết quả hoàn tiền.
Nếu việc này vẫn đang được làm thủ công
Khung 12 giờ và những thông báo đến lúc 3 giờ sáng không hợp với một quy trình phụ thuộc vào việc ai đó kiểm tra dashboard.
Nếu đội của bạn đang ở tình trạng đó, RefundSensor đảm nhận phần việc phía nhà phát triển trong các quy trình này: giám sát thông báo, chuẩn bị và gửi phản hồi trong khung thời gian, và theo dõi kết quả cho tới hồ sơ entitlement của bạn.
Câu hỏi thường gặp
Là một App Store Server Notification báo cho server của bạn biết một khách hàng đã yêu cầu hoàn tiền và Apple đang mời bạn gửi consumption information về giao dịch mua đó. Đây không phải thông báo hoàn tiền và cũng không phải quyết định. Apple quyết định riêng, dùng phản hồi của bạn như một trong nhiều yếu tố đầu vào.
Vì Apple không thể nhìn vào bên trong ứng dụng của bạn. Apple biết giao dịch và lịch sử tài khoản, nhưng không biết nội dung đã được giao chưa, có hoạt động không, hay khách hàng đã dùng bao nhiêu. Bối cảnh đó nằm trong hệ thống của bạn, và Apple hỏi xin trước khi kết thúc việc xem xét.
Khách hàng yêu cầu hoàn tiền, Apple bắt đầu xem xét, và một thông báo được gửi tới endpoint bạn đã cấu hình. Bạn xác minh thông báo, xác định giao dịch, xác nhận sự đồng ý, thu thập dữ liệu sử dụng, và gửi consumption information trong khung thời gian. Apple cân nhắc, quyết định, rồi gửi kết quả dưới dạng một thông báo riêng.
Trên endpoint hiện tại là năm trường. Ba trường bắt buộc: sự đồng ý của khách hàng, trạng thái giao hàng, và có cung cấp nội dung dùng thử hay không. Hai trường tùy chọn: mức đã tiêu thụ của giao dịch mua, và kết quả hoàn tiền bạn mong muốn. Endpoint V1 trước đây yêu cầu mười hai trường, đó là lý do các bài viết cũ mô tả một danh sách dài hơn nhiều.
Tài liệu hiện tại của Apple mô tả thông báo này gắn với yêu cầu hoàn tiền trên mọi loại sản phẩm, rộng hơn so với tài liệu cũ. Nhưng Apple không công bố cam kết cho mọi trường hợp, nên hãy xây dựng handler phản hồi khi có yêu cầu đến, thay vì logic phụ thuộc vào việc lúc nào cũng sẽ có.
Tài liệu của Apple yêu cầu phản hồi trong vòng 12 giờ kể từ khi có thông báo. Yêu cầu đến vào bất kỳ giờ nào, kể cả cuối tuần, nên đây là bước dễ bị bỏ lỡ nhất trong một quy trình thủ công. Hãy kiểm tra trang của Apple để biết yêu cầu hiện hành thay vì dựa vào một tích hợp cũ.
Bạn có thể cung cấp thông tin cho quyết định, chứ không kiểm soát được nó. Dữ liệu consumption chính xác cho Apple bối cảnh mà họ vốn thiếu, và endpoint hiện tại cho phép bạn nêu mong muốn về việc hoàn tiền. Apple cân nhắc cả hai cùng các yếu tố khác và có thể quyết định khác đi. Không có cơ chế nào để nhà phát triển chấp thuận hay từ chối hoàn tiền.
Có. Xác minh thông báo, xác định giao dịch, kiểm tra trạng thái đồng ý, tập hợp dữ liệu từ hồ sơ, đáp ứng khung thời gian, gửi đi, và ghi log kết quả đều là các bước có tính xác định. Phần vẫn cần con người là thiết kế luồng xin đồng ý trong ứng dụng và quyết định chính sách refund preference của bạn.
