Tích hợp ban đầu với Stripe

Adapty hỗ trợ các flow web2app bằng cách theo dõi các khoản thanh toán và gói đăng ký được thực hiện qua Stripe.

Tích hợp này bao gồm các giao dịch mua được thực hiện trên web (Stripe Checkout, trang thanh toán được lưu trữ, Payment Links hoặc các flow thanh toán web tùy chỉnh) và đồng bộ hóa chúng với quyền truy cập ứng dụng di động cùng dữ liệu phân tích.

Tích hợp này hữu ích trong các trường hợp sau:

• Tự động cấp quyền truy cập vào các tính năng trả phí cho những người dùng đã mua trên web nhưng sau đó cài đặt ứng dụng và đăng nhập vào tài khoản của họ
• Tập hợp toàn bộ dữ liệu phân tích gói đăng ký trong một Adapty Dashboard duy nhất (bao gồm cohort, dự đoán và các công cụ phân tích khác của chúng tôi)

Mặc dù mua hàng qua web đang ngày càng phổ biến với các ứng dụng, Apple App Store chỉ cho phép hệ thống khác ngoài in-app purchase đối với hàng hóa kỹ thuật số tại Mỹ mà thôi. Hãy đảm bảo bạn không quảng bá gói đăng ký web của mình trong ứng dụng cho các quốc gia khác. Nếu không, ứng dụng của bạn có thể bị từ chối hoặc bị cấm.

Các bước dưới đây hướng dẫn cách cấu hình tích hợp Stripe.

1. Kết nối Stripe với Adapty

Tích hợp này chủ yếu dựa vào việc Adapty lấy dữ liệu gói đăng ký từ Stripe qua webhook. Do đó, bạn cần kết nối tài khoản Adapty của mình với tài khoản Stripe bằng cách cung cấp API Keys và sử dụng URL webhook của Adapty trong Stripe. Để tự động hóa việc cấu hình webhook, hãy cài đặt ứng dụng Adapty trong Stripe:

0. Xác định xem bạn đang kết nối Stripe ở chế độ test hay live. Nếu ban đầu bạn thực hiện ở chế độ test, bạn sẽ cần lặp lại các bước dưới đây cho chế độ live.

1. Truy cập Stripe App Marketplace và cài đặt ứng dụng Adapty. Lưu ý rằng chế độ sandbox không hỗ trợ cài đặt ứng dụng. Bạn chỉ có thể thực hiện điều này ở chế độ production hoặc test.

2. Cấp cho ứng dụng các quyền cần thiết. Điều này cho phép Adapty truy cập dữ liệu và lịch sử gói đăng ký. Sau đó, nhấp vào Continue to app settings để tiếp tục.

Ở cuối pop-up quyền, bạn có thể chọn cài đặt ứng dụng ở chế độ live hay test.

3. Trong pop-up, tạo một restricted key mới. Bạn sẽ cần xác minh danh tính bằng email, Touch ID, hoặc security key. Sau khi tạo key, bạn sẽ không thể xem lại được nữa, vì vậy hãy lưu trữ an toàn trong trình quản lý mật khẩu hoặc secret store.

4. Sao chép key đã tạo từ pop-up và truy cập App Settings → Stripe của Adapty. Dán key vào phần Stripe App Restricted API Key tùy theo chế độ của bạn. Lưu ý rằng bạn phải tạo các key khác nhau cho chế độ test và live.

Xong rồi! Tiếp theo, hãy tạo sản phẩm trên Stripe và thêm chúng vào Adapty.

Quy trình cài đặt đã lỗi thời

1. Truy cập Developers → API Keys trong Stripe:

2. Nhấp vào nút Reveal live (test) key bên cạnh tiêu đề Secret key, sao chép nó và truy cập App Settings → Stripe của Adapty. Dán key vào đây:

3. Tiếp theo, sao chép Webhook URL từ cuối trang tương tự trong Adapty. Truy cập Developers → Webhooks trong Stripe và nhấp vào nút Add endpoint:

4. Dán webhook URL từ Adapty vào trường Endpoint URL. Sau đó chọn Latest API version trong trường Version của webhook. Tiếp theo chọn các sự kiện sau:

• charge.refunded
  • checkout.session.completed
  • customer.subscription.created
  • customer.subscription.deleted
  • customer.subscription.paused
  • customer.subscription.resumed
  • customer.subscription.updated
  • invoice.created
  • invoice.updated
  • payment_intent.succeeded

5. Nhấn “Add endpoint” rồi nhấn “Reveal” bên dưới “Signing secret”. Đây là key dùng để giải mã dữ liệu webhook phía Adapty, hãy sao chép nó sau khi hiển thị:

6. Cuối cùng, dán key này vào App Settings → Stripe của Adapty tại mục “Stripe Webhook Secret”:

2. Tạo sản phẩm trên Stripe

Truy cập Product catalog của Stripe và tạo các sản phẩm bạn muốn bán cùng với các gói giá của chúng. Lưu ý rằng Stripe cho phép bạn có nhiều gói giá cho mỗi sản phẩm, rất hữu ích để tùy chỉnh ưu đãi mà không cần tạo thêm sản phẩm mới.

3. Thêm sản phẩm Stripe vào Adapty

Chúng tôi xử lý Stripe tương tự như App Store và Google Play: đó chỉ là một cửa hàng khác nơi bạn bán sản phẩm kỹ thuật số. Vì vậy nó được cấu hình tương tự: chỉ cần thêm các sản phẩm Stripe (cụ thể là product_id và price_id của chúng) vào phần Products của Adapty:

Product ID trong Stripe trông giống như prod_... và price ID trông giống như price_.... Chúng khá dễ tìm cho mỗi sản phẩm trong Product Catalog của Stripe, khi bạn mở bất kỳ sản phẩm nào:

Sau khi bạn đã thêm tất cả các sản phẩm cần thiết, bước tiếp theo là cho Stripe biết người dùng nào đang thực hiện giao dịch mua, để Adapty có thể nhận diện được!

4. Bổ sung thông tin ID người dùng cho các giao dịch mua trên web

Adapty dựa vào webhook từ Stripe để cấp và cập nhật mức độ truy cập cho người dùng như là nguồn thông tin duy nhất. Tuy nhiên, bạn cần cung cấp thêm thông tin từ phía mình khi làm việc với Stripe để tích hợp này hoạt động đúng cách.

Để mức độ truy cập nhất quán trên các nền tảng (web hoặc mobile), bạn cần đảm bảo có một user ID duy nhất mà Adapty có thể nhận diện từ các webhook. Đây có thể là email, số điện thoại hoặc bất kỳ ID nào khác từ hệ thống xác thực bạn đang sử dụng. Adapty gọi giá trị này là customer_user_id.

Adapty đọc ID người dùng từ một nguồn duy nhất — nguồn được chọn trong Profile creation behavior tại App Settings → Stripe. Đây không phải là chuỗi dự phòng: nếu nguồn được chọn không có giá trị cho một giao dịch cụ thể, giao dịch mua đó sẽ ở trạng thái ẩn danh ngay cả khi ID có mặt ở nơi khác trong dữ liệu Stripe. Xem Profile creation behavior để biết tất cả các nguồn có sẵn.

Hãy chọn tùy chọn phù hợp với cách bạn tạo giao dịch mua trong Stripe.

Phiên thanh toán và gói đăng ký được tạo qua Stripe API

Giữ nguyên Profile creation behavior là Use customer_user_id from metadata (default). Sau đó, tìm đến phần code xử lý khởi tạo thanh toán qua Stripe — và thêm user ID này vào đối tượng metadata của Stripe Subscription (sub_...) hoặc Checkout Session (ses_...) dưới dạng customer_user_id như sau:

{'customer_user_id': "YOUR_USER_ID"}

Chỉ cần thêm một dòng đơn giản này là tất cả những gì bạn cần làm trong code. Sau đó, Adapty sẽ phân tích tất cả các webhook nhận được từ Stripe, trích xuất metadata này và liên kết chính xác các gói đăng ký với khách hàng của bạn.

Liên kết thanh toán (không cần code)

Nếu bạn bán hàng qua Stripe Payment Links và không có backend để thiết lập metadata, hãy truyền user ID vào tham số query client_reference_id của liên kết:

https://buy.stripe.com/your_link?client_reference_id=YOUR_USER_ID

Stripe lưu giá trị này trong Checkout Session và chuyển nó đến Adapty qua sự kiện checkout.session.completed. Cách này hoạt động cho cả gói đăng ký lẫn sản phẩm mua một lần.

5. Cấp quyền truy cập cho người dùng trên di động

Để đảm bảo người dùng di động đến từ web có thể truy cập các tính năng trả phí, chỉ cần gọi Adapty.activate() hoặc Adapty.identify() với cùng customer_user_id bạn đã cung cấp ở bước trước (xem Xác định người dùng iOS, Android, React Native, Flutter, và Unity để biết thêm).

6. Kiểm tra tích hợp của bạn

Hãy đảm bảo bạn đã hoàn thành các bước trên cho cả Sandbox và Production. Các giao dịch bạn thực hiện từ chế độ Test của Stripe sẽ được coi là Sandbox trong Adapty.

Hành vi tạo hồ sơ người dùng

Adapty phải liên kết một giao dịch mua với hồ sơ người dùng để nó khả dụng trên di động — vì vậy mặc định nó tạo hồ sơ người dùng khi nhận webhook từ Stripe. Bạn có thể chọn dùng gì làm customer user ID trong Adapty:

1. Mặc định và được khuyến nghị: Sử dụng customer_user_id từ metadata — customer_user_id bạn đã cung cấp trong metadata ở bước 4 ở trên
2. Sử dụng email từ đối tượng Customer của Stripe (xem tài liệu Stripe)
3. Sử dụng client_reference_id từ đối tượng Session của Stripe (xem tài liệu Stripe) — tùy chọn dùng với Payment Links

Bạn có thể cấu hình ID nào bạn muốn sử dụng trong App Settings → Stripe. Adapty chỉ sử dụng nguồn bạn chọn ở đây cho mọi giao dịch Stripe trong ứng dụng — không tự động chuyển sang các nguồn khác.

Bạn cũng có tùy chọn thứ tư là không tạo hồ sơ người dùng nào cả, nhưng điều này không được khuyến nghị do các giới hạn Analytics đã nêu ở trên.

Giới hạn hiện tại

Nâng cấp, hạ cấp và phân bổ phí

Các thay đổi gói đăng ký như nâng cấp hoặc hạ cấp có thể dẫn đến các khoản phí theo tỷ lệ. Adapty sẽ không tính các khoản phí này vào tính toán doanh thu. Tốt nhất là vô hiệu hóa các tùy chọn này theo cách thủ công qua Stripe dashboard. Bạn cũng có thể vô hiệu hóa chúng bằng cách đặt giá trị thuộc tính proration_behaviour thành none qua Stripe API.

Hủy gói đăng ký

Stripe có hai tùy chọn hủy gói đăng ký:

1. Hủy ngay lập tức: Gói đăng ký hủy ngay lập tức có hoặc không có tùy chọn phân bổ phí
2. Hủy vào cuối kỳ: Gói đăng ký hủy vào cuối kỳ thanh toán hiện tại (tương tự như gói đăng ký trong ứng dụng trên các cửa hàng ứng dụng).

Adapty hỗ trợ cả hai tùy chọn, nhưng tính toán doanh thu khi hủy ngay lập tức sẽ bỏ qua tùy chọn phân bổ phí.

Vấn đề thanh toán và thời gian ân hạn

Khi khách hàng gặp vấn đề với thanh toán, Adapty sẽ tạo sự kiện billing issue và quyền truy cập sẽ bị thu hồi. Chúng tôi chưa hỗ trợ Grace Period của Stripe — điều này sẽ là một phần của các bản phát hành trong tương lai.

Hoàn tiền

Adapty chỉ theo dõi hoàn tiền toàn bộ. Hoàn tiền theo tỷ lệ hoặc một phần hiện không được hỗ trợ.

Tính duy nhất của Transaction ID

Adapty khớp hồ sơ người dùng và giao dịch bằng store_transaction_id và store_original_transaction_id. Những giá trị này phải là duy nhất trên các môi trường Test và Production.

Tại sao điều này quan trọng

Nếu cùng một transaction ID tồn tại trong cả hai môi trường, Adapty xử lý chúng như một giao dịch, gây ra:

• Giao dịch mua Production kế thừa mức độ truy cập và product ID từ Test
• Product ID và môi trường sai trong phản hồi API
• Liên kết hồ sơ người dùng và sự kiện gói đăng ký bị gián đoạn

Cách đảm bảo tính duy nhất

Invoice ID của Stripe có thể trùng lặp giữa môi trường Test và Live. Để ngăn xung đột giữa các môi trường, hãy chọn một trong các cách sau

Tùy chọn 1: Đánh số theo tài khoản với tiền tố môi trường

Cấu hình tiền tố riêng cho mỗi môi trường:

1. Trong Stripe Dashboard, chuyển sang chế độ Test.
2. Truy cập Settings → Billing → Invoices.
3. Đặt Invoice numbering thành Sequentially across your account.
4. Đặt Invoice prefix thành TEST- (hoặc tiền tố khác dành riêng cho môi trường test).
5. Chuyển sang chế độ Live và lặp lại các bước 2-4, sử dụng LIVE- (hoặc tiền tố khác dành riêng cho môi trường live) làm tiền tố

Tùy chọn 2: Đánh số theo khách hàng

Đặt Invoice numbering trong Stripe settings -> Billing -> Invoices tab thành Sequentially for each customer (customer-level).

Ngay cả với cấu hình trên, nếu bạn xóa một invoice, Stripe có thể tái sử dụng ID đó cho các invoice mới của cùng khách hàng. Tốt nhất là tránh xóa invoice khi có thể.

Sản phẩm mua một lần qua Stripe Checkout hoặc Payment Links

Adapty ghi lại các sản phẩm mua một lần (không phải gói đăng ký) được thực hiện qua Stripe Checkout (mode=payment) hoặc Payment Links từ sự kiện checkout.session.completed. Hãy đảm bảo sự kiện này đã được bật trên webhook endpoint của bạn trong Stripe — các endpoint được tạo trước khi Adapty bổ sung hỗ trợ Payment Links sẽ không bao gồm sự kiện này. Xem bước 4 để biết cách kiểm tra.

Adapty lấy sản phẩm từ mục hàng đầu tiên trong session, vì vậy một session bán nhiều sản phẩm sẽ chỉ ghi lại sản phẩm đầu tiên.

Hoàn tiền cho các giao dịch mua này chưa được áp dụng: Stripe gửi sự kiện charge.refunded, nhưng Adapty không thu hồi quyền truy cập đối với sản phẩm mua một lần được mua qua Checkout hoặc Payment Link. Hoàn tiền cho gói đăng ký và sản phẩm mua một lần được thanh toán qua hóa đơn Stripe vẫn hoạt động bình thường.

Khai thác tối đa dữ liệu Stripe của bạn

Sau khi tích hợp với Stripe, Adapty sẵn sàng cung cấp thông tin chi tiết ngay lập tức. Để tận dụng tối đa dữ liệu Stripe của bạn, bạn có thể thiết lập thêm các tích hợp Adapty để chuyển tiếp các sự kiện Stripe — đưa toàn bộ phân tích gói đăng ký vào một Adapty Dashboard duy nhất.

{
  'customer_user_id': "YOUR_USER_ID",
  'variation_id': "YOUR_VARIATION_ID"
}

Các tích hợp bạn có thể sử dụng để chuyển tiếp và phân tích các sự kiện Stripe:

• Amplitude
• Webhook
• Firebase
• Mixpanel
• Posthog

Các sự kiện Stripe được hỗ trợ

Adapty hỗ trợ các sự kiện Stripe sau:

• charge.refunded
• checkout.session.completed
• customer.subscription.created
• customer.subscription.deleted
• customer.subscription.paused
• customer.subscription.resumed
• customer.subscription.updated
• invoice.created
• invoice.updated
• payment_intent.succeeded