Skip to main content
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 sang on_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ả.
Trang chi tiết giao dịch của một payment bị lỗi, hiển thị mã lỗi và thông báo lỗi, Activity Log và nút Retry Payment Manually

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ề: trong reason 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.
Thử lại một hard decline trên cùng thẻ không thể thành công và các lần bị từ chối lặp lại sẽ làm giảm tỷ lệ authorization của bạn. Khi lý do là MANUAL_RETRY_HARD_DECLINE, hãy yêu cầu khách hàng cập nhật payment method thay thế. Subscription Dunning thực hiện việc này tự động.

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.
Lần sửa đổi cuối 25 tháng 9, 2026