Hoàn tiền qua Advanced Commerce API là cách duy nhất để nhà phát triển iOS chủ động hoàn tiền, và Apple vẫn có quyết định cuối cùng

Nhà phát triển iOS thông thường không thể hoàn tiền cho khách hàng. Vào tháng 6 năm 2026, một App Store Commerce Engineer trả lời câu hỏi trên diễn đàn nhà phát triển chỉ bằng một câu: hiện tại nhà phát triển không thể trực tiếp hoàn tiền. Có một ngoại lệ, và nó nằm trong Advanced Commerce API. Ứng dụng được Apple duyệt có thể gửi yêu cầu hoàn tiền Advanced Commerce API, thu hồi gói đăng ký kèm hoàn tiền, hoặc yêu cầu một số tiền tùy chỉnh. Apple vẫn quyết định tiền có được chuyển hay không.

Advanced Commerce API là gì và ai được dùng

Apple phát hành Advanced Commerce API vào ngày 23 tháng 1 năm 2025. API này xử lý In-App Purchase của Apple cho các danh mục cực lớn gồm sản phẩm mua một lần tùy chỉnh, gói đăng ký, và gói đăng ký có add-on tùy chọn. Bạn không phải tạo từng sản phẩm trong App Store Connect. Bạn định nghĩa SKU trên máy chủ của mình và gửi cho Apple tại thời điểm mua.

Quyền truy cập được cấp theo từng ứng dụng. Bạn điền biểu mẫu yêu cầu, và trang điều kiện của Apple nêu ba mô hình kinh doanh phải là cốt lõi của ứng dụng:

• Danh mục cực lớn gồm các sản phẩm mua một lần, như sách nói, lớp học, khóa học hoặc mini app.
• Danh mục cực lớn gồm nội dung đăng ký, trong đó gói của mỗi nhà sáng tạo là một gói đăng ký riêng.
• Một gói đăng ký có add-on tùy chọn, được gia hạn cùng nhau như một giao dịch mua, như kênh cao cấp hoặc thể thao.

Apple cũng cho phép ứng dụng đăng ký khi một chương trình khác cần đến API này. Mini Apps Partner Program, chương trình trả cho thành viên 85% doanh thu In-App Purchase đủ điều kiện trong các mini app được lưu trữ, bắt buộc phải có nó.

Các endpoint hoàn tiền ra đời sau, và cần chữ ký

Phiên bản 1.1, ngày 24 tháng 3 năm 2025, bổ sung Request Transaction Refund và Revoke Subscription. Trang chương trình của Apple cho biết các ứng dụng cung cấp nội dung đăng ký cũng có thể đủ điều kiện dùng các API Cancel, Revoke và Refund để xử lý việc hủy, xác thực nội dung sau khi mua và quản lý danh mục. Trang của mỗi endpoint đều thêm cùng một điều kiện: Account Holder của bạn phải ký Advanced Commerce API Addendum, và nếu phiên bản mới nhất chưa được chấp nhận, lệnh gọi sẽ trả về lỗi. Chính Addendum, không phải tài liệu, liệt kê các trường hợp sử dụng dành cho từng endpoint.

Ba endpoint, đặt cạnh nhau

Cancel a Subscription chặn lần thu phí tiếp theo

Cancel tắt tự động gia hạn. Apple cho biết khách hàng vẫn giữ quyền truy cập đến hết kỳ hiện tại. Không có khoản nào được hoàn. Đây là lựa chọn đúng khi khách muốn dừng và đã dùng hết thời gian họ trả tiền.

Revoke Subscription kết thúc mọi thứ ngay lập tức

Revoke đặt tự động gia hạn thành false và thu hồi gói đăng ký kèm hoàn tiền toàn bộ hoặc theo tỷ lệ. Phần body nhận refundReason, refundRiskingPreference, refundType và requestInfo. Sau đó Apple gửi thông báo REFUND tới endpoint App Store Server Notifications V2 của bạn. Chỉ dẫn của Apple rất rõ: ngừng dịch vụ kể từ revocationDate trong thông báo đó, và không ngừng trước khi thông báo đến.

Request Transaction Refund xử lý từng mục

Đây là công cụ chính xác. Bạn gửi một danh sách mục, mỗi mục nêu SKU, refundReason, refundType và cờ revoke. Với CUSTOM, bạn gửi thêm refundAmount tính bằng phần nghìn đơn vị tiền tệ, nên 4990 nghĩa là 4.99. Nếu gửi số tiền kèm FULL hoặc PRORATED, Apple từ chối với lỗi 4000155. Phản hồi chứa một giao dịch đã ký và, với gói đăng ký, thông tin gia hạn đã ký.

Apple chấp nhận các giá trị refundReason sau: UNINTENDED_PURCHASE, FULFILLMENT_ISSUE, UNSATISFIED_WITH_PURCHASE, LEGAL, OTHER và MODIFY_ITEMS_REFUND. Giá trị thứ bảy, SIMULATE_REFUND_DECLINE, chỉ dùng để kiểm thử trong sandbox và TestFlight, và nó tồn tại vì App Store có thể từ chối.

Apple vẫn có thể từ chối chính yêu cầu hoàn tiền của bạn

Tên endpoint nói đúng bản chất. Đây là một yêu cầu. Hai trường cho thấy quyền quyết định thực sự nằm ở đâu.

refundRiskingPreference mở đường cho việc kiểm tra mức tiêu dùng

Apple mô tả refundRiskingPreference là việc App Store có hỏi bạn dữ liệu tiêu dùng để làm căn cứ quyết định hoàn tiền hay không. Mặc định là true. Khi là true, bạn nhận CONSUMPTION_REQUEST cho chính yêu cầu hoàn tiền của mình và trả lời qua Send Consumption Information. Apple yêu cầu nhà phát triển phản hồi trong vòng 12 giờ kể từ khi nhận CONSUMPTION_REQUEST. Đặt thành false thì thông báo đó sẽ không đến.

Các lỗi báo hiệu bị từ chối

PendingRefundError là lỗi cần lường trước. Nguyên nhân thường gặp là khách hàng đã yêu cầu Apple qua Report a Problem trước khi đội hỗ trợ của bạn kịp xử lý. Dù sao quy định điều kiện của Apple cũng bắt các ứng dụng này cung cấp lối hoàn tiền ngay trong ứng dụng, hoặc liên kết Report a Problem, hoặc API beginRefundRequest, nên cả hai cánh cửa cùng mở một lúc.

Hoàn tiền Advanced Commerce API tốn của bạn bao nhiêu

Chủ động hoàn tiền có vẻ rẻ hơn là đôi co trong tranh chấp. Nhưng đó vẫn là tiền đi ra, và API này khiến một số sai lầm dễ lặp lại trên quy mô lớn.

Thuế nằm trong số tiền tùy chỉnh

Apple cho biết refundAmount được yêu cầu phải bao gồm thuế ở mọi khu vực, trừ Canada và Hoa Kỳ. Nhóm nào tính khoản hoàn CUSTOM từ giá SKU trước thuế sẽ hoàn thiếu cho khách ở mọi storefront khác, rồi mất thời gian hỗ trợ để sửa từng trường hợp.

Những chi phí không lấy lại được

• Chi trả cho nhà sáng tạo: trong danh mục của nhà sáng tạo hoặc nền tảng lưu trữ mini app, phần của nhà sáng tạo thường được trả ngay khi bán. Hoàn tiền cho khách không thu hồi được khoản đó.
• Bản quyền nội dung: phí theo từng tựa phải trả cho bên nắm quyền đối với sách nói hoặc khóa học có thể phát sinh khi có truy cập, tùy hợp đồng của bạn, và hoàn tiền không đảo ngược được.
• Tài nguyên tính toán: streaming, chuyển mã và mọi tác vụ máy chủ cho giao dịch mua đã nằm trong hóa đơn của bạn.
• Lệnh gọi API: các dịch vụ bên thứ ba tính phí theo yêu cầu, từ giọng nói đến suy luận mô hình, vẫn bị tính phí sau khi hoàn tiền.

Hoàn toàn bộ trong khi chỉ định hoàn một mục

Revoke Subscription hoàn tiền và kết thúc toàn bộ gói đăng ký, kể cả add-on. Nếu khách chỉ khiếu nại một add-on, Request Transaction Refund cho phép bạn chỉ hoàn SKU đó, với cờ revoke chỉ đặt cho mục đó. Gọi Revoke Subscription cho một khiếu nại về một mục sẽ trả lại cả doanh thu của gói cơ bản.

Danh sách kiểm tra trước khi bật các tính năng này

• Xác nhận Account Holder của bạn đã chấp nhận Advanced Commerce API Addendum hiện hành, và đặt cảnh báo cho lỗi trả về khi nó hết hiệu lực.
• Tạo UUID requestReferenceId mới cho mỗi yêu cầu, và chỉ dùng lại cùng giá trị đó khi thử lại một lệnh gọi bị hết thời gian chờ.
• Đưa các lệnh gọi hoàn tiền vào hàng đợi. Giới hạn là 5 mỗi giây cho mỗi ứng dụng, và phản hồi 429 có header Retry-After tính bằng mili giây UNIX.
• Kiểm thử trường hợp bị từ chối trong sandbox bằng SIMULATE_REFUND_DECLINE, và nhớ rằng giới hạn sandbox là 10 phần trăm của production.
• Quyết định refundRiskingPreference theo từng trường hợp, và chuẩn bị sẵn bộ phản hồi dữ liệu tiêu dùng cho khung 12 giờ khi giá trị vẫn là true.
• Chỉ kết thúc quyền truy cập khi thông báo REFUND đến, kể từ revocationDate trong đó.
• Ghi lại lý do, số tiền và SKU của mỗi yêu cầu, để bạn thấy tỷ lệ hoàn tiền của mình trước khi Apple thấy.