LRC-11956 — Tích hợp thanh toán Atone

1 Tổng quan giải pháp

Atone là cổng thanh toán trả-sau (BNPL) của Nhật. Loverec cần tích hợp Atone song song với các cổng thẻ tín dụng hiện tại, áp dụng cho mua coin/retail video và gói sub gia hạn (VIP, FullHD, Members Plan).

Phạm vi triển khai

• Mua 1 lần: Coin, Point, Retail Video — Atone tính phí một lần ngay sau khi xét duyệt thành công
• Sub gia hạn hàng tháng: VIP, FullHD, Members Plan — Atone xử lý gia hạn tự động dựa trên token xác thực đã lưu
• Hai loại dịch vụ Atone:
  • 翌月後払い (Service Type 01): Thanh toán sau vào tháng kế tiếp — chuyển khoản / ATM / conbini
  • つど後払い (Service Type 04 — Atone Lite): Thanh toán sau theo từng lần
• Switch giữa Atone và thẻ tín dụng: User được tự do đổi qua lại bất cứ lúc nào, kể cả khi đang có sub đang chạy

2 Hiện trạng hệ thống Loverec

Trước khi bổ sung Atone, hệ thống hiện đang vận hành các flow thanh toán sau:

2.1 Các phương thức thanh toán đang có

Loverec hiện đang hỗ trợ nhiều cổng thanh toán thẻ tín dụng, mỗi cổng phục vụ một số dòng thẻ:

• Cổng A: VISA, Mastercard
• Cổng B: JCB, AMEX
• Mỗi cổng có cơ chế riêng để lấy token xác thực thẻ (3DS) khi user thêm thẻ

Tất cả các thẻ user đã thêm được lưu lại để dùng cho các giao dịch sau. User có thể có nhiều thẻ, nhưng chỉ có 1 thẻ được set làm mặc định tại 1 thời điểm.

2.2 Cách thẻ mặc định hoạt động

Quy tắc hiện tại trên hệ thống:

• Mỗi giao dịch người dùng thực hiện, phương thức đang được chọn sẽ trở thành phương thức mặc định cho tất cả giao dịch tự động sau đó (kể cả gia hạn sub).
• Không phân biệt sản phẩm: mua coin lần này bằng thẻ B → kỳ gia hạn VIP sub kế tiếp cũng tự động dùng thẻ B (dù trước đó VIP sub đang gia hạn bằng thẻ A).
• User cũng có thể vào trang "Phương thức thanh toán" trong Account để chủ động đổi thẻ mặc định.

2.3 Flow mua sub & gia hạn hiện tại (với thẻ tín dụng)

2.4 Trang quản lý thẻ & switch payment method

User có trang Account → Phương thức thanh toán để:

• Xem danh sách thẻ đã đăng ký
• Đánh dấu thẻ nào là mặc định (radio button)
• Thêm thẻ mới
• Xóa thẻ

Khi đổi thẻ mặc định, hệ thống hiển thị confirm popup: 支払いカードを変更しますか。 ("Đổi thẻ thanh toán?") trước khi áp dụng.

2.5 Cách hệ thống xử lý lỗi thanh toán hiện tại

Các lỗi thanh toán thẻ được phân nhóm:

• Lỗi thẻ: thẻ hết hạn, không đủ hạn mức, thẻ bị block → noti user đổi thẻ
• Lỗi hệ thống: timeout, cổng thanh toán không phản hồi → retry tự động
• Lỗi tạm thời: nhóm các lỗi có thể retry sau (network, gateway busy)

Mỗi nhóm lỗi có thông điệp riêng cho user, có/không retry tự động, có/không gửi mail/noti.

3 Atone là gì? Khác thẻ tín dụng thế nào?

Phần này giải thích đặc thù của Atone để hiểu vì sao flow phải khác card.

3.1 Atone là cổng "trả sau"

• User không cần thẻ tín dụng để thanh toán bằng Atone. Atone tạm ứng tiền cho merchant ngay khi xét duyệt OK; user trả tiền cho Atone qua chuyển khoản/ATM/conbini sau (hằng tháng hoặc theo từng lần).
• Atone định danh user bằng số điện thoại + OTP, không phải số thẻ.
• Một user chỉ cần xác thực 1 lần (nhập SĐT + OTP), nhận về token xác thực, dùng cho tất cả các giao dịch sau.

3.2 Khác biệt chính so với thẻ tín dụng trên Loverec

3.3 Hai loại dịch vụ Atone

User chọn loại service type lần đầu khi đăng ký Atone. Loại đã chọn sẽ được lưu và dùng cho các giao dịch sau, trừ khi user chủ động đổi.

3.4 Quy tắc đặc thù gia hạn sub của Atone

3.5 Module Atone — 2 chế độ

Atone cung cấp 1 module JavaScript chạy trên trang Loverec, có 2 chế độ:

• Chế độ thanh toán (modal_mode=01): dùng cho mua hàng / sub lần đầu. User xác thực + đồng ý charge ngay.
• Chế độ xác thực thành viên (modal_mode=02): dùng khi user muốn đăng ký Atone (hoặc đăng ký lại) mà không phát sinh giao dịch. Chỉ cấp token xác thực.

Khi user switch payment method từ thẻ sang Atone (mà sub đang chạy), Loverec phải dùng chế độ xác thực (02) vì giao dịch sub lần đầu đã xảy ra bằng thẻ, không cần charge mới.

4 User stories

Mô tả mong muốn của từng vai khi dùng tính năng Atone.

5 Flow xử lý mới (chi tiết)

3 flow chính: (a) mua sub Atone lần đầu, (b) gia hạn sub tự động, (c) switch payment method.

5.1 — Flow A: Mua sub bằng Atone lần đầu

5.2 — Flow B: Gia hạn sub Atone tự động (không có user)

5.3 — Flow C: Switch payment method (thẻ ↔ Atone) khi đang có sub

5.4 — Flow D: Reconciliation khi mismatch callback vs webhook

6 Thay đổi giao diện

4 màn hình thay đổi + 2 popup mới.

6.1 — Trang chọn gói & phương thức thanh toán (Charge / Rank / Subscription)

Hiện trạng: Hiển thị danh sách các thẻ tín dụng đã đăng ký + nút "Thêm thẻ mới".

Thay đổi:

• Thêm option "Atone" trong danh sách phương thức thanh toán
• Nếu user chưa có Atone token, chọn Atone sẽ mở dropdown/modal chọn service type (翌月後払い / つど後払い)
• Nếu đã có Atone token, hiển thị icon Atone + label dịch vụ (không có 4 số cuối như thẻ)

6.2 — Popup "Default vs One-time" (mới)

Hiển thị khi nào: Khi user mua sub bằng Atone, mà user đã có cổng thanh toán mặc định khác.

6.3 — Trang quản lý phương thức thanh toán (Account)

Hiện trạng: Danh sách thẻ + nút "Thêm thẻ mới" (chỉ dẫn đến trang thêm thẻ tín dụng).

Thay đổi:

• Thêm option "Thêm Atone" trong menu thêm phương thức thanh toán
• Khi click "Thêm Atone" → mở Atone Authentication Module (modal_mode=02), không qua trang nhập thẻ thông thường
• Atone hiển thị trong danh sách với format khác thẻ: chỉ icon + label dịch vụ (không có "**** 1234")

6.4 — Confirm popup khi đổi sang Atone

Hiện trạng: Confirm 支払いカードを変更しますか。 ("Đổi thẻ thanh toán?") khi đổi giữa 2 thẻ.

Thay đổi: Nội dung popup khi đổi sang Atone (hoặc đổi từ Atone) cần khác hơn:

• Khi user đổi sang Atone lần đầu, thêm dòng giải thích về service type sẽ dùng
• Khi user đổi từ Atone sang thẻ, không cần giải thích thêm

6.5 — Popup retry payment (khi gia hạn fail)

Hiện trạng: Khi gia hạn fail, popup hiển thị danh sách thẻ để user retry.

Thay đổi: Trong danh sách retry, hiển thị thêm Atone (nếu user đã đăng ký) với icon + label. Khi user chọn Atone để retry, gọi Atone gia hạn lại.

6.6 — Mail / Notification template (mới cho Atone)

Cần thiết kế template JP cho các sự kiện:

• Atone thanh toán thành công (one-time hoặc sub lần đầu)
• Atone gia hạn sub thành công
• Atone gia hạn sub fail (với lý do tương ứng)
• Atone xét duyệt không đạt (Screening NG)
• Đổi phương thức thanh toán sang Atone thành công
• Đổi phương thức thanh toán từ Atone sang thẻ thành công
• Webhook reconciliation phát hiện inconsistency (chỉ gửi admin)

7 Việc cần làm — Frontend

Việc FE cần làm xoay quanh UI flow mới + tích hợp module Atone + xử lý popup/mail UX.

8 Việc cần làm — Backend

BE đảm nhận: lưu trữ data, gọi API Atone (không gọi từ FE vì CORS), webhook handler, cron gia hạn, reconciliation, mail/noti.

9 Việc cần làm — Admin CMS

Admin cần công cụ để xem và xử lý giao dịch Atone, đặc biệt là các case fail/screening NG cần can thiệp thủ công.

10 Xử lý mã lỗi Atone & thông báo cho user

Phân loại mã lỗi để định behavior + message phù hợp. KH yêu cầu: Atone không được gom vào nhóm "lỗi thẻ" vì Atone không dùng thẻ.

10.1 — Phân nhóm mã lỗi

10.2 — Mail / Notification mapping

11 Test scenarios

Test case chính theo hành vi user (do Lê Thị Huyền đề xuất + bổ sung).

11.1 — Test case core (4 TC do Lê Thị Huyền)

11.2 — Test case bổ sung

• TC5: Atone xét duyệt NG (Screening NG) lần đầu mua → hiển thị thông báo, gợi ý đổi phương thức
• TC6: Gia hạn Atone fail với lỗi tạm thời (timeout) → hệ thống retry 3 lần, lần 3 fail → noti user
• TC7: Callback Atone success nhưng webhook báo fail → reconciliation → rollback sub, noti user
• TC8: User mua sub Atone với option "Default" → tất cả sub khác sang dùng Atone từ kỳ kế
• TC9: User mua sub Atone với option "One-time" → sub khác vẫn dùng thẻ cũ
• TC10: User chọn service type 01 (翌月後払い), giao dịch sau tự động dùng cùng service type
• TC11: Regression — đảm bảo 3 cổng thẻ hiện tại không bị break
• TC12: Mua coin one-time bằng Atone, KHÔNG được đánh dấu "định kỳ" (transaction_options không gửi)

11.3 — Môi trường test

• Atone sandbox dev/staging đã có (xem §13 Tham chiếu)
• Atone production: chưa cấp (block release) — phải request gấp
• BE phải support env flag để giả lập các case fail (vì Atone sandbox không reproduce được error scenarios)

12 Vấn đề còn mở

Các điểm chưa rõ, cần Q&A với Atone hoặc thống nhất với KH trước khi triển khai.

13 Estimate & lộ trình

13.1 — Estimate tổng (đã chốt với KH — Comment #78, #87)

13.2 — Lộ trình đề xuất

1. Week 1 — Unblock + Align
   • Request Atone prod environment
   • Họp với KH + Atone để chốt TC4 flow
   • Q&A 3 mã lỗi pending
   • Confirm diagram flow với KH
2. Week 2 — Core CR
   • FE: phân biệt 2 chế độ module, đánh dấu định kỳ, popup default/one-time
   • BE: lưu first_transaction_id, endpoint nhận auth callback, đánh dấu định kỳ
3. Week 3 — Common + Admin
   • FE: trang thêm Atone, UI label, popup retry với Atone
   • BE: cron gia hạn Atone, retry mechanism, webhook reconciliation
   • BE: mail/noti template, admin CMS
4. Week 4 — Test + UAT
   • QA TC1-TC12 trên staging
   • Regression test các cổng thẻ hiện tại
   • KH UAT review
5. Week 5 — Production prep
   • Atone prod env validation
   • Webhook URL prod, checksum keys prod
   • Rollback plan
   • Soft launch