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.
Loại từ chốiÝ nghĩaLàm thế nàoVí dụ
Từ chối mềmTạm thời hoặc có thể điều chỉnh — thẻ có thể thành công trong một lần thử sau hoặc khi khách hàng sửa lỗi việc nhập thông tin.An toàn để thử lại (sau một khoảng thời gian chờ, hoặc khi khách hàng sửa thông tin).INSUFFICIENT_FUNDS, GENERIC_DECLINE, CARD_VELOCITY_EXCEEDED, PROCESSING_ERROR, NETWORK_ERROR, NETWORK_TIMEOUT, TRY_AGAIN_LATER
Từ chối cứngKết thúc — thử lại cùng một thẻ sẽ không thay đổi được kết quả.Không thử lại cùng một thẻ. Hỏi khách hàng sử dụng phương thức thanh toán khác hoặc liên hệ với ngân hàng của họ.STOLEN_CARD, LOST_CARD, PICKUP_CARD, DO_NOT_HONOR, FRAUDULENT, INVALID_ACCOUNT
Đố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.
Mã Thất BạiLoạiLỗi Người DùngMô TảHành Động Đề Xuất
AUTHENTICATION_FAILURESoftCóXác thực thất bại trong suốt giao dịchYêu cầu khách hàng thử lại và hoàn tất xác thực 3DS, hoặc sử dụng thẻ khác
AUTHENTICATION_REQUIREDSoftCóCần xác thực bổ sung để hoàn tất giao dịchYêu cầu khách hàng hoàn tất xác thực 3DS. Đối với các lần gia hạn đăng ký, yêu cầu khách hàng quay lại và xác thực
AUTHENTICATION_TIMEOUTSoftCóQuá trình xác thực đã hết thời gianYêu cầu khách hàng thử lại và hoàn tất xác thực kịp thời
CARD_DECLINEDSoftKhôngThẻ bị ngân hàng phát hành từ chối mà không có lý do cụ thể (từ chối tổng quát)Yêu cầu khách hàng thử lại, liên hệ với ngân hàng hoặc sử dụng thẻ khác
CARD_NOT_ACTIVATEDSoftCóThẻ chưa được chủ thẻ kích hoạtYêu cầu khách hàng kích hoạt thẻ với ngân hàng của họ, sau đó thử lại
CARD_VELOCITY_EXCEEDEDSoftCóQuá nhiều giao dịch được thử trong thời gian ngắnYêu cầu khách hàng chờ và thử lại sau, hoặc liên hệ với ngân hàng về giới hạn
CUSTOMER_CANCELLEDSoftCóKhách hàng đã hủy giao dịchĐể khách hàng khởi động lại khi sẵn sàng
DO_NOT_HONORHardKhôngNgân hàng phát hành từ chối giao dịch một cách rõ ràng (mã ISO 8583 05 — không chấp nhận); mạng đối xử coi đây như kết thúcYêu cầu khách hàng liên hệ với ngân hàng của họ; không thử lại trên cùng thẻ
EXPIRED_CARDHardCóThẻ đã hết hạnYêu cầu khách hàng sử dụng một thẻ có ngày hết hạn hợp lệ
FRAUDULENTHardCóGiao dịch bị gắn cờ có khả năng gian lậnHiển thị cho khách hàng thông báo từ chối chung — không tiết lộ lý do. Yêu cầu họ sử dụng thẻ khác
GENERIC_DECLINESoftKhôngGiao dịch bị từ chối vì lý do không xác địnhYêu cầu khách hàng liên hệ với ngân hàng của họ hoặc thử thẻ khác
INCORRECT_CVCSoftCóMã CVC được cung cấp saiYêu cầu khách hàng nhập lại CVC đúng
INCORRECT_NUMBERSoftCóSố thẻ được nhập saiYêu cầu khách hàng nhập lại số thẻ đúng
INSUFFICIENT_FUNDSSoftCóTài khoản không đủ tiền để thực hiện giao dịchYêu cầu khách hàng sử dụng phương thức thanh toán khác hoặc thử lại khi tiền có sẵn
INVALID_ACCOUNTHardCóChi tiết tài khoản cung cấp không hợp lệYêu cầu khách hàng liên hệ với ngân hàng của họ hoặc sử dụng thẻ khác
INVALID_AMOUNTSoftCóSố tiền giao dịch không hợp lệXác thực số tiền và giới hạn mua với khách hàng
INVALID_CARD_NUMBERSoftCóĐịnh dạng số thẻ không hợp lệYêu cầu khách hàng nhập lại số thẻ hợp lệ
INVALID_CARD_OWNERSoftCóThông tin chủ thẻ không hợp lệYêu cầu khách hàng sửa lại tên chủ thẻ
INVALID_CVCSoftCóĐịnh dạng CVC không hợp lệYêu cầu khách hàng nhập lại CVC hợp lệ
INVALID_EXPIRY_YEARSoftCóNăm hết hạn thẻ không hợp lệYêu cầu khách hàng nhập ngày hết hạn hợp lệ
INVALID_PINSoftCóMã PIN cung cấp không đúngYêu cầu khách hàng nhập lại mã PIN đúng
INVALID_REQUESTSoftCóYêu cầu giao dịch chứa dữ liệu không hợp lệKiểm tra các trường yêu cầu thanh toán và gửi lại với dữ liệu hợp lệ
INVALID_UPI_IDSoftCóID UPI cung cấp không hợp lệYêu cầu khách hàng nhập ID UPI hợp lệ
LIMIT_EXCEEDEDSoftCóGiao dịch vượt quá giới hạn thẻ hoặc tài khoảnYêu cầu khách hàng liên hệ với ngân hàng về giới hạn, hoặc sử dụng phương thức khác
LIVE_MODE_TEST_CARDHardCóMột thẻ thử nghiệm được sử dụng ở chế độ trực tiếpSử dụng một thẻ thực — thử lại thẻ thử nghiệm luôn thất bại ở chế độ trực tiếp
LOST_CARDHardCóThẻ bị báo mấtHiển thị cho khách hàng thông báo từ chối chung — không tiết lộ lý do. Yêu cầu họ sử dụng thẻ khác
MANDATE_INVALIDSoftCóManda thanh toán không hợp lệYêu cầu khách hàng thiết lập lại sở thích thanh toán
MANDATE_REQUIREDSoftCóCần có sự ủy quyền cho giao dịch nàyThiết lập một manda và yêu cầu khách hàng xác nhận trước khi thu phí
MANDATE_REQUIRED_SYSTEMHardKhôngHệ thống yêu cầu một manda cho loại giao dịch nàyĐảm bảo luồng thiết lập manda đã hoàn tất trước khi thu phí
NETWORK_ERRORSoftKhôngĐã xảy ra lỗi mạng trong suốt giao dịchTạm thời — thử lại thanh toán sau một thời gian ngắn
NETWORK_TIMEOUTSoftKhôngYêu cầu mạng đã hết thời gianTạm thời — thử lại thanh toán sau một thời gian ngắn
ORDER_ALREADY_EXISTSSoftKhôngĐơn hàng đã tồn tại cho giao dịch này (tạo đơn hàng trùng lặp)Kiểm tra trạng thái của đơn hàng hiện có trước khi thử lại; liên hệ với hỗ trợ nếu nó tiếp tục
ORDER_CREATION_FAILEDSoftKhôngKhông tạo được đơn hàng cho giao dịchLỗi tạm thời/hệ thống — thử lại thanh toán; liên hệ với hỗ trợ nếu nó tiếp tục
PAYMENT_METHOD_PROVIDER_DECLINEDHardCóNhà cung cấp phương thức thanh toán từ chối giao dịchYêu cầu khách hàng liên hệ với nhà cung cấp của họ hoặc sử dụng phương thức thanh toán khác
PAYMENT_METHOD_UNSUPPORTEDHardCóPhương thức thanh toán không được hỗ trợ cho giao dịch nàyYêu cầu khách hàng sử dụng phương thức thanh toán được hỗ trợ
PICKUP_CARDHardCóThẻ bị báo mất hoặc bị đánh cắp và bị gắn cờ để thu hồiHiển thị cho khách hàng thông báo từ chối chung — không tiết lộ lý do. Yêu cầu họ sử dụng thẻ khác
PROCESSING_ERRORSoftKhôngLỗi xảy ra trong khi xử lý giao dịchTạm thời — thử lại thanh toán; nếu nó tiếp tục, yêu cầu khách hàng liên hệ với ngân hàng của họ
PROVIDER_UNSUPPORTEDHardKhôngNhà cung cấp thanh toán không hỗ trợ loại giao dịch nàyYêu cầu khách hàng sử dụng phương thức thanh toán khác
REENTER_TRANSACTIONSoftCóGiao dịch cần nhập lạiYêu cầu khách hàng thử lại thanh toán
REVOCATION_OF_AUTHORIZATIONHardCóỦy quyền cho giao dịch đã bị thu hồiYêu cầu khách hàng sử dụng phương thức thanh toán khác
STOLEN_CARDHardCóThẻ bị báo mấtHiển thị cho khách hàng thông báo từ chối chung — không tiết lộ lý do. Yêu cầu họ sử dụng thẻ khác
SUBSCRIPTION_NOT_ACTIVEHardKhôngĐăng ký không hoạt động, do đó không thể xử lý phí định kỳKích hoạt lại đăng ký (ví dụ: bằng cách cập nhật phương thức thanh toán) trước khi thử lại phí
TRANSACTION_NOT_ALLOWEDHardCóGiao dịch không được phép cho thẻ hoặc tài khoản nàyYêu cầu khách hàng liên hệ với ngân hàng của họ để cho phép loại giao dịch này, hoặc sử dụng thẻ khác
TRANSACTION_NOT_APPROVEDHardCóGiao dịch không được phê duyệtYêu cầu khách hàng liên hệ với ngân hàng của họ hoặc thử thẻ khác
TRY_AGAIN_LATERSoftKhôngGiao dịch nên được thử lại sauTạm thời — thử lại thanh toán sau
UNKNOWN_ERRORSoftKhôngĐã xảy ra lỗi không xác địnhThử lại thanh toán; nếu nó tiếp tục, liên hệ với hỗ trợ
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.

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

Đọc error_code từ payment.failed webhook hoặc đối tượng thanh toán, ánh xạ nó đến hành động đề xuất ở trên, và quyết định xem có nên thử lại hay không. Đối với gia hạn đăng ký, các từ chối mềm được thử lại tự động — xem Subscription Payment Retries. Đố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ẻ, hãy xem tham khảo Error Codes.

​
Liên quan

Handle Payment Failures

Hướng dẫn từ đầu đến cuối về phát hiện, hiển thị và thử lại các khoản thanh toán thất bại.

Error Codes

Mã lỗi API và logic kinh doanh cho các lỗi không phải là từ chối.

Subscription Payment Retries

Thử lại tự động sẽ khôi phục các từ chối mềm khi gia hạn đăng ký.

Subscription Dunning

Chuỗi email phục hồi các từ chối cứng bằng cách yêu cầu cập nhật phương thức thanh toán.

​
Hỗ trợ

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