Nếu ứng dụng của bạn vẫn dùng App Store Server Notifications V1, Apple sẽ không bao giờ hỏi bạn về các yêu cầu hoàn tiền gói đăng ký

Version 1 của App Store Server Notifications vẫn gửi thông tin hoàn tiền, nhưng lại thiếu đúng một thông báo cho phép bạn trình bày lập luận trong một yêu cầu hoàn tiền gói đăng ký. Apple ngừng hỗ trợ V1 vào ngày 5 tháng 6 năm 2023, cùng lúc với endpoint verifyReceipt, và từ đó chỉ bổ sung mọi tính năng liên quan đến hoàn tiền vào V2. Nếu phần cài đặt App Store Connect của bạn vẫn ghi Version 1, Apple có thể quyết định một khoản hoàn tiền gói đăng ký mà không hề gửi CONSUMPTION_REQUEST đến máy chủ của bạn. Bạn không thua trong cuộc tranh luận đó. Bạn chỉ đơn giản là không bao giờ được mời tham gia.

Việc Apple ngừng hỗ trợ App Store Server Notifications V1 có nghĩa là gì

Ngừng hỗ trợ không có nghĩa là bị tắt. Một kỹ sư của Apple đã viết trên diễn đàn nhà phát triển vào tháng 6 năm 2023 rằng verifyReceipt và thông báo V1 sẽ tiếp tục hoạt động cho đến khi có thông báo về ngày kết thúc vòng đời, rằng ngày đó chưa được ấn định và nhà phát triển sẽ được báo trước. Hơn ba năm sau, App Store Connect vẫn cung cấp lựa chọn "Version 1 (deprecated)" khi bạn thiết lập URL máy chủ.

Điều mà việc ngừng hỗ trợ thực sự mang lại là sự đóng băng. Mọi thay đổi trong changelog thông báo của Apple kể từ tháng 6 năm 2023 đều là thay đổi của V2: trường mới trong giao dịch đã ký, loại thông báo mới, dữ liệu cam kết 12 tháng được bổ sung vào tháng 4 năm 2026. Máy chủ V1 không thấy bất kỳ điều nào trong số đó.

Những tín hiệu hoàn tiền mà máy chủ V1 không bao giờ nhận được

Dưới đây là cách cùng một sự kiện hoàn tiền đến máy chủ V1 và máy chủ V2, theo tài liệu của Apple cho từng phiên bản.

V1 có còn nhận CONSUMPTION_REQUEST không?

Có, với sản phẩm tiêu hao. Tài liệu tham khảo V1 của Apple mô tả CONSUMPTION_REQUEST là thông báo được gửi khi khách hàng bắt đầu yêu cầu hoàn tiền cho một giao dịch mua trong ứng dụng loại tiêu hao. Một kỹ sư của Apple đã xác nhận trên diễn đàn vào năm 2023 rằng yêu cầu tiêu thụ của V1 được gửi cho các khoản hoàn tiền đủ điều kiện. Khoảng trống nằm ở gói đăng ký. Changelog của Apple ghi nhận yêu cầu tiêu thụ cho gói đăng ký bắt đầu từ ngày 11 tháng 4 năm 2024, trên V2, và tài liệu Send Consumption Information cho biết Apple gửi yêu cầu này qua endpoint V2 của bạn.

Vì sao CANCEL trên V1 dễ bị hiểu sai

Trên V1, khi Apple hoàn tiền một gói đăng ký, loại thông báo là CANCEL, thường đi kèm DID_CHANGE_RENEWAL_STATUS. Nhiều máy chủ coi mọi lần hủy là việc khách hàng tắt tự động gia hạn, nên quyền truy cập vẫn tiếp tục đến hết kỳ. V2 loại bỏ sự mơ hồ này. Một khoản hoàn tiền đến dưới dạng REFUND, còn việc khách hàng tắt gia hạn đến dưới dạng DID_CHANGE_RENEWAL_STATUS với loại phụ AUTO_RENEW_DISABLED.

Ở lại V1 khiến bạn mất bao nhiêu tiền

Apple quyết định mọi khoản hoàn tiền trên App Store. CONSUMPTION_REQUEST là thời điểm duy nhất dữ liệu sử dụng của bạn đến được với quyết định đó, và Apple yêu cầu bạn trả lời trong vòng 12 giờ. Trên V1, các khoản hoàn tiền gói đăng ký bỏ qua bước này.

Sau đây là một ví dụ với số liệu minh họa. Giả sử ứng dụng của bạn bán gói đăng ký hằng tháng giá $9.99 có bao gồm tạo ảnh bằng AI. Một người đăng ký tạo 400 ảnh trong một tháng, và mỗi lần tạo đều khiến bạn tốn tiền thật cho việc suy luận mô hình. Sau đó họ yêu cầu Apple hoàn tiền.

Khoản thanh toán bạn mất là phần của bạn, không phải giá niêm yết. Apple trả 70% giá gói đăng ký, sau khi trừ các loại thuế áp dụng, trong năm đầu tiên người đăng ký sử dụng dịch vụ trả phí, và 85% sau đó hoặc cho thành viên của App Store Small Business Program. Hóa đơn điện toán thì không giảm theo. Chi phí suy luận, lệnh gọi API của bên thứ ba và lưu trữ tệp đã được trả khi khách hàng sử dụng.

Hai thông báo kết quả bị thiếu cũng gây tốn kém. Không có REFUND_REVERSED, máy chủ đã thu hồi quyền truy cập khi có hoàn tiền sẽ không bao giờ khôi phục quyền đó khi Apple thu hồi khoản hoàn tiền, nên một khách hàng đang trả tiền vẫn bị khóa và phải liên hệ bộ phận hỗ trợ. Không có REFUND_DECLINED, bạn không thể phân biệt một yêu cầu hoàn tiền còn đang chờ với một yêu cầu đã bị Apple từ chối.

Cách chuyển từ V1 sang V2 mà không bỏ sót khoản hoàn tiền nào

Chuyển sang V2 gồm một thay đổi phía máy chủ và một thiết lập. Hướng dẫn của chính Apple trên diễn đàn, từ một App Store Commerce Engineer vào tháng 12 năm 2025, giải thích điều gì xảy ra vào ngày bạn chuyển đổi.

Xây dựng endpoint V2 trước khi đổi thiết lập

• Chấp nhận một yêu cầu POST có body chứa signedPayload. Payload V2 ở định dạng JWS, được Apple ký, vì vậy hãy xác minh chữ ký trước khi tin bất kỳ nội dung nào bên trong. App Store Server Library của Apple làm việc này cho bạn.
• Chuyển phần xử lý CANCEL sang REFUND, và xử lý REFUND_DECLINED cùng REFUND_REVERSED như các trường hợp mới.
• Trả lời CONSUMPTION_REQUEST cho gói đăng ký bằng Send Consumption Information, và chỉ khi khách hàng đã đồng ý chia sẻ dữ liệu với Apple. Apple cho biết nếu không có sự đồng ý thì bạn không nên phản hồi.
• Trả về HTTP 200 đến 206 khi thành công. Bất kỳ mã 40x hoặc 50x nào cũng khiến Apple thử lại.

Đổi thiết lập trong App Store Connect

Trong App Store Connect, mở ứng dụng của bạn, chọn App Information trong mục General, tìm App Store Server Notifications và đặt Production Server URL thành endpoint V2 của bạn với Version 2 được chọn. Nếu muốn kiểm thử, hãy làm tương tự với URL sandbox trước, và dùng Request a Test Notification để xác nhận máy chủ của bạn phản hồi.

Giữ trình xử lý V1 hoạt động trong khoảng ba ngày

Sau khi chuyển đổi, các thông báo mới đến ngay ở định dạng V2, cho mọi gói đăng ký, cũ hay mới. Các thông báo V1 đang được thử lại vẫn tiếp tục đến ở định dạng V1 cho đến khi thành công hoặc hết lượt thử. Apple ước tính lần thử lại V1 cuối cùng có thể xảy ra vào khoảng 78 giờ, tức là 6 cộng 24 cộng 48. Hãy để trình xử lý cũ chạy quá mốc đó rồi mới gỡ bỏ.

Thay thế verifyReceipt luôn trong lúc này

verifyReceipt cũng bị ngừng hỗ trợ cùng ngày. Endpoint này vẫn phản hồi, nhưng Apple khuyến nghị máy chủ dùng App Store Server API thay thế. Get Transaction Info trả về một giao dịch đã ký, Get Transaction History trả về lịch sử của một khách hàng, và Get Refund History liệt kê mọi giao dịch mua đã được hoàn tiền của một khách hàng. Kết hợp với thông báo V2, các API này đáp ứng những gì phần lớn máy chủ từng dùng biên lai để làm, bao gồm cả trường cancellation_date từng đánh dấu một khoản hoàn tiền trong biên lai.

RefundHalt kết nối với App Store Server Notifications V2 và trả lời từng CONSUMPTION_REQUEST trong khung 12 giờ, dựa trên dữ liệu sử dụng mà ứng dụng của bạn đã ghi nhận. Nếu bạn vẫn đang dùng V1, việc chuyển đổi chính là bước giúp mọi điều đó trở nên khả thi.