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— lý do thất bại được chuẩn hóa từ bảng bên dưới.error_message— phần giải thích dễ hiểu dành cho bạn, merchant. Khierror_codelà một trong các mã được chuẩn hóa bên dưới, đây là tiêu đề kèm hành động đề xuất thay vì văn bản thô từ payment processor.retry_attempt—0cho khoản charge ban đầu,1hoặc cao hơn cho mỗi lần thử lại gia hạn subscription theo lịch.
Nội dung dành cho Merchant và Customer
Mỗi mã thất bại được chuẩn hóa tương ứng với hai thông báo khác nhau, để đúng đối tượng nhận được mức độ chi tiết phù hợp:Customer Portal trả về nội dung dành cho customer trong
error_message, trong khi merchant API trả về nội dung dành cho merchant của cùng payment đó. error_code giống hệt nhau trong cả hai trường hợp.Handle Payment Failures
Hướng dẫn dành cho developer theo từng bước về cách đọc các mã này từ webhook và API, hiển thị chúng cho customer và quyết định thời điểm thử lại.
Từ chối mềm và 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 việc bạn nên thử lại cùng payment method hay yêu cầu customer sử dụng payment method mới.
Đối với các lần gia hạn subscription, Dodo Payments tự động áp dụng phân biệt này: các trường hợp từ chối mềm sẽ được thử lại bởi Subscription Payment Retries, trong khi các trường hợp từ chối cứng sẽ kết thúc chuỗi thử lại ngay lập tức và nên được xử lý bằng Subscription Dunning.
Lý do giao dịch thất bại
Bảng sau liệt kê mọi mã thất bại, loại từ chối, việc customer có thể tự khắc phục hay không, mô tả và hành động đề xuất.Lỗi do người dùng cho biết việc customer có thể tự khắc phục tình trạng payment bị từ chối hay không. Khi
Yes, customer có thể thực hiện hành động để sửa lỗi (ví dụ nhập đúng thông tin thẻ). Khi No, việc từ chối là do vấn đề cấp hệ thống hoặc hạn chế từ ngân hàng mà customer không thể trực tiếp khắc phục.Thẻ cũng có thể bị từ chối khi risk engine của chính ngân hàng phát hành đánh dấu chủ thẻ là customer có rủi ro cao — không phụ thuộc vào merchant hoặc chi tiết giao dịch. Những lần từ chối này thường xuất hiện dưới dạng các mã chung như
DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED hoặc FRAUDULENT. Trong các trường hợp này, ngân hàng không chia sẻ lý do cụ thể và cả Dodo Payments lẫn merchant đều không thể override quyết định. Yêu cầu customer liên hệ ngân hàng để giải quyết cờ đánh dấu hoặc sử dụng thẻ hay payment method khác.Xử lý lỗi bằng chương trình
Đọcerror_code từ webhook payment.failed hoặc payment object, ánh xạ mã này với hành động đề xuất ở trên và quyết định có thử lại hay không. Đối với các lần gia hạn subscription, các trường hợp từ chối mềm sẽ được tự động thử lại — xem Subscription Payment Retries.
Đối với các lỗi ở cấp API và lỗi logic nghiệp vụ (chẳng hạn như PAYMENT_NOT_SUCCEEDED hoặc REFUND_WINDOW_EXPIRED) không phải là lỗi từ chối thẻ, hãy xem tài liệu tham khảo Error Codes.
Liên quan
Handle Payment Failures
Hướng dẫn end-to-end về cách phát hiện, hiển thị và thử lại các payment thất bại.
Error Codes
Mã lỗi API và lỗi logic nghiệp vụ cho các lỗi không phải từ chối.
Subscription Payment Retries
Tự động thử lại để khắc phục các trường hợp từ chối mềm trong quá trình gia hạn subscription.
Subscription Dunning
Các chuỗi email khắc phục trường hợp từ chối cứng bằng cách nhắc cập nhật payment method.