Đính kèm một appAccountToken vào mọi giao dịch mua trên App Store, nếu không bạn không thể bảo vệ khoản hoàn tiền

Một khách hàng yêu cầu Apple hoàn tiền, Apple gửi cho máy chủ của bạn một CONSUMPTION_REQUEST, và bạn có mười hai giờ để trả lời bằng dữ liệu thực về cách người đó đã dùng sản phẩm. Rồi bạn mở thông báo ra và nhận ra bạn chẳng biết họ là ai. Giao dịch mang một originalTransactionId và một id sản phẩm, nhưng không có gì trỏ tới tài khoản trong cơ sở dữ liệu của riêng bạn. Khoảng trống đó chính là thứ appAccountToken lấp lại, và nếu bạn không thiết lập nó lúc mua, bạn không thể lấp lại sau đó cho giao dịch bán ấy.

appAccountToken là một UUID mà bạn đính kèm vào một giao dịch mua để giao dịch App Store phát sinh mang một con trỏ trở lại đúng người dùng trong hệ thống của bạn. Thiết lập nó, và mọi câu hỏi hoàn tiền mà Apple từng hỏi về khách hàng đó đều đến kèm danh tính của họ. Bỏ qua nó, và bạn đang đoán. Đây là trường này là gì, cách thiết lập nó, endpoint mới cứu vãn các giao dịch mua thực hiện bên ngoài ứng dụng của bạn, và mắt xích thiếu vắng thực sự tốn kém thế nào khi một khoản hoàn tiền ập đến.

appAccountToken thực sự là gì

appAccountToken là một UUID mờ đục mà bạn tạo ra và truyền cho StoreKit vào thời điểm mua. Apple lưu nó trên giao dịch và trả lại trong thông tin giao dịch cho lần mua đó, và nó ở nguyên đó. Theo lời Apple, đó là "UUID liên kết giao dịch với tài khoản người dùng trên dịch vụ của riêng bạn." Quy tắc định dạng duy nhất là nó phải là một UUID. Apple không đọc nó, không xác thực nó ánh xạ tới đâu, và không quan tâm nó có nghĩa gì ở phía bạn. Đó là một liên kết mà bạn kiểm soát.

Vì nó nằm trên giao dịch, nó quay lại ở mọi nơi giao dịch quay lại. Giao dịch đã ký trong một thông báo máy chủ, phản hồi Get Transaction Info của App Store Server API, và mọi lần gia hạn trong một chuỗi đăng ký, tất cả đều mang cùng token nếu bạn thiết lập nó trên giao dịch mua ban đầu. Một UUID, đính kèm một lần, theo dõi việc thanh toán của khách hàng suốt vòng đời mối quan hệ.

Nó phải là một UUID thật, nếu không nó lặng lẽ biến mất

Quy tắc duy nhất Apple áp đặt là định dạng. StoreKit 2 đòi hỏi một UUID RFC 4122. Nếu bạn truyền một chuỗi ghép, một id số nguyên, hay một địa chỉ email, StoreKit không báo lỗi. Nó loại bỏ giá trị và giao dịch quay lại với appAccountToken được đặt thành nil. Các nhà phát triển liên tục gặp phải điều này, và triệu chứng luôn giống nhau, một biến thể nào đó của "appAccountToken bị thiếu trong payload giao dịch" trên chính diễn đàn của Apple, gần như luôn vì giá trị được truyền không phải là một UUID hợp lệ. Hãy tạo một UUID thật ở phía máy chủ, lưu nó ứng với tài khoản, và đừng bao giờ đưa cho StoreKit bất cứ thứ gì khác.

Cách thiết lập nó lúc mua

Trong StoreKit 2 đây là một tùy chọn mua duy nhất. Tạo UUID trên máy chủ của bạn khi người dùng đăng ký hoặc lần đầu đến bước thanh toán, lưu nó trên bản ghi tài khoản của họ, và truyền chính giá trị đó vào lệnh gọi mua.

Chữ ký là Product.PurchaseOption.appAccountToken(_ token: UUID), và một giao dịch mua trông như try await product.purchase(options: [.appAccountToken(token)]). Khi giao dịch quay lại, được xác minh qua App Store Server API hoặc được gửi bởi một thông báo máy chủ, nó mang UUID đó, và máy chủ của bạn tra cứu khách hàng chỉ trong một truy vấn.

Dùng một token ổn định cho mỗi tài khoản

Đừng tạo một token mới cho mỗi giao dịch mua của cùng một người dùng. Apple trả lại token trên các lần gia hạn, thử lại thanh toán và nâng cấp trong cùng một chuỗi, vì vậy một UUID ổn định cho mỗi tài khoản cho bạn một sợi chỉ sạch sẽ từ lần mua đầu tiên qua mọi sự kiện tương lai. Một token thay đổi theo mỗi giao dịch mua làm đứt sợi chỉ đó và phá hỏng toàn bộ mục đích. Một tài khoản, một token, dùng lại mỗi lần tài khoản đó mua.

Endpoint cứu vãn các giao dịch mua ngoài ứng dụng

Cho đến năm 2025 vẫn có một lỗ hổng. Nếu một khách hàng đổi mã ưu đãi hoặc mua một giao dịch mua trong ứng dụng được quảng bá thẳng từ App Store, ứng dụng của bạn không bao giờ chạy luồng mua, nên không có chỗ nào để thiết lập appAccountToken. Những giao dịch đó đến ẩn danh và cứ thế ở nguyên vậy.

WWDC 2025 đã khép lại khoảng trống này bằng endpoint Set App Account Token. Máy chủ của bạn gọi PUT /inApps/v1/transactions/{originalTransactionId}/appAccountToken trên App Store Server API với UUID trong phần thân, và Apple thiết lập token trên giao dịch đó. Nó hoạt động cho mọi loại sản phẩm, bao trùm việc đổi mã ưu đãi và các giao dịch mua được quảng bá, và giá trị bạn gửi ghi đè bất kỳ token nào đã có trên giao dịch. Giờ đây bạn có thể liên kết một giao dịch mua sau thực tế, từ máy chủ của bạn, mà nó không bao giờ đi qua ứng dụng của bạn.

Nơi mắt xích thiếu vắng khiến bạn mất tiền

Mục đích của token không phải là hồ sơ gọn gàng. Mà là câu hỏi hoàn tiền duy nhất của Apple dành cho nhà phát triển, CONSUMPTION_REQUEST, chỉ có thể trả lời được nếu bạn tìm được khách hàng mà nó nói đến.

Khi một người mua yêu cầu hoàn tiền cho một sản phẩm tiêu dùng hoặc một đăng ký không gia hạn, Apple gửi cho máy chủ của bạn một thông báo CONSUMPTION_REQUEST và cho bạn mười hai giờ để trả lời bằng Send Consumption Information. Câu trả lời của bạn là dữ liệu về đúng khách hàng đó: họ đã tiêu thụ bao nhiêu sản phẩm, thời gian gắn bó của tài khoản, tổng chi tiêu trọn đời, tình trạng giao hàng của họ. Bản thân appAccountToken là một trong các trường trong yêu cầu đó, và quan trọng hơn, đó là cách giao dịch của thông báo ánh xạ tới tài khoản mà bạn sắp mô tả mức sử dụng. Không token, không tra cứu, không câu trả lời chính xác.

Một câu trả lời trống thực sự tốn kém thế nào

Một khoản hoàn tiền không nhận diện được ép bạn vào một lựa chọn tồi. Bạn có thể trả lời yêu cầu tiêu thụ bằng chẳng gì cả, điều này được đọc là mức tiêu thụ thấp và đẩy Apple về phía chấp thuận hoàn tiền, kể cả cho những khách hàng đã dùng sản phẩm rất nhiều. Hoặc bạn có thể đoán. Dù cách nào bạn cũng đang hoàn tiền cho những giao dịch mua mà bạn có bằng chứng để bảo vệ, và bạn đã trả chi phí thực để phục vụ chúng.

Chi phí đó không phải là giá bán. Một sản phẩm tiêu dùng đã chạy một loạt lệnh gọi API mô hình, tạo hình ảnh, xuất một video, hay kích hoạt một khoản chi trả cho nhà sáng tạo đã tiêu tiền thật ngay khoảnh khắc nó được cung cấp. Khoản hoàn tiền trả lại tiền của khách hàng. Nó không trả lại hóa đơn của nhà cung cấp. Nhân một khách hàng không thể nhận diện với mỗi khoản hoàn tiền họ nộp, và với mỗi kẻ hoàn tiền hàng loạt trông cậy vào việc bạn không biết họ là ai, và token bạn đã bỏ qua trở thành dòng mã đắt đỏ nhất mà bạn chưa từng viết.

Ý tưởng tương tự tồn tại trên Android, dưới một cái tên khác

Google Play giải quyết đúng vấn đề đó bằng setObfuscatedAccountId, thứ đính kèm một mã định danh tài khoản vào một giao dịch mua để việc xem xét bồi hoàn của Google qua orders.reviewrefund có thể được trả lời dựa trên một người dùng thật. Cửa hàng khác, cơ chế khác, cùng một bài học: đính kèm danh tính lúc mua nếu không bạn không thể bảo vệ tranh chấp về sau. Trên App Store, công cụ đó là appAccountToken, và nó phải là một UUID.

Ba thói quen giữ token đúng chỗ

• Tạo một UUID cho mỗi tài khoản và lưu nó. Một token ổn định cho mỗi khách hàng, tạo khi họ đăng ký hoặc lúc thanh toán lần đầu, lưu trên bản ghi của họ và dùng lại cho mọi giao dịch mua.
• Xác thực trước khi bạn truyền nó. Xác nhận giá trị là một UUID thật trong mã mua của bạn, để một id sai định dạng không bao giờ có thể lặng lẽ trở thành một token nil trên giao dịch.
• Bổ sung cho các giao dịch mua ngoài ứng dụng. Khi một thông báo máy chủ đến cho một lần đổi mã ưu đãi hoặc một giao dịch mua được quảng bá mà không có token, hãy gọi endpoint Set App Account Token để đính kèm token đúng.

Làm ba điều đó và mọi giao dịch Apple từng gửi cho bạn, kể cả các yêu cầu hoàn tiền, đều đến khi đã được gắn với khách hàng mà nó thuộc về.

Đây là nền tảng mà RefundHalt dựa vào. Chúng tôi đọc appAccountToken từ mọi giao dịch và thông báo máy chủ, gắn nó với mức sử dụng mà chúng tôi đã theo dõi cho tài khoản đó, và trả lời yêu cầu tiêu thụ của Apple trong cửa sổ mười hai giờ bằng những con số thực của khách hàng. Token là sợi chỉ. Thiết lập nó một lần và việc bảo vệ hoàn tiền của bạn có thứ gì đó để bám vào.