Chuyển đến nội dung chính

​
Tổng Quan

Dodo Payments trả về lý do thất bại chi tiết mỗi khi một lần thanh toán không thành công. Những lý do này được tiêu chuẩn hóa trên các phương thức và nhà cung cấp thanh toán, giúp bạn triển khai xử lý nhất quán trong ứng dụng của mình. Khi một khoản thanh toán thất bại, payment.failed webhook và đối tượng thanh toán tiết lộ:
  • error_code — một lý do thất bại được tiêu chuẩn hóa từ bảng dưới đây.
  • error_message — một giải thích dễ hiểu cho người đọc.
  • retry_attempt — 0 cho lần thanh toán ban đầu, 1 hoặc cao hơn cho mỗi lần thử gia hạn đăng ký được lên lịch.
Hiểu những lý do thất bại này giúp bạn cung cấp phản hồi rõ ràng cho khách hàng, quyết định xem có nên thử lại hay không, và thu hồi nhiều doanh thu hơn.

Handle Payment Failures

Hướng dẫn nhà phát triển từng bước để đọc mã này từ webhooks và API, hiển thị cho khách hàng, và quyết định khi nào cần thử lại.

​
Từ chối mềm vs. Từ chối cứng

Mỗi mã thất bại thuộc một trong hai loại. Sự phân biệt này quyết định xem bạn nên thử lại phương thức thanh toán cũ hay yêu cầu khách hàng cung cấp phương thức mới. Đối với việc gia hạn đăng ký, Dodo Payments tự động áp dụng sự phân biệt này: các từ chối mềm được thử lại bởi Subscription Payment Retries, trong khi từ chối cứng kết thúc chuỗi thử lại ngay lập tức và nên được xử lý bằng Subscription Dunning.
Không bao giờ tiết lộ lý do thực sự cho STOLEN_CARD, LOST_CARD, PICKUP_CARD, or FRAUDULENT cho khách hàng. Hiển thị những điều này có thể cảnh báo một kẻ gian lận. Luôn luôn hiển thị cho khách hàng một thông báo từ chối chung chung (ví dụ, “Thẻ của bạn đã bị từ chối. Vui lòng liên hệ ngân hàng của bạn hoặc sử dụng thẻ khác.”) và chỉ ghi lại mã cụ thể nội bộ.

​
Lý do thất bại giao dịch

Bảng sau liệt kê tất cả mã thất bại, loại từ chối, liệu khách hàng có thể khắc phục, mô tả và hành động đề xuất.
Lỗi Người Dùng chỉ ra liệu khách hàng có thể giải quyết sự từ chối thanh toán hay không. Khi Yes, khách hàng có thể thực hiện hành động để khắc phục sự cố (ví dụ, nhập đúng thông tin thẻ). Khi No, sự từ chối là do vấn đề hệ thống hoặc hạn chế từ ngân hàng mà khách hàng không thể giải quyết trực tiếp.
A card can also be declined when the issuing bank’s own risk engine flags the cardholder as a high-risk customer — independent of the merchant or the transaction details. These declines typically surface as generic codes such as DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED, or FRAUDULENT. In these cases the bank does not share the specific reason, and neither Dodo Payments nor the merchant can override the decision. Ask the customer to contact their bank to resolve the flag, or use a different card or payment method.

​
Xử lý lỗi theo chương trình

Đọc error_code từ webhook payment.failed hoặc đối tượng thanh toán, ánh xạ tới hành động khuyến nghị ở trên, và quyết định có nên thử lại hay không. Đối với gia hạn đăng ký, các lỗi từ chối mềm được thử lại tự động — xem Khôi phục Thanh Toán Đăng Ký. Đối với lỗi cấp API và logic kinh doanh (như PAYMENT_NOT_SUCCEEDED hoặc REFUND_WINDOW_EXPIRED) không phải là từ chối thẻ, xem tham chiếu Mã lỗi.

​
Liên quan

Hướng dẫn từ đầu đến cuối để phát hiện, bề mặt, và thử lại các khoản thanh toán không thành công. Mã lỗi API và logic kinh doanh cho các lỗi không phải từ chối. Tự động thử lại để khôi phục từ chối mềm trên gia hạn đăng ký. Chuỗi email thúc đẩy cập nhật phương thức thanh toán để khôi phục từ chối cứng.

​
Hỗ trợ

Để được hỗ trợ thêm về lỗi giao dịch hoặc vấn đề tích hợp, vui lòng liên hệ với nhóm hỗ trợ của chúng tôi tại support@dodopayments.com.
Lần sửa đổi cuối 26 tháng 6, 2026