Thử lại thủ công sẽ thử lại khoản thanh toán gia hạn subscription bị lỗi ngay khi bạn yêu cầu, từ trang chi tiết thanh toán hoặc thông qua API. Tính năng này tính phí vào payment method đã 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 và Payment Retries sẽ thử tính phí lại 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: khách hàng đã xác nhận họ nạp thêm tiền vào tài khoản, hoặc đội ngũ hỗ trợ của bạn đang trao đổi với họ. Thử lại thủ công cho phép bạn 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: Thử lại thủ công áp dụng cho invoice gia hạn subscription khi subscription đang ở trạng thái
on_hold. Khoản thanh toán đầu tiên, khoản thanh toán một lần, phí thay đổi plan và phí theo yêu cầu không đủ điều kiện. - Không cần khách hàng thực hiện thao tác: Khoản phí được gửi đến payment method đã 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 ngay cả khi Payment Retries bị tắt.
- Thử lại invoice, không phải payment: Payment bị lỗi chỉ là điểm bắt đầu. Dodo Payments tìm invoice gia hạn đang mở phía sau payment đó và thu khoản công nợ này, vì vậy việc bạn thử lại payment bị lỗi nào trên invoice không quan trọng.
Thử lại từ Dashboard
1
Open the failed payment
Đi tới Transactions → Payments và nhấp vào payment 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 payment đủ điều kiện.
3
Check the result
Một payment mới được tạo cho lần thử và xuất hiện trong Activity Log. Nếu khoản phí thành công, subscription trở lại trạng thái
active và ngày thanh toán tiếp theo được dời như bình thường. Nếu payment processor chưa hoàn tất việc quyết toán khoản phí, payment sẽ hiển thị là đang được xử lý cho đến khi webhook payment.succeeded hoặc payment.failed báo kết quả.
Retry Payment Manually on the transaction details page of a failed renewal
Điều kiện đủ tư cách
Một lần thử lại thủ công chỉ được gửi khi tất cả các bước kiểm tra dưới đâ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.
Thử lại thủ công có một điểm hạn chế hơn so với các lần thử lại tự động: subscription phải ở trạng thái
on_hold. Các lần thử lại tự động vẫn tiếp tục chạy đối với những trạng thái không phải active khác; xem Subscription Status Transitions.Giới hạn thử lại
Mỗi invoice 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 một lần thử lại bị từ chối vì lý do này, API trả về
MANUAL_RETRY_LIMIT_REACHED (HTTP 429). Nội dung lỗi chỉ chứa code và message. Để biết khi nào có thể thực hiện lần thử lại tiếp theo, 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ử đã được sử dụng.
Các lần thử lại tự động không được tính vào giới hạn này và các lần thử lại 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
Thử lại qua API
Trước tiên hãy kiểm tra điều kiện đủ tư cách, sau đó gửi yêu cầu thử lại. Cả hai endpoint đều nhận ID của payment bị lỗi.Kiểm tra payment có thể được thử lại hay không
GET /payments/{payment_id}/retry không bao giờ báo lỗi đối với payment không đủ điều kiện. Thay vào đó, endpoint trả về can_retry: false cùng với mã reason, để dashboard hoặc công cụ hỗ trợ của bạn có thể hiển thị cùng trạng thái như dashboard Dodo Payments. Endpoint này yêu cầu vai trò Viewer.
Response
Gửi lần thử lại thủ công
POST /payments/{payment_id}/retry tạo payment mới và tính phí vào payment method đã lưu. Endpoint này yêu cầu vai trò Editor.
Response
Phản hồi lỗi
Mọi code đều được mô tả trong tài liệu tham khảo Error Codes.
Webhook
Thử lại thủ công tạo một payment 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, chính xác như đối với lần thử lại tự động. Hãy lưu 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 payment.
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 khách hàng để cập nhật payment method sau một hard decline.
Handle Payment Failures
Đọc decline code và quyết định khi nào việc thử lại đáng thực hiện.
Error Codes
Mọi code
MANUAL_RETRY_*, trigger và thông báo tương ứng.