Manual Retry thử lại khoản thanh toán gia hạn subscription bị lỗi khi bạn yêu cầu, từ trang chi tiết khoản thanh toán hoặc thông qua API. Tính năng này tính phí phương thức thanh toán đã lưu trên subscription và hoạt động độc lập với lịch Payment Retries tự động.
Thử lại thủ công là gì?
Khi khoản thanh toán gia hạn bị lỗi, subscription chuyển sangon_hold. Nếu bạn đã bật Payment Retries, tính năng này sẽ thử lại khoản phí theo lịch back-off. Đôi khi bạn biết khoản thanh toán sẽ thành công ngay lúc này: customer đã xác nhận họ đã nạp tiền vào tài khoản, hoặc đội ngũ hỗ trợ của bạn đang trao đổi với họ. Manual Retry gửi một lần thử ngay lập tức thay vì chờ hàng giờ hoặc hàng ngày cho lần thử theo lịch tiếp theo.
- Chỉ áp dụng cho khoản thanh toán gia hạn: Manual Retry áp dụng cho các hóa đơn gia hạn subscription trong khi subscription ở trạng thái
on_hold. Khoản thanh toán đầu tiên, khoản thanh toán một lần, khoản phí thay đổi plan và khoản phí theo yêu cầu không đủ điều kiện. - Không cần customer thực hiện thao tác: Khoản phí được tính vào phương thức thanh toán đã lưu trên subscription.
- Độc lập với các lần thử lại tự động: Một lần thử lại thủ công không sử dụng một lần thử trong lịch tự động, không thay đổi lần thử theo lịch tiếp theo và vẫn hoạt động khi Payment Retries bị tắt.
- Thử lại hóa đơn, không phải khoản thanh toán: Khoản thanh toán bị lỗi chỉ là điểm bắt đầu. Dodo Payments tìm hóa đơn gia hạn đang mở đứng sau đó và thu khoản nợ tương ứng, vì vậy không quan trọng bạn thử lại từ khoản thanh toán bị lỗi nào trên hóa đơn.
Thử lại từ Dashboard
Chỉ người dùng có vai trò Owner hoặc Editor mới có thể gửi một lần thử lại thủ công.1
Open the failed payment
Đi tới Transactions → Payments và nhấp vào khoản thanh toán gia hạn bị lỗi để mở trang Transaction details.
2
Click Retry Payment Manually
Nhấp vào Retry Payment Manually ở góc trên bên phải. Nút này chỉ khả dụng khi khoản thanh toán đủ điều kiện.
3
Check the result
Dodo Payments tạo một khoản thanh toán mới cho lần thử và khoản thanh toán này xuất hiện trong Activity Log. Nếu khoản phí thành công, subscription trở về trạng thái
active và ngày lập hóa đơn tiếp theo được chuyển sang một billing period sau lần thử lại thành công. Nếu payment processor chưa hoàn tất việc quyết toán khoản phí, khoản thanh toán sẽ hiển thị là đang xử lý cho đến khi webhook payment.succeeded hoặc payment.failed báo cáo kết quả.
Retry Payment Manually on the transaction details page of a failed renewal
Điều kiện đủ
Dodo Payments chỉ gửi một lần thử lại thủ công khi mọi điều kiện trong bảng này đều đạt. Cột Reason code là giá trị API trả về: trongreason trên GET /payments/{payment_id}/retry và dưới dạng lỗi code trên POST /payments/{payment_id}/retry.
Manual Retry hẹp hơn các lần thử tự động ở một điểm: yêu cầu subscription phải ở trạng thái
on_hold. Subscription past_due đang trong thời gian ân hạn sẽ không đạt điều kiện này. Các lần thử tự động vẫn tiếp tục chạy đối với những trạng thái không hoạt động khác. Xem Subscription Status Transitions.Giới hạn thử lại
Mỗi hóa đơn gia hạn cho phép 3 lần thử lại thủ công, với thời gian chờ giữa các lần:
Các giới hạn áp dụng cho cả test mode và live mode. Khi giới hạn từ chối một lần thử lại, API trả về
MANUAL_RETRY_LIMIT_REACHED (HTTP 429) và nội dung lỗi chỉ chứa code cùng message. Để biết khi nào lần thử lại tiếp theo mở, kiểm tra trạng thái thử lại và đọc retry_available_at. Giá trị này là null khi cả ba lần thử lại đã được sử dụng.
Các lần thử tự động không được tính vào giới hạn này và các lần thử thủ công không được tính vào 8 lần thử của lịch tự động.
Thử lại thủ công và tự động
Hai quy trình thử lại khác nhau ở những điểm sau:Thử lại thông qua API
Trước tiên hãy kiểm tra điều kiện, sau đó gửi lần thử lại. Cả hai endpoint đều nhận ID của một khoản thanh toán bị lỗi.Kiểm tra xem có thể thử lại khoản thanh toán hay không
GET /payments/{payment_id}/retry không trả về lỗi đối với khoản thanh toán không đủ điều kiện. Thay vào đó, nó trả về can_retry: false cùng mã reason, để dashboard hoặc công cụ hỗ trợ của riêng bạn có thể hiển thị cùng trạng thái với dashboard Dodo Payments. Endpoint này yêu cầu vai trò Viewer.
Response
Gửi một lần thử lại thủ công
POST /payments/{payment_id}/retry tạo một khoản thanh toán mới và tính phí phương thức thanh toán đã lưu. Endpoint này yêu cầu vai trò Editor. Các ví dụ SDK sử dụng lại client từ ví dụ trước.
Response
Phản hồi lỗi
Khi không được phép thử lại,POST trả về một trong các HTTP status sau:
Tài liệu tham khảo Error Codes mô tả mọi mã.
Webhooks
Manual Retry tạo một khoản thanh toán thông thường, vì vậy các webhook giống như đối với mọi lần thử gia hạn khác sẽ được kích hoạt:
Trên payment object trong các event này,
retry_attempt là 1 hoặc cao hơn và subscription_id được thiết lập, giống như đối với một lần thử tự động. Payment object không có trường đánh dấu một lần thử thủ công, vì vậy hãy giữ payment_id từ phản hồi thử lại nếu bạn cần phân biệt lần thử thủ công với lần thử theo lịch.
Payment Webhook Payloads
Schema payload đầy đủ cho các event thanh toán.
Liên quan
Subscription Payment Retries
Lịch back-off tự động chạy song song với các lần thử lại thủ công.
Subscription Dunning
Gửi email cho customer để cập nhật phương thức thanh toán sau một hard decline.
Handle Payment Failures
Đọc các mã từ chối và quyết định khi nào nên thử lại.
Error Codes
Mọi mã
MANUAL_RETRY_*, trigger và thông báo tương ứng.